Claude Code MCP: Add, Authenticate, and Use Servers

Updated Nov 21, 2026 · 10 min read · ntimer

Claude Code MCP support lets the coding agent use tools and data from local processes or remote services. Add a local server with a command after --, or add a hosted server with claude mcp add --transport http; then verify it, complete OAuth if required, and ask Claude to use its tools. Choose local, project, or user scope deliberately.

What does MCP give Claude Code?

MCP gives Claude Code structured access to tools and data outside its built-in capabilities, including issue trackers, databases, monitoring systems, and workflow services. After a server connects, Claude can discover its available tools and invoke relevant ones during a coding task.[1]

Without MCP, you may copy an issue, report, or time record into the conversation and manually carry the result back. With MCP, a server supplies named tools with structured inputs and results, so Claude can read or act through the integration. The Model Context Protocol guide explains the host-client-server design; this guide concentrates on Claude Code's current CLI.

Claude Code's documentation lists examples such as implementing work from an issue tracker, querying a database, analyzing monitoring data, and automating workflows.[1] Which actions are available depends entirely on the connected server and your permissions. Connecting a server does not make every action automatic: Claude Code can still ask you to approve tool use.

  • Use a local stdio server when a trusted program needs machine-local access or should run only for your Claude Code session.
  • Use a remote HTTP server when the service is hosted, shared across devices, or maintained by a provider.
  • Before connecting either type, verify the operator, inspect the requested access, and decide which configuration scope is appropriate.

How do I add a remote MCP server to Claude Code?

Run claude mcp add --transport http <name> <url> in your shell to register a remote MCP server. HTTP is Claude Code's recommended option for cloud services, and its http configuration maps to the specification's Streamable HTTP transport.[1][4]

bash
# General form
claude mcp add --transport http <name> <url>

# Example: ntimer at user scope
claude mcp add --transport http -s user ntime https://api.ntimer.app/mcp

Choose a short, recognizable name because Claude Code uses it in management commands and tool labels. The URL must be the service's actual MCP endpoint, not its marketing homepage. Claude Code accepts http as the CLI transport name; the MCP specification calls the standard binding Streamable HTTP, where messages are posted to one endpoint and replies use JSON or a request-scoped event stream.[4]

The example adds ntimer as ntime and uses -s user, the short form of --scope user, so the server is available across your projects. Omit the scope for a private current-project configuration, or use project scope only when the whole team should receive the same server definition. After the command reports that it saved the server, verify the connection instead of assuming “added” means “connected.”[2]

One remote endpoint, several coding workflows

At https://api.ntimer.app/mcp, ntimer offers timer, worklog, project-tree, report, mind-map, and mail-draft tools. The MCP server name in Claude Code commands is ntime. OAuth connects the tools to the account that approves access, without putting a static ntimer token in the command.

How do I add a local stdio MCP server?

Use claude mcp add [options] <name> -- <command> [args...] for a local server. Everything after the double dash belongs to the server process, while options before it configure Claude Code; stdio is the default local transport.[1]

bash
# General form
claude mcp add [options] <name> -- <command> [args...]

# Example from Claude Code's quickstart
claude mcp add playwright -- npx -y @playwright/mcp@latest

Claude Code launches a stdio server as a subprocess and communicates over its standard input and output. In the protocol specification, stdio frames newline-delimited messages through those streams; it does not open a network port.[4] When Claude Code disconnects, for example at the end of a session, it signals the process to exit and stops it if it does not.[1]

The -- separator is important. A flag after it, such as a script's --port, goes to the server command; without the separator, Claude Code may interpret that flag as its own. Put Claude Code options such as --scope, --transport, or --env before the server name and separator in the form documented for that command.[1]

Treat a local server command like any other program you install and execute. It runs with your operating-system permissions, so verify the package and restrict its access. Claude Code's security guidance recommends reviewing proposed commands and isolating higher-risk work involving untrusted content.[3]

Which Claude Code MCP scope should I use?

Use local for a private server in one project, project for a team-shared definition in .mcp.json, and user for a private server available across all your projects. Local is the default when you omit -s or --scope.[1][2]

