The MCP Ecosystem

How MCP (Model Context Protocol) servers integrate into Claude Code — from discovery through authentication to tool execution. This is the extensibility backbone: any external tool, resource, or command can be registered via MCP and used alongside built-in tools.

The five layers

1. Discovery: where are the servers?

MCP servers are discovered from 7 configuration scopes with defined precedence:

claudeai (lowest) → plugins → user → project → local → dynamic → enterprise (highest)

• User settings (~/.claude/settings.json) — personal servers
• Project settings (.mcp.json in project root) — shared team servers, requires explicit approval
• Enterprise (managed-mcp.json) — takes exclusive control, all other scopes ignored
• Plugins — servers bundled with installed plugins
• Claude.ai connectors — hosted connectors fetched from Claude.ai

Three deduplication strategies prevent the same server from appearing twice: plugin dedup (by command/URL signature), claude.ai dedup, and CCR proxy URL unwrapping.

2. Connection: how do they connect?

8 transport types cover every deployment scenario:

Connection management uses exponential backoff reconnection (1s initial, 30s max, 5 attempts) for remote transports. State updates are batched at 16ms intervals to prevent UI thrashing when many servers connect simultaneously.

3. Authentication: how do they auth?

Two OAuth flows:

• Standard OAuth PKCE (performMCPOAuthFlow) — browser-based authorization code flow with PKCE. Local HTTP server on localhost for callback. 5-minute timeout. Manual code paste fallback for remote environments.
• XAA enterprise SSO (performMCPXaaAuth) — one IdP login reused across all XAA-configured servers. RFC 8693 token exchange + RFC 7523 jwt-bearer grant (no browser needed).

Tokens stored in platform keychain, not config files. Auth probe results cached 15 minutes to avoid repeated failures. Step-up auth handles 403 insufficient_scope by forcing PKCE re-auth instead of useless token refresh.

Vendor normalization fixes non-standard OAuth errors (e.g., Slack's invalid_refresh_token → standard invalid_grant).

4. Tool conversion: how do MCP tools become Claude Code tools?

MCP tools are converted to native Tool objects by spreading the MCPTool template:

• Name prefixing — mcp__<server>__<tool> prevents collisions (unless CLAUDE_AGENT_SDK_MCP_NO_PREFIX)
• Description capping — truncated at 2,048 chars
• Behavioral hints — MCP readOnlyHint → isConcurrencySafe, destructiveHint → isDestructive
• LRU cache — tool lists cached (size 20) to avoid re-fetching on every call

Tool pool assembly: built-in tools form a sorted prefix, MCP tools form a sorted suffix. This partitioning preserves prompt cache when MCP servers change. Built-in tools win on name conflicts.

5. Execution: how do MCP tool calls work?

1. ensureConnectedClient() verifies or re-establishes connection
2. callMCPToolWithUrlElicitationRetry() executes with signal and progress callback
3. On McpSessionExpiredError (HTTP 404, JSON-RPC -32001), retries once
4. Default timeout: ~27.8 hours (DEFAULT_MCP_TOOL_TIMEOUT_MS = 100_000_000)

Error handling: McpAuthError transitions server to needs-auth state. McpToolCallError surfaces as tool_result is_error=true. All errors produce conversation messages, never crashes.

Policy enforcement

• Deny list — block servers by name, command, or URL pattern (wildcard *)
• Allow list — enterprise allowlist
• Plugin-only mode — blocks all non-plugin servers
• Project approval — .mcp.json servers require explicit approval before connecting
• Enterprise takeover — managed-mcp.json takes exclusive control

Change notification

When a server notifies that its tools/prompts/resources changed (ToolListChangedNotification, etc.), the cache is invalidated and tools are re-fetched. This enables dynamic tool registration without reconnection.

Design tensions

1. 7 scopes — flexible but complex. Enterprise override simplifies managed environments at the cost of user freedom.
2. Tool name prefixing — prevents collisions but makes tool names verbose and unfamiliar.
3. Cache partitioning — MCP as suffix preserves built-in cache, but all MCP tool cache breaks when any server changes.
4. Very long default timeout — prevents premature timeout on slow tools but masks broken connections.

Related entities

• mcp-subsystem — architecture overview
• mcp-client — transport and connection
• mcp-server-discovery — configuration loading
• mcp-auth — OAuth and XAA authentication
• mcp-runtime-management — connection lifecycle
• tool-system — tool pool assembly
• cache-economics — why registration order matters