MCP Server Integration

Relevant source files

• CHANGELOG.md
• LICENSE.md
• README.md
• demo.gif
• feed.xml
• plugins/plugin-dev/skills/mcp-integration/SKILL.md

This document explains how Claude Code integrates with the Model Context Protocol (MCP) to extend its capabilities through external tools, prompts, and resources. MCP servers enable Claude Code to interact with external systems like GitHub, databases, APIs, and custom services through a standardized protocol.

For information about the general tool execution pipeline and permission system, see Tool System & Permissions. For details about the plugin system that can bundle MCP servers, see Plugin System.

MCP Architecture in Claude Code

MCP (Model Context Protocol) is a standardized protocol that allows Claude Code to communicate with external servers. This integration enables Claude to interact with external services without requiring built-in implementations for every possible integration.

Data Flow and Entity Mapping

The following diagram bridges the natural language request for an MCP tool to the specific code entities and transport mechanisms used to fulfill it.

Diagram: MCP Request Lifecycle and Entity Mapping

MCP Architecture Overview

The MCP integration consists of three main layers:

1. MCP Infrastructure: Connection management, transport protocols (stdio, SSE, HTTP, WebSocket), and tool caching.
2. MCP Servers: External services implementing the MCP protocol, including remote claude.ai connectors and local processes.
3. Integration Points: Discovery and invocation of MCP tools, which are automatically prefixed for namespacing.

Configuration File Locations

• User-level: ~/.claude/mcp-servers.json
• Project-level: .claude/mcp-servers.json
• Plugin-bundled: Dedicated .mcp.json at plugin root or inline mcpServers field in plugin.json plugins/plugin-dev/skills/mcp-integration/SKILL.md23-59

claude.ai MCP Connectors

Claude Code supports using MCP connectors from claude.ai, enabling access to remote MCP servers configured in your claude.ai account. Note that claude.ai MCP connectors are disabled when a manual ANTHROPIC_API_KEY is set. Startup notices inform users of connectors that require authentication CHANGELOG.md54

Sources: plugins/plugin-dev/skills/mcp-integration/SKILL.md23-59 CHANGELOG.md54

MCP Server Configuration

MCP servers are defined by how they are launched and how they authenticate.

Diagram: Configuration Schema to Transport Mapping

Configuration Methods for Plugins

Plugins can bundle MCP servers in two ways:

1. Dedicated .mcp.json (Recommended): Clearer separation of concerns for multiple servers plugins/plugin-dev/skills/mcp-integration/SKILL.md23-37
2. Inline in plugin.json: Convenient for simple single-server plugins using the mcpServers field plugins/plugin-dev/skills/mcp-integration/SKILL.md44-59

Configuration Management Commands

Command	Purpose	Notes
/mcp	Interactive MCP Management Dialog	Browse and manage servers; shows HTTP status and error text if a server fails to connect CHANGELOG.md16
claude mcp list	CLI server status	Displays HTTP status and error text for connection failures CHANGELOG.md16
claude mcp get	View specific server	Shows status and details of a specific MCP server.

Validation and Error Handling

• Headless stream-json init events include mcp_server_errors for config entries skipped by validation CHANGELOG.md12
• Terminal runs print a startup warning for invalid MCP configurations CHANGELOG.md12
• A warning is issued for MCP config values containing hidden leading or trailing whitespace CHANGELOG.md16

Sources: plugins/plugin-dev/skills/mcp-integration/SKILL.md23-59 CHANGELOG.md12-16

Transport Types

Claude Code supports four primary transport mechanisms for MCP communication plugins/plugin-dev/skills/mcp-integration/SKILL.md65-166:

Type	Protocol	Best For	Process Management
stdio	Local Stdin/Stdout	Local tools, custom servers	Claude Code spawns child process. Terminates when Claude Code exits plugins/plugin-dev/skills/mcp-integration/SKILL.md91-93
SSE	Server-Sent Events	Hosted cloud services	OAuth handled automatically plugins/plugin-dev/skills/mcp-integration/SKILL.md115-118
HTTP	REST API	Stateless interactions	Uses standard HTTP headers for Authorization plugins/plugin-dev/skills/mcp-integration/SKILL.md120-136
WebSocket	Real-time Bidirectional	Low-latency requirements	Persistent connection with wss:// support plugins/plugin-dev/skills/mcp-integration/SKILL.md144-160

Environment Variable Expansion All MCP configurations support variable substitution, including ${CLAUDE_PLUGIN_ROOT} for plugin portability plugins/plugin-dev/skills/mcp-integration/SKILL.md167-176 Managed MCP allowlist/denylist entries resolve ${VAR} from the startup environment and managed-settings env CHANGELOG.md27

Sources: plugins/plugin-dev/skills/mcp-integration/SKILL.md65-188 CHANGELOG.md27

Tool Discovery and Registration

MCP tools are automatically prefixed to avoid name collisions and provide context to the model.

Naming Format: mcp__plugin_<plugin-name>_<server-name>__<tool-name> plugins/plugin-dev/skills/mcp-integration/SKILL.md194-200

Registration and Discovery Process

1. Plugin Loading: Claude Code parses MCP configuration from plugin.json or .mcp.json plugins/plugin-dev/skills/mcp-integration/SKILL.md231-233
2. Connection: Server process is started (stdio) or connection established (SSE/HTTP/WS) plugins/plugin-dev/skills/mcp-integration/SKILL.md234
3. Discovery: Tools are discovered via the protocol and registered with the agent plugins/plugin-dev/skills/mcp-integration/SKILL.md235
4. Availability: Tools become available to the agent using the namespaced prefix plugins/plugin-dev/skills/mcp-integration/SKILL.md236-237

Sources: plugins/plugin-dev/skills/mcp-integration/SKILL.md194-237

Authentication and OAuth

Claude Code manages authentication flows to ensure secure access to external services.

1. OAuth (SSE/HTTP): Handled automatically by Claude Code. The user is prompted to authenticate in a browser on first use plugins/plugin-dev/skills/mcp-integration/SKILL.md243-254
2. Token-Based (Headers): Supports static or environment variable tokens passed via the headers field in the configuration plugins/plugin-dev/skills/mcp-integration/SKILL.md256-270
3. Environment Variables (stdio): Authentication credentials can be passed directly to local server processes via the env field plugins/plugin-dev/skills/mcp-integration/SKILL.md272-287

Sources: plugins/plugin-dev/skills/mcp-integration/SKILL.md243-287

Permission and Security

MCP tools integrate with Claude Code's standard permission system.

• Pre-allowing Tools: Commands can specify allowed MCP tools in their frontmatter using the full namespaced name to avoid repeated prompts plugins/plugin-dev/skills/mcp-integration/SKILL.md204-214
• Wildcard Matching: Permission rules support wildcard matching (e.g., mcp__plugin_asana_asana__*) plugins/plugin-dev/skills/mcp-integration/SKILL.md218-221
• Managed Settings: Benign feature toggles and cost-related settings in server-managed environments no longer trigger settings-approval prompts CHANGELOG.md67

Sources: plugins/plugin-dev/skills/mcp-integration/SKILL.md204-221 CHANGELOG.md67