# Claude Code MCP Integration In addition to the built-in tools, [[Claude Code]] supports [[Model Context Protocol (MCP)]]. Use the `--mcp-config <path>` CLI flag to load MCP servers from a JSON file or string. Since 2025-06, Claude Code also supports remote MCP servers: https://www.anthropic.com/news/claude-code-remote-mcp ## Tool naming convention MCP tools surface in Claude Code as `mcp__<server>__<tool>` — e.g. `mcp__github__create_issue`, `mcp__puppeteer__puppeteer_navigate`. This naming flows through every governance surface: - Permission rules: `mcp__github`, `mcp__github__*`, `mcp__github__create_issue` - Hook matchers: `"matcher": "mcp__github"` (catches every github tool) - `allowedTools` / `disallowedTools` in skills and subagents - Tool reference in error messages ## Configuration scopes | Scope | File | When to use | |-------|------|-------------| | Project | `.mcp.json` (repo root, checked in) | Servers the team needs for this codebase | | Project local | `.mcp.local.json` (gitignored) | Personal servers, secrets, local-only experiments | | User | `~/.claude.json` | Servers genuinely useful across every project | | Runtime override | `--mcp-config <path>` flag | Ad-hoc / scripted launches | **Token cost rule**: every globally-configured MCP server consumes context tokens at session start (its tool descriptions are loaded). Scope per-project unless truly universal — a forgotten server in `~/.claude.json` taxes every session forever. ### Project config example (`.mcp.json`) ```json { "mcpServers": { "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_TOKEN" } }, "database": { "command": "node", "args": ["~/.claude/mcp/db-server.js", "--db", "production"] } } } ``` ## Deferred tool loading To prevent MCP tool schemas from inflating the system prompt, Claude Code defers them: only **tool names** load at startup, while **full schemas fetch on-demand** via the `ToolSearch` tool when Claude actually needs to invoke an MCP tool. This keeps context lean even with dozens of MCP servers configured. Inspect overhead with `/context`. ## Remote MCP servers Remote servers (HTTPS endpoints) support: - **Streamable HTTP transport** — efficient for long-running tool calls - **OAuth 2.1 with PKCE** — modern auth flow without baked-in tokens Add via `claude mcp add --transport sse <name> <url>` (SSE / streaming) or `claude mcp add --transport http <name> <url>`. ## Tool inheritance gotcha **MCP servers do NOT inherit Claude Code's built-in tools.** A server has access only to tools it explicitly exposes. If your server needs file I/O or shell exec, the server itself must implement those — `Read`/`Write`/`Bash` are NOT automatically available to MCP tool implementations. This is the most common confusion when wiring up custom servers. ## Configure MCP servers Managed using `claude mcp`: ``` serve [options] Start the Claude Code MCP server add [options] <name> <commandOrUrl> [args...] Add a server remove [options] <name> Remove an MCP server list List configured MCP servers get <name> Get details about an MCP server add-json [options] <name> <json> Add server with JSON string (stdio or SSE) add-from-claude-desktop [options] Import from Claude Desktop (Mac and WSL only) reset-project-choices Reset approved/rejected project-scoped servers help [command] Display help for command ``` Options for `add`: ``` -s, --scope <scope> Configuration scope: local, user, or project (default: "local") -t, --transport <transport> Transport type: stdio, sse (default: "stdio") -e, --env <env...> Set environment variables (e.g. -e KEY=value) -H, --header <header...> Set HTTP headers for SSE transport ``` ## Import from Claude Desktop Servers can be imported using `claude mcp add-from-claude-desktop` (macOS and WSL only). Under WSL, this command cannot import from Claude if Claude is not installed within WSL. Workaround: pass the path to the Windows config file: ```bash claude --mcp-config /c/Users/foo/AppData/Roaming/Claude/claude_desktop_config.json ``` This isn't remembered between sessions. Create an alias: ```bash alias claude='claude --mcp-config /c/Users/foo/AppData/Roaming/Claude/claude_desktop_config.json' ``` This breaks for MCP servers using Windows-specific paths. For those, manually add with `claude mcp add ...`. Example for [[Dockmaster]]: ```bash claude mcp add dockmaster /c/Users/foo/AppData/Local/MCP\ Dockmaster/mcp-proxy-server.exe ``` ## References - MCP docs: https://docs.anthropic.com/en/docs/claude-code/mcp - Remote MCP: https://www.anthropic.com/news/claude-code-remote-mcp ## Related - [[Claude Code]] - [[Claude Code Tools]] - [[Claude Code Plugins]] - [[Model Context Protocol (MCP)]]