Guides

Claude Code MCP setup: add, share and troubleshoot MCP servers

Published October 30, 2026 · Last checked October 30, 2026

MCP (the Model Context Protocol) is an open standard for connecting AI tools. An MCP server gives Claude Code direct access to your tools, databases and APIs, so you stop copying data into the chat. This page is the step-by-step: which command each of the three transports uses, where the configuration is stored, how to share it with a team, how to authenticate, and what to check when it fails. It follows Anthropic's Connect Claude Code to tools via MCP, checked against that page on October 30, 2026.

What MCP is and when to connect a server

MCP servers give Claude Code access to your tools, databases and APIs. Connect one when you find yourself copying data into the chat from another tool, such as an issue tracker or a monitoring dashboard. Once it is connected, Claude can read and act on that system directly instead of working from what you paste.

Security: verify that you trust each server before connecting it. Servers that fetch external content can expose you to prompt injection risk.

Adding a server for each transport

Every method uses claude mcp add. Start from what the server gives you: an https:// address is a remote server, and a launch command such as npx is a server that runs on your machine.

Remote HTTP server

# Basic syntax
claude mcp add --transport http <name> <url>

# Real example: Connect to Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Example with Bearer token
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

In JSON configuration, the type field accepts streamable-http as an alias for http. A JSON entry that has a url but no type is a configuration error: Claude Code reads an entry with no type as a stdio server and skips it.

Remote SSE server

The SSE (Server-Sent Events) transport is deprecated; use HTTP where available. Some services still expose only an SSE endpoint. Add those with the same claude mcp add --transport http <name> <url> command: Claude Code tries HTTP first and switches to SSE when the server does not accept it. That automatic switch requires Claude Code v2.1.265 or later. On an earlier version, or to connect over SSE directly, pass --transport sse:

# Basic syntax
claude mcp add --transport sse <name> <url>

# Real example: Connect to Asana
claude mcp add --transport sse asana https://mcp.asana.com/sse

# Example with authentication header
claude mcp add --transport sse private-api https://api.company.com/sse \
  --header "X-API-Key: your-key-here"

Local stdio server

Stdio servers run as local processes on your machine.

# Basic syntax
claude mcp add [options] <name> -- <command> [args...]

# Real example: Add Airtable server
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

• The -- (double dash) separates Claude's own options, such as --transport, --env and --scope, from the command and arguments that run the server. Everything after -- is passed to the server untouched. Without it, Claude Code would try to parse the server's flags, like --port, as its own options.
• claude mcp add --env KEY=value --transport stdio myserver -- python server.py --port 8080 runs python server.py --port 8080 with KEY=value in the environment.
• --env accepts multiple KEY=value pairs. If the server name comes directly after --env, the CLI reads the name as another pair and rejects it, so place at least one other option, such as --transport stdio, between --env and the server name.

Converting instructions written for another client

A server's setup instructions may be written for Claude Desktop, Cursor or another MCP client and give no claude mcp add command. Look in them for a URL, a launch command or a JSON block:

• A URL such as https://mcp.example.com/mcp: the server is remote. Use claude mcp add --transport http example https://mcp.example.com/mcp.
• A launch command such as npx -y @example/mcp-server: the server runs on your machine. Put the whole command after --: claude mcp add example --env API_KEY=your-key -- npx -y @example/mcp-server.
• An mcpServers JSON block: pass claude mcp add-json the object inside mcpServers, not the wrapper:

claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'

With add-json, a url entry with no type needs "type": "http", "type": "sse" or "type": "ws" added first. WebSocket servers are configured in .mcp.json or with claude mcp add-json, because claude mcp add --transport does not accept ws. A server name can contain only letters, numbers, hyphens and underscores.

Scopes: where the configuration is stored

MCP servers can be configured at three scopes. The scope controls which projects the server loads in and whether the configuration is shared with your team. Choose it with -s or --scope; the default is local.

# Local scope
claude mcp add --transport http stripe --scope local https://mcp.stripe.com

# Project scope
claude mcp add --transport http shared-server --scope project https://example.com/mcp

# User scope
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

A local-scoped server is stored in ~/.claude.json under that project's path, so it does not appear in your other projects. Use it for personal development servers, experimental configurations, and servers with credentials you do not want in version control. Note that "local scope" for MCP servers differs from the general local settings file, .claude/settings.local.json.

When the same server is defined in more than one place, Claude Code connects to it once, using the definition from the highest-precedence source. The entire entry is used; fields are not merged across scopes. The order, highest first: local scope, project scope, user scope, plugin-provided servers, claude.ai connectors.

