Home › Entities › MCP Integration

MCP Integration

What it is

The Model Context Protocol (MCP) integration is Claude Code's primary extensibility mechanism — a full 24-file protocol implementation (300KB+) supporting stdio, SSE, and WebSocket transports. The MCP client alone is 119K lines, making it the most complete MCP implementation in existence. Any server implementing the MCP protocol can register tools, expose resources, and push notifications into a Claude Code session.

Claude Code doesn't overlay MCP — it IS MCP. Every capability including Computer Use runs as a tool call through the same protocol. External servers adopt identical patterns.

Why it exists

Claude Code needed an extensibility model that could: 1. Integrate arbitrary external tools without modifying the core codebase 2. Preserve prompt cache economics — enterprise MCP setups add 55,000+ tokens before the first user message 3. Support multiple transport protocols — local tools via stdio, remote servers via SSE/WebSocket 4. Enable the channel system — channels (peer messaging, notifications) are implemented as MCP servers declaring experimental['claude/channel'] capability

The decision to make MCP foundational rather than a plugin layer means all tools — built-in and external — share the same dispatch, caching, and permission infrastructure.

What depends on it

Trade-offs and limitations

Context cost: Each MCP server's tool definitions consume tokens on every request. Five active servers can consume 55,000+ tokens. Community consensus: keep servers project-scoped to avoid context pollution.

Cache partitioning: MCP tools are appended after built-ins to avoid cache breaks. This makes registration order-dependent — adding/removing an MCP server invalidates the MCP tool cache but preserves the built-in prefix.

Tool documentation deduplication: A lightweight LLM side-query checks if the user has already seen a tool's description in the last N turns. If yes, docs are stripped from context. This saves tokens but adds latency.

Auth complexity: The auth module is 88KB — JWT + OAuth for server authentication. This is the second-largest file in the MCP subsystem.

Architecture

Key files

File Size Role
src/services/mcp/client.ts 119KB Full protocol client
src/services/mcp/auth.ts 88KB JWT + OAuth authentication
src/services/mcp/config.ts 51KB Server discovery, .mcp.json parsing
src/services/mcp/useManageMCPConnections.ts 44KB Server lifecycle hook

Dedicated MCP tools

Server discovery

Servers configured in .mcp.json (project-scoped) or ~/.claude.json (global):

{
  "mcpServers": {
    "server-name": {
      "command": "server-binary",
      "args": [],
      "env": {}
    }
  }
}

Three-Layer Tool Result Pattern

Production MCP servers should return data in three tiers: 1. Index — Fast, always-loaded references (~150 chars per entry) 2. Detailed data — Fetched on demand 3. Raw transcripts — Searched, never bulk-reloaded

Key claims

Relationships

Evidence

Open questions