This document explains how Claude Code integrates with Model Context Protocol (MCP) servers 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 (Model Context Protocol) is a standardized protocol that allows Claude Code to communicate with external servers that provide tools, prompts, and resources. This integration enables Claude to interact with external services without requiring built-in implementations for every possible integration.
MCP Architecture Overview
The MCP integration consists of three main layers:
Configuration File Locations
~/.claude/mcp-servers.json.claude/mcp-servers.jsonplugins/**/mcp-servers.jsonclaude.ai MCP Connectors
Since version 2.1.46, Claude Code supports using MCP connectors from claude.ai, enabling access to remote MCP servers configured in your claude.ai account.
Sources: CHANGELOG.md106 CHANGELOG.md261 CHANGELOG.md405 CHANGELOG.md299 .github/workflows/oncall-triage.yml25-47
MCP servers are configured in the mcp-servers.json configuration file. Each server definition specifies how to launch and communicate with the server.
Configuration Structure Example
The GitHub MCP server configuration used in GitHub Actions workflows demonstrates the structure:
| Command | Purpose | Notes |
|---|---|---|
claude mcp add | Add a new MCP server configuration | Supports --client-id and --client-secret for OAuth |
claude mcp list | List configured MCP servers | Shows enabled/disabled status |
claude mcp get | View specific server configuration | Displays full server config |
claude mcp enable <name> | Enable a previously disabled server | Reconnects to server |
claude mcp remove | Remove MCP server configuration | Disconnects and removes config |
claude mcp | Interactive MCP Management Dialog | Browse and manage servers |
MCP Management Dialog
The MCP Management Dialog provides an interactive interface for managing MCP servers. Fixed in version 2.1.47 to properly display servers after deferred loading.
CLI Argument
MCP servers can also be specified via the --mcp-config flag, as demonstrated in the oncall-triage workflow:
Sources: .github/workflows/claude-issue-triage.yml20-42 .github/workflows/oncall-triage.yml25-47 .github/workflows/oncall-triage.yml116-118 CHANGELOG.md59 CHANGELOG.md252
MCP servers communicate with Claude Code through three transport mechanisms:
stdio Transport
The stdio transport spawns a child process and communicates via standard input/output pipes. This is the most common transport type, used for Docker containers, Node.js scripts, and executable binaries.
HTTP/SSE Transport
HTTP and Server-Sent Events (SSE) transports communicate with remote MCP servers over HTTP. These are particularly useful for streamable MCP servers that can handle long-lived connections.
Sources: CHANGELOG.md234 CHANGELOG.md261 CHANGELOG.md282
MCP tools are discovered and made available to Claude through a dynamic discovery system that balances context window usage with tool availability.
MCP Tool Naming Convention
All MCP tools are exposed to Claude with a prefix format: mcp__<servername>__<toolname>. For example:
mcp__github__get_issue - Get issue details from GitHub MCP servermcp__github__get_issue_comments - Get comments from an issuemcp__github__update_issue - Update an issue via GitHub MCP servermcp__github__list_issues - List issues with filtering/paginationmcp__github__search_issues - Search across issuesReal-World Usage Example
The .claude/commands/oncall-triage.md command demonstrates MCP tool usage patterns:
While this example uses the gh CLI tool wrapped in Bash, the GitHub Actions workflows use native MCP tools instead:
When MCP tool descriptions consume too much context window space, Claude Code automatically defers their loading and uses the MCPSearch tool for dynamic discovery. This is enabled by default since version 2.1.7.
Sources: .github/workflows/claude-issue-triage.yml106 .github/workflows/oncall-triage.yml118 .claude/commands/oncall-triage.md2 CHANGELOG.md458
The MCPSearch tool is a meta-tool that allows Claude to discover and enable MCP tools on-demand, reducing upfront context window usage.
MCPSearch Configuration
| Configuration | Default | Description |
|---|---|---|
| Auto-enable threshold | 10% | When MCP tool descriptions exceed this percentage of context window |
| Custom threshold syntax | auto:N | Set custom percentage (0-100) |
| Disable MCPSearch | Add to disallowedTools | Force all tools to load upfront |
Context Window Impact
The MCPSearch feature significantly reduces initial context usage for users with many MCP tools configured:
Configuration Options
| Setting | Value | Description |
|---|---|---|
| Default threshold | auto:10 | Auto-enable when tools exceed 10% of context |
| Custom threshold | auto:N | Where N is 0-100 percentage |
| Disable MCPSearch | Add MCPSearch to disallowedTools | Forces all tools to load upfront |
Performance Improvements
Sources: CHANGELOG.md434 CHANGELOG.md458 CHANGELOG.md25-27 CHANGELOG.md40
MCP servers that require OAuth authentication can be configured with pre-configured credentials or use Dynamic Client Registration (DCR).
Pre-configured OAuth Credentials
Added in version 2.1.30, some MCP servers (like Slack) don't support Dynamic Client Registration. For these servers, Claude Code allows pre-configured OAuth client credentials:
Example: Slack MCP Server
Authentication Failure Caching
To improve startup performance, version 2.1.49 introduced caching of authentication failures for HTTP and SSE MCP servers, avoiding repeated connection attempts to servers requiring auth.
Sources: CHANGELOG.md252 CHANGELOG.md21 CHANGELOG.md25
Claude Code's GitHub automation workflows extensively use MCP servers to interact with GitHub's API. This demonstrates MCP integration in a headless, CI/CD environment.
GitHub Automation Use Cases
| Workflow | MCP Server | Tools Used | Purpose |
|---|---|---|---|
| Issue Triage | github | get_issue, get_issue_comments, update_issue, search_issues | Automatically label issues based on content |
| Issue Deduplication | github | get_issue, search_issues, update_issue | Find and mark duplicate issues |
| Oncall Triage | github | list_issues, get_issue, get_issue_comments, update_issue | Identify critical blocking issues |
Configuration Example from Workflow
The oncall-triage workflow demonstrates full MCP setup in GitHub Actions:
The workflow then passes the config via --mcp-config and restricts allowed tools:
GitHub MCP Server Image
The workflows use a specific Docker image: ghcr.io/github/github-mcp-server:sha-7aced2b, which provides tools for issue and PR management.
Sources: .github/workflows/oncall-triage.yml25-47 .github/workflows/oncall-triage.yml116-118 .github/workflows/claude-issue-triage.yml28-38 .github/workflows/claude-issue-triage.yml104-106
MCP servers support dynamic lifecycle events that allow tools, prompts, and resources to be updated without restarting the connection.
list_changed Notifications
The list_changed notification allows MCP servers to notify Claude Code when their available tools, prompts, or resources have changed. This enables:
When a list_changed notification is received:
list_tools RPC call is made to the server| Event | Behavior |
|---|---|
| Server connection failure | Attempt reconnection with exponential backoff |
| Server process exits | Remove from active connections, require manual restart |
list_changed notification | Invalidate cache and reload tools |
| Orphaned process | Kill child process on Claude Code exit |
Previous versions of Claude Code had issues with orphaned MCP server processes:
mcp list and mcp get commands leaving orphaned processes CHANGELOG.md320Sources: CHANGELOG.md405 CHANGELOG.md320 CHANGELOG.md234
MCP tools follow the same permission system as built-in tools, allowing fine-grained control over which MCP tools Claude can use.
Restricting MCP Tools in Workflows
GitHub Actions workflows demonstrate how to restrict Claude to specific MCP tools for security:
This ensures Claude can only use explicitly allowed MCP tools, preventing unintended actions.
Subagent Access to MCP Tools
A bug fixed in 2.1.30 addressed subagents not being able to access SDK-provided MCP tools. The fix ensures that MCP tools are synced to shared application state, making them available to all agents and subagents CHANGELOG.md104
Sources: .github/workflows/claude-issue-triage.yml102-105 .github/workflows/oncall-triage.yml116-118 CHANGELOG.md104
MCP server configurations and tool names are sanitized to protect user privacy in analytics events.
Sanitization Measures
Fixed in 2.1.6: MCP tool names were being exposed in analytics events. The fix sanitizes user-specific server configurations before logging to prevent exposure of sensitive server names or configurations CHANGELOG.md370
Sources: CHANGELOG.md370
| Issue | Version Fixed | Description |
|---|---|---|
| Image content crash during streaming | 2.1.39 | MCP tools returning image content during streaming caused crashes |
| Subagent MCP tool access | 2.1.30 | Subagents couldn't access SDK-provided MCP tools due to state sync issues |
| Stdio timeout not killing process | 2.1.14 | Timeout didn't terminate child processes, causing UI freezes |
| Excessive HTTP/SSE connections | 2.1.11 | Too many connection requests to HTTP/SSE transports |
| Reconnection hanging | 2.1.9 | Cached connection promises never resolving caused hangs |
| Orphaned processes | 2.1.14 | mcp list/mcp get commands left zombie processes |
| Tool name exposure | 2.1.6 | MCP tool names leaked in analytics events |
Sources: CHANGELOG.md7 CHANGELOG.md104 CHANGELOG.md234 CHANGELOG.md261 CHANGELOG.md282 CHANGELOG.md320 CHANGELOG.md370
Refresh this wiki