Sharing a server with your team through .mcp.json

Project scope stores the configuration in a .mcp.json file at the project's root. When you add a project-scoped server, Claude Code creates or updates this file for you. Check it into version control so everyone on your team gets the same MCP tools.

{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

For security reasons, Claude Code prompts for approval in interactive sessions before using project-scoped servers from .mcp.json files. To reset those approval choices, run claude mcp reset-project-choices.

Environment variables in .mcp.json

.mcp.json supports environment variable expansion, so a team can share one configuration while machine-specific paths and sensitive values such as API keys stay in each person's environment. You can reference a variable in a server's command, args, env, url or headers value:

• ${VAR}: expands to the value of environment variable VAR.
• ${VAR:-default}: expands to the value of VAR if it is set, or to default if it is unset.

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

If a referenced variable is not set and has no default, the config still loads: Claude Code reports a missing-variable warning in claude mcp list and uses the unexpanded ${VAR} text as-is. In a remote server's url and headers, credential variables such as ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN read as empty instead of expanding. To give the server one of those credentials, copy it into a variable with a name of your own and reference that name.

Listing, checking and removing servers

# List all configured servers
claude mcp list

# Get details for a specific server
claude mcp get notion

# Remove a server
claude mcp remove notion

# (within Claude Code) Check server status
/mcp

On success, claude mcp add prints an Added ... line, which means the configuration was written. It does not validate credentials, so a placeholder token is accepted and the server fails to connect later. To check that Claude Code really connected, run claude mcp get <name>, or run /mcp in Claude Code and look for a checkmark on the server's row.

claude mcp list shows a health status next to each server:

When you remove a remote server, Claude Code also deletes the OAuth tokens and client registration it stored for that server, but it does not revoke the tokens at the authorization server. Where the authorization server supports revocation, run claude mcp logout <name> in your shell before claude mcp remove <name>.

To stop using a server without losing its configuration, toggle it off in the /mcp panel. Claude Code stops connecting to it and keeps the configuration.

Authenticating with remote servers

Many cloud-based MCP servers require authentication, and Claude Code supports OAuth 2.0. It marks a remote server as needing authentication when the server responds with 401 Unauthorized or 403 Forbidden.

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

Then run /mcp inside Claude Code and follow the steps in your browser to log in.

• Authentication tokens are stored securely and refreshed automatically.
• Use "Clear authentication" in the /mcp menu to revoke access.
• If your browser does not open automatically, copy the provided URL and open it manually.
• If the browser redirect fails with a connection error after authenticating, paste the full callback URL from your browser's address bar into the URL prompt that appears in Claude Code.
• OAuth authentication works with HTTP servers.

To sign in without opening a session, run the flow from your shell:

claude mcp login sentry

To clear stored credentials later, run claude mcp logout <name>. In an SSH session or on Linux without a display server, claude mcp login detects that no local browser is available and prints the authorization URL instead of opening one: open the URL on your local machine, then paste the full redirect URL from your browser's address bar back at the prompt. That step needs an interactive terminal, so connect with ssh -t. Pass --no-browser to force the URL prompt even when a local browser is detected.

If you configured headers.Authorization for the server and the server rejects it, Claude Code reports the connection as failed instead of falling back to OAuth. Check that the token is valid for the MCP endpoint, or remove the header to use the OAuth flow. A claude -p or Agent SDK run has no /mcp panel, so sign in first from an interactive session, or with claude mcp login <name>.

Timeouts and output limits

• Set the startup timeout with the MCP_TIMEOUT environment variable; for example, MCP_TIMEOUT=10000 claude sets 10 seconds.
• To limit a tool call for one server, add a timeout field in milliseconds to that server's .mcp.json entry, for example "timeout": 600000 for ten minutes. It overrides the MCP_TOOL_TIMEOUT environment variable for that server only.
• Claude Code displays a warning when MCP tool output exceeds 10,000 tokens and limits output to 25,000 tokens by default. To raise the limit, set MAX_MCP_OUTPUT_TOKENS in your shell before starting Claude Code:

export MAX_MCP_OUTPUT_TOKENS=50000
claude

The warning threshold is fixed. Unless the server raises a tool's own limit, successful text results longer than 50,000 characters are saved to a file regardless of this variable.

Troubleshooting

FAQ

Sources

• Claude Code: Connect Claude Code to tools via MCP (claude mcp add, scopes, .mcp.json, authentication, output limits; checked October 30, 2026)