Scope controls where Claude Code saves the server and who receives it.
ScopeWhere it is availableStorageUse it when
localOnly you, in the current projectThe current project's entry in ~/.claude.jsonTesting a server or keeping project-specific credentials private
projectEveryone using the repository after approval.mcp.json at the project rootThe team needs the same non-secret server definition
userOnly you, across all projectsThe top-level MCP configuration in ~/.claude.jsonA personal service or utility should follow you between repositories
bash
# Current project, private to you (default)
claude mcp add --transport http docs https://code.claude.com/docs/mcp

# Shared through the repository's .mcp.json
claude mcp add --scope project --transport http docs https://code.claude.com/docs/mcp

# Private to you, available in every project
claude mcp add --scope user --transport http docs https://code.claude.com/docs/mcp

Project scope is configuration-as-code, not a way to distribute secrets. Commit the .mcp.json definition only when teammates should inherit it; each teammate is prompted to approve project servers in an interactive trusted workspace.[1][2] Keep tokens out of tracked files. If the same name exists in several scopes, remove duplicates so it is obvious which endpoint Claude Code will load.

How do I list, inspect, or remove MCP servers?

Use claude mcp list to see configured servers and health, claude mcp get <name> to inspect one definition, and claude mcp remove <name> to delete it. Inside an interactive Claude Code session, /mcp shows connection, approval, and authentication controls.[1]

bash
claude mcp list
claude mcp get ntime
claude mcp remove ntime

# Run this inside Claude Code, not in your shell
/mcp

Run list immediately after adding a server. A connected status means it is ready; a needs-authentication status means the endpoint responded but requires sign-in; a failed status means Claude Code could not establish the connection. get gives the server-specific details you need to spot a wrong URL, command, transport, or scope.[1][2]

When you remove a remote server, Claude Code deletes the OAuth material it stored for that configuration, but the issuing authorization server may still retain the grant. To revoke the tokens at the authorization server, where it supports revocation, run claude mcp logout <name> before claude mcp remove <name>.[1] Add the same scope to remove when duplicate names exist and you need to target one definition.

How do I authenticate a Claude Code MCP server with OAuth?

After adding a protected HTTP server, authenticate from the /mcp menu in an interactive session or run claude mcp login <name> in your shell. Claude Code discovers the authorization service, obtains user approval, and stores credentials for later connections.[1][5]

bash
# Sign in from the shell
claude mcp login ntime

# Force a copy-and-paste URL flow on a headless machine
claude mcp login ntime --no-browser

# Clear stored credentials later
claude mcp logout ntime

The shell login command runs the configured server's OAuth flow without requiring you to open the interactive /mcp panel. If no display is available, Claude Code prints an authorization URL and asks you to paste the final redirect URL back into the terminal; --no-browser forces that flow.[1] This is useful over SSH, provided the shell is interactive.

MCP authorization for HTTP transports is based on OAuth. The protocol has the client discover protected-resource and authorization-server metadata, obtain an access token, and bind the request to the intended MCP resource.[5] Do not paste an OAuth access token into chat. If authentication expires, run login again or choose re-authentication in /mcp.

Authenticate ntimer

After claude mcp add --transport http -s user ntime https://api.ntimer.app/mcp, run claude mcp login ntime and approve the ntimer account you want Claude Code to use. Then check claude mcp list for a connected status before asking for a timer action.

How can Claude Code track a coding session through MCP?

Connect ntimer, ask Claude Code to start a timer against the correct work, have it send heartbeats while it codes, and stop the timer after verification. The server's structured tools record the session while heartbeat expiry prevents abandoned agent work from adding unlimited idle time.

  1. Add the endpoint: claude mcp add --transport http -s user ntime https://api.ntimer.app/mcp.
  2. Authorize it: claude mcp login ntime.
  3. Verify it: claude mcp list, then inspect details with claude mcp get ntime if it is not connected.
  4. Prompt Claude: Use `ntime_list_works` to find the matching work, then use `ntime_start` before changing code.
  5. Ask it to send ntime_heartbeat every few minutes during the task. The timer remains open while heartbeats arrive and closes at the last heartbeat after idleMinutes of silence, 30 minutes by default.
  6. After tests pass, ask Claude to call ntime_stop and report the recorded duration. Use ntime_status if you need to confirm no timer remains open.

