Model Context Protocol (MCP)

Connect Claude Code to external tools, data sources, and services via the Model Context Protocol — an open standard for AI-application integration.

MCP support is implemented in src/services/mcp/. Servers are discovered at startup and their tools, resources, and prompts are merged into Claude Code's runtime.

How It Works

  MCP Server Config (JSON or inline)
       │
       ▼
  ┌─ MCP Manager (src/services/mcp/)
  │    • Server connection lifecycle
  │    • Tool discovery via tools/list
  │    • Resource access via resources/read
  │    • Paginated responses
  │
  ├─ Tool Pool (assembleToolPool)
  │    • MCP tools merged with built-in tools
  │    • Availability toggled by permission rules
  │
  └─ Query Loop
       • Model sees MCP tools alongside built-ins
       • Tool calls routed to the appropriate MCP server

MCP Commands

CLI Configuration

MCP servers are configured at startup via CLI flags:

# Load servers from a JSON config file
  claude --mcp-config ./mcp-servers.json

  # Load multiple configs
  claude --mcp-config ./servers.json ./extra.json

  # Pass inline JSON
  claude --mcp-config '{"servers":{...}}'

  # Strict mode (only use MCP servers, no built-ins)
  claude --strict-mcp-config

MCP Server Config Format

Each MCP server is defined with a command, arguments, and environment variables:

{
    "servers": {
      "filesystem": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
        "env": {}
      },
      "database": {
        "command": "node",
        "args": ["./mcp/db-server.js"],
        "env": { "DB_URL": "postgresql://..." }
      }
    }
  }

Tool Discovery

When an MCP server connects, Claude Code:

1. Sends tools/list to discover available tools
2. Merges discovered tools into the global tool pool via assembleToolPool()
3. Handles paginated responses for servers with many tools
4. Makes tools available to the model alongside built-in tools

MCP-provided tools inherit their schemas from the server and go through the same permission gating and hook system as built-in tools.

Resources

MCP servers can also expose resources — structured data that Claude Code can read:

• ListMcpResources — List available resources from all connected servers
• ReadMcpResource — Read a specific resource by URI

Resources are useful for accessing database schemas, API documentation, configuration files, and other structured data through MCP servers.

Plugin-Bundled MCP Servers

Plugins can declare MCP servers in their manifest. These are automatically started when the plugin is loaded and stopped when the plugin is unloaded. See Plugins for details.

Architecture Files