Add MCP servers to Claude Code (claude mcp add, .mcp.json, scopes)

HTTP is the recommended transport for remote servers. Stdio servers run as local processes on your machine. For stdio, the -- separator splits Claude's own options (such as --transport, --env, and --scope) from the command that starts the server. Everything after -- goes to the server untouched.

# Remote HTTP server
claude mcp add --transport http notion https://mcp.notion.com/mcp

# HTTP server with a Bearer token header
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

# Local stdio server with an environment variable
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

• Set environment variables with -e or --env, for example -e KEY=value.
• If the server name comes right after --env, the CLI reads the name as another pair and rejects it. Put another option, such as --transport stdio, between --env and the name.
• --transport and --header also accept the short forms -t and -H.
• SSE is deprecated. You can still pass --transport sse to connect to an SSE-only server.
• If you already have a JSON config for a server, add it with claude mcp add-json NAME 'JSON'.

Use -s or --scope to choose one of three scopes. Local (the default) loads only in the current project and is stored in ~/.claude.json. Project is stored in .mcp.json at the project root, so your team gets it through version control. User is also stored in ~/.claude.json but loads in all your projects. When the same server name is defined in more than one scope, local wins over project, and project wins over user.

claude mcp add --transport http shared-server --scope project https://example.com/mcp
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

.mcp.json supports ${VAR} and ${VAR:-default} expansion in command, args, env, url, and headers. Always set type on a remote entry: an entry with a url but no type is a configuration error, because Claude Code treats an entry with no type as a stdio server.

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    },
    "local-weather": {
      "type": "stdio",
      "command": "/path/to/weather-cli",
      "args": ["--api-key", "${WEATHER_API_KEY}"],
      "env": { "CACHE_DIR": "/tmp" }
    }
  }
}

• Claude Code asks you to approve project-scoped servers from .mcp.json before it uses them. Reset those choices with claude mcp reset-project-choices.
• If a referenced variable is unset and has no default, the server still loads with the literal ${VAR} text, and claude mcp list shows a warning.

Claude Code supports OAuth 2.0 for remote servers. After you add a server that needs sign-in, run /mcp inside Claude Code and finish the login in your browser. Tokens are stored securely and refresh automatically. Use Clear authentication in the /mcp menu to revoke access.

claude mcp list
claude mcp get notion
claude mcp remove notion
claude mcp login sentry
claude mcp logout sentry

Removing a remote server also deletes the OAuth tokens Claude Code stored for it. To remove a definition from one scope, run claude mcp remove NAME --scope SCOPE.

• MCP_TIMEOUT sets the server startup timeout in milliseconds, for example MCP_TIMEOUT=10000 claude.
• MCP_TOOL_TIMEOUT sets the tool execution timeout. Override it for one server with a timeout field (milliseconds) in that server's .mcp.json entry.
• Claude Code warns when MCP tool output goes over 10,000 tokens and caps it at 25,000 tokens by default. Raise the cap with MAX_MCP_OUTPUT_TOKENS.

export MAX_MCP_OUTPUT_TOKENS=50000
MCP_TIMEOUT=10000 claude