Be explicit about the work or client when names could be ambiguous. Claude can create a missing work with ntime_add_work, but that is a write and should be intentional. Existing sessions can be logged, corrected, or removed with ntime_log, ntime_edit_session, and ntime_delete_session; reports come from ntime_report.

This workflow separates coding from accounting while keeping both in one conversation. The agent handles timer calls around the work, and you retain control over selection and corrections. For billable-session practices beyond MCP setup, read how to track billable hours, or create an ntimer account to try the remote server.

Why is my MCP server not working in Claude Code?

Start with claude mcp list, then inspect the named server with claude mcp get <name> and open /mcp. Most failures come from the wrong scope or endpoint, pending project approval, expired authorization, failed tool discovery, a local process that exits, or timeouts.[1][2]

Use the observed status to choose the smallest useful fix.
SymptomLikely causeWhat to do
Server is not listedAdded in another project or scope, removed, or saved under a different nameRun claude mcp list from the intended project; re-add with --scope user if it should be global
Pending approvalA project-scoped .mcp.json entry has not been trustedStart claude interactively in the project and approve the server at the prompt; if you dismissed it, run claude mcp reset-project-choices and restart[1][2]
Needs authenticationNo token, an expired grant, or rejected stored credentialsRun claude mcp login <name> or re-authenticate from /mcp[1]
Connected but tools do not showTool discovery failed, the server exposes no tools, or policy hides themUse claude mcp get <name> for the issue, inspect the tool count in /mcp, and check organization or permission rules[1][2]
Failed to connectWrong URL/transport, unreachable remote service, or local command exitedCompare the saved definition with the provider's docs; reconnect from /mcp after correcting it[1]
Startup times outThe server needs longer to initializeLaunch Claude Code with a larger startup window, such as MCP_TIMEOUT=60000 claude (the default is 30 seconds)[1][2]
A tool call times outThe operation exceeds the current per-server limitSet a suitable timeout in milliseconds on that server's MCP configuration and retry only after checking whether the first call changed data[1]

Do not repeatedly retry a write after an ambiguous timeout. First use a read tool to check whether the remote operation completed; otherwise you may create duplicate issues, messages, or time entries. For a connection problem, fix configuration before changing model prompts. The quickstart's status table distinguishes connected, connection-error, tools-fetch-failed, needs-authentication, failed, pending-approval, disabled, and policy-blocked states.[2]

Finally, treat unexpected tool output as untrusted input. Prompt injection is malicious text intended to override an assistant's instructions, and Anthropic recommends reviewing commands and proposed changes before approval.[3] A successful connection proves reachability, not the safety of every document the server returns.

Questions

What is the exact command to add an HTTP MCP server?

Run claude mcp add --transport http <name> <url> in your shell.[1] Replace the placeholders with a simple server name and the provider's MCP endpoint, then use claude mcp list to verify the connection.

Where does Claude Code store project MCP servers?

Project-scoped servers are stored in .mcp.json at the repository root and can be committed for teammates. Local and user scopes are stored in ~/.claude.json; local is tied to one project, while user is available across projects.[1][2]

Can Claude Code authenticate an MCP server without the /mcp menu?

Yes. Run claude mcp login <name> in an interactive shell.[1] On a headless or SSH machine, add --no-browser to print the authorization URL and paste the resulting redirect URL back into the terminal.

Why does a project MCP server require approval?

A repository can contain a project-scoped .mcp.json that asks Claude Code to connect to external services or launch local commands. Interactive approval lets you review that configuration before the server becomes active in the trusted workspace.[1][3]

Should I use local or user scope for ntimer?

Use user scope if you want your personal ntimer connection available across repositories; the documented command is claude mcp add --transport http -s user ntime https://api.ntimer.app/mcp. Use local scope only when you want it restricted to the current project.

Sources

  1. Connect Claude Code to tools via MCP, Anthropic. accessed Nov 21, 2026. Back
  2. Connect to MCP servers, Anthropic. accessed Nov 21, 2026. Back
  3. Security, Anthropic. accessed Nov 21, 2026. Back
  4. Transports: Overview, Model Context Protocol, 2026. accessed Nov 21, 2026. Back
  5. Authorization, Model Context Protocol, 2026. accessed Nov 21, 2026. Back

Related guides

00:00:00

Start the clock.

Start tracking