Claude Code — MCP

Short answer to “how do I connect an MCP server to Claude Code”: run claude mcp add from your shell, then manage it in-session with /mcp.

Add a server

# Remote HTTP server (recommended transport)
claude mcp add --transport http <name> <url>
claude mcp add --transport http notion https://mcp.notion.com/mcp

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

# Remote SSE server
claude mcp add --transport sse <name> <url>

# Local stdio server — everything after -- goes to the server command
claude mcp add <name> -- <command> [args...]
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

# From a raw JSON definition (also how you add WebSocket servers: "type": "ws")
claude mcp add-json <name> '<json>'

Notes:

• --transport accepts http, sse, stdio — not ws. WebSocket servers go in via .mcp.json or add-json with "type": "ws". streamable-http is an accepted alias for http in JSON configs.
• A JSON entry with a url but no type is an error (treated as stdio and skipped with a warning).
• claude mcp add saves the config without validating credentials — check claude mcp list afterwards.

Scopes

Scope	Stored in	Visibility
local (default)	~/.claude.json (per-project)	You, this project only
project	.mcp.json at the project root	Committed, shared with the team; requires interactive approval (skipped in -p/SDK/cloud sessions)
user	~/.claude.json	You, all projects

Same-name precedence: local > project > user > plugin > claude.ai connectors.

Project config: .mcp.json

Commit this at the repo root to share servers with the team. Supports ${VAR} and ${VAR:-default} expansion in command, args, env, url, and headers:

{
  "mcpServers": {
    "notion": {
      "type": "http",
      "url": "https://mcp.notion.com/mcp"
    },
    "airtable": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "airtable-mcp-server"],
      "env": {
        "AIRTABLE_API_KEY": "${AIRTABLE_API_KEY}"
      }
    }
  }
}

Manage servers

claude mcp list                    # status: Connected / Needs authentication / Failed to connect / Pending approval
claude mcp get <name>              # details for one server
claude mcp remove <name>           # remove (--scope to target a scope)
claude mcp reset-project-choices   # reset .mcp.json approval choices
claude mcp login                   # authenticate MCP servers from the shell
claude mcp add-from-claude-desktop # import servers from Claude Desktop

In-session, /mcp opens the management panel: authenticate, reconnect, enable/disable (/mcp reconnect <server>, /mcp enable|disable [<server>|all]).

After connecting

• Tools appear as mcp__<server>__<tool> (plugin-bundled: mcp__plugin_<plugin>_<server>__<tool>).
• MCP prompts become slash commands: /mcp__<server>__<prompt>.
• Tool search (MCPSearch) is on by default and kicks in when tools would exceed 10% of the context window (ENABLE_TOOL_SEARCH=auto).
• Timeouts: MCP_TIMEOUT (startup), MCP_TOOL_TIMEOUT (default ~28h), idle timeout 5 min remote / 30 min stdio (CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT); main-conversation MCP calls auto-background after 2 minutes (v2.1.212+).
• Reserved server names you can’t use: workspace, claude-in-chrome, computer-use, Claude Preview, Claude Browser.
• Enterprise control: allowedMcpServers / deniedMcpServers in managed settings; per-project toggles via enableAllProjectMcpServers, enabledMcpjsonServers, disabledMcpjsonServers (see Claude Code — Configuration).

---

Last verified: 2026-09-07

Official sources:

• https://code.claude.com/docs/en/mcp.md
• https://docs.claude.com/en/docs/claude-code/mcp
• https://docs.claude.com/en/docs/claude-code/settings

AI coding tools evolve quickly. If you find outdated information, please open an issue or pull request.