MCP Integration

How Claude Code connects to Model Context Protocol servers — discovery, connection, tool wrapping, and resource access. For how MCP tools fit into the broader tool pipeline, see Tool Sources.

What is MCP?

The Model Context Protocol (MCP) is an open standard for connecting AI models to external tools and data sources. Claude Code acts as an MCP client, connecting to MCP servers that expose tools and resources.

Server Types

Claude Code supports multiple MCP transport protocols:

Transport	How it Works	Use Case
stdio	Spawns a subprocess, communicates via stdin/stdout	Local tools (filesystem, git, etc.)
sse	HTTP Server-Sent Events	Remote servers
http	HTTP request/response	Simple remote APIs
ws	WebSocket	Bidirectional communication
sdk	In-process SDK	Embedded tools
claudeai-proxy	Claude.ai cloud proxy	Official cloud servers

Configuration

MCP servers are configured at multiple scopes, loaded in priority order:

Config Sources

User Config (~/.claude/mcp.json)

Project Config (.claude.json)

Local Config (.claude/local.json)

Additional Sources

Managed Config (Org policies)

Claude.ai (Official servers)

Result

Merge Configs → Active MCP Servers

Config Format

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@my-org/mcp-server"],
      "env": {
        "API_KEY": "..."
      }
    },
    "remote-server": {
      "url": "https://mcp.example.com/sse",
      "transport": "sse"
    }
  }
}

Connection Lifecycle

Each MCP server connection goes through distinct phases. The connection stays alive for the session and handles failures with automatic reconnection:

📋

Load config — parse mcp.json scopes

📡

Spawn / connect (stdio, sse, http, ws)

Failed — log warning, skip server

Connected — handshake OK

🔧

Discovery — tools/list + resources/list

🧩

Wrap as MCPTool instances, register in tool system

✅

Ready — accepting tool calls

Tool Call

⚙️

Execute on server

Result → tool_result

Server Crash

💥

Attempt reconnect

Re-discover tools

Session End

🛑

Kill subprocess / close

Cleanup complete

Tool Wrapping

MCP tools are wrapped as MCPTool instances and merged into the main tool registry:

Naming Convention

MCP tool names are prefixed to avoid collisions:

mcp__{server-name}__{tool-name}

For example, a tool search from server github becomes mcp__github__search.

Schema Translation

MCP tool input schemas (JSON Schema) are translated to match Claude Code's internal Zod-based validation.

Permission Integration

MCP tools go through the same permission system as built-in tools. Permission rules can match MCP tool names:

MCPTool(mcp__github__*)    # Allow all GitHub MCP tools
MCPTool(mcp__filesystem__write)  # Require approval for filesystem writes

Resource Access

MCP servers can also expose resources — named data sources that Claude can read:

• ListMcpResources tool — lists available resources from all connected servers
• ReadMcpResource tool — reads a specific resource by URI

Resources are useful for exposing databases, documentation, API schemas, or any structured data.

Error Handling

Scenario	Behavior
Server fails to start	Warning logged, server skipped
Server crashes mid-session	Attempt reconnection, log error
Tool call fails	Error returned as tool_result, model can adapt
Server timeout	Configurable timeout, error on expiry

Key Source Files

File	Purpose
src/services/mcp/client.ts	MCP client management
src/services/mcp/types.ts	MCP type definitions
src/services/mcp/config.ts	Config parsing and merging
src/tools/MCPTool/	Generic MCP tool wrapper
src/commands/mcp/	/mcp command UI