MCP Integration System

1 What MCP Is in Claude Code

MCP (Model Context Protocol) is a standard for connecting AI models to external tools and data sources. Inside Claude Code, every MCP server is treated as a first-class tool supplier: its tools are registered with the same Tool interface as built-in tools like Write and Bash, just namespaced under mcp__<server>__<tool>.

The architecture is split across three layers:

2 Transport Types

The type system in services/mcp/types.ts defines the full set of supported transports. Each has distinct setup requirements and use cases:

// services/mcp/InProcessTransport.ts
class InProcessTransport implements Transport {
  private peer: InProcessTransport | undefined

  async send(message: JSONRPCMessage): Promise<void> {
    // Deliver async to avoid stack depth in sync req/resp cycles
    queueMicrotask(() => { this.peer?.onmessage?.(message) })
  }
}

export function createLinkedTransportPair(): [Transport, Transport] {
  const a = new InProcessTransport()
  const b = new InProcessTransport()
  a._setPeer(b); b._setPeer(a)
  return [a, b]
}

3 Config Scope Cascade

MCP server configs come from multiple sources that are merged with a clear precedence order. The ConfigScope type names them:

// services/mcp/config.ts — conceptual merge order
const allConfigs = {
  ...enterpriseServers,      // wins if present
  ...dynamicServers,         // --mcp-config flag
  ...claudeAiServers,        // deduplicated by URL sig
  ...projectServers,         // .mcp.json, root-down
  ...localServers,           // ~/.claude/projects/…
  ...userServers,            // ~/.claude/settings.json
  ...pluginServers,          // namespaced, sig-deduplicated
}

// Env vars expanded in all configs before connection
// e.g. command: "npx", args: ["$MY_SERVER_PATH"]

Policy Allow/Deny Lists

Enterprise policy can define allowedMcpServers and deniedMcpServers in settings. The denylist takes absolute precedence. Matching can be by:

• Name — exact server name string
• Command — full command+args array for stdio servers
• URL pattern — glob with * wildcard for remote servers

4 Connection Lifecycle

Every server goes through a state machine managed by the MCPServerConnection union type:

// services/mcp/client.ts (simplified)
const connectPromise = client.connect(transport)
const timeoutPromise = new Promise<never>((_, reject) => {
  const id = setTimeout(() => {
    transport.close().catch(() => {})
    reject(new Error(`MCP server "${name}" timed out after ${timeout}ms`))
  }, getConnectionTimeoutMs())
  connectPromise.then(() => clearTimeout(id), () => clearTimeout(id))
})

await Promise.race([connectPromise, timeoutPromise])

5 Tool Proxying

The MCPTool defined in tools/MCPTool/MCPTool.ts is a template. For every tool reported by a connected server, fetchToolsForClient() in client.ts creates a deep clone with the real metadata overridden:

Name normalization

// services/mcp/normalization.ts
export function normalizeNameForMCP(name: string): string {
  // Replace any char not in [a-zA-Z0-9_-] with underscore
  let normalized = name.replace(/[^a-zA-Z0-9_-]/g, '_')
  // For claude.ai servers: collapse consecutive underscores,
  // strip leading/trailing (__ delimiter must stay clean)
  if (name.startsWith('claude.ai ')) {
    normalized = normalized.replace(/_+/g, '_').replace(/^_|_$/g, '')
  }
  return normalized
}

// Full tool name: "mcp__my_server__list_files"
export function buildMcpToolName(server: string, tool: string): string {
  return `mcp__${normalizeNameForMCP(server)}__${normalizeNameForMCP(tool)}`
}

// After client.callTool() returns a CallToolResult...

// 1. Image content items → resized/downsampled, returned as base64
if (content.type === 'image' && IMAGE_MIME_TYPES.has(mimeType)) {
  const buf = maybeResizeAndDownsampleImageBuffer(rawBuf)
  // → ContentBlockParam with base64 data
}

// 2. Binary blobs → persisted to disk, path returned as text
if (!IMAGE_MIME_TYPES.has(mimeType)) {
  await persistBinaryContent(content)
  // → getBinaryBlobSavedMessage(path)
}

// 3. Total result > 100 KB → truncation with instructions
if (mcpContentNeedsTruncation(result)) {
  result = truncateMcpContentIfNeeded(result)
}

6 OAuth Authentication

MCP servers using SSE or HTTP transport can require OAuth. The auth system in services/mcp/auth.ts implements the full PKCE flow with XAA (Cross-App Access) extension support:

Token refresh & Slack quirk

The standard RFC 6749 invalid_grant error triggers token invalidation. But Slack returns HTTP 200 with {"error":"invalid_refresh_token"} — the SDK would see this as a ZodError. Claude Code normalizes these non-standard codes to invalid_grant before passing to the SDK's error-class mapper.

// services/mcp/auth.ts
const NONSTANDARD_INVALID_GRANT_ALIASES = new Set([
  'invalid_refresh_token',
  'expired_refresh_token',
  'token_expired',
])

// Wraps fetch: peeks at 2xx POST responses, rewrites error bodies
// matching OAuthErrorResponseSchema (but NOT OAuthTokensSchema)
// to a synthetic 400 response — so SDK error-class mapping applies.

XAA — Cross-App Access

Enterprise extension for SSO flows. When xaa: true is set on an MCP server config, instead of launching a browser the system exchanges an IdP ID-token for the MCP server's OAuth token silently. Configured once in settings.xaaIdp, shared across all XAA-enabled servers.

7 Elicitation

Elicitation is the MCP mechanism for servers to request structured input from the user mid-operation. Claude Code supports both modes:

Requests land in AppState.elicitation.queue as ElicitationRequestEvent objects with a respond() callback. The ElicitationDialog React component polls this queue. Hooks (executeElicitationHooks) can satisfy requests programmatically without showing UI.

// services/mcp/elicitationHandler.ts
client.setRequestHandler(ElicitRequestSchema, async (request, extra) => {
  // 1. Try hooks first (programmatic response)
  const hookResponse = await runElicitationHooks(serverName, request.params, extra.signal)
  if (hookResponse) return hookResponse

  // 2. Queue for user interaction
  const response = new Promise<ElicitResult>(resolve => {
    setAppState(prev => ({
      ...prev,
      elicitation: {
        queue: [...prev.elicitation.queue, {
          serverName, requestId: extra.requestId,
          params: request.params,
          respond: resolve,
        }],
      },
    }))
  })
  return await response
})

8 Server Deduplication

When multiple config sources supply the same underlying server, Claude Code deduplicates by content signature, not just name. The signature for stdio servers is stdio:["cmd","arg1"]; for remote servers it's url:https://vendor.example.com/mcp.

Deduplication rules:

• Manual wins over plugin — user-configured always beats plugin-provided.
• First plugin wins — if two plugins provide the same server, first-loaded wins.
• Enabled manual wins over claude.ai — a disabled manual server does not suppress its connector twin (so neither would run).
• Plugin servers are namespaced plugin:name:server to avoid key collisions even before dedup.

9 Knowledge Check