🔌 MCP Integration

MCP (Model Context Protocol) fornece tools externas e data sources para modelos de IA. No Claude Code, cada MCP server prove tools registradas via a interface standard Tool, namespaced como mcp__<server>__<tool>.

Oito tipos de transport, cada um com requisitos de setup distintos:

InProcessTransport

class InProcessTransport implements Transport {
  private peer: InProcessTransport | undefined

  async send(message: JSONRPCMessage): Promise<void> {
    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]
}

Usa queueMicrotask para entregar mensagens, evitando stack overflows em chamadas recursivas.

Timeout Race Pattern

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])

MCPTool e um template. Para cada tool de cada server conectado, fetchToolsForClient() clona com metadata real overridden.

Name Normalization

export function normalizeNameForMCP(name: string): string {
  let normalized = name.replace(/[^a-zA-Z0-9_-]/g, '_')
  if (name.startsWith('claude.ai ')) {
    normalized = normalized.replace(/_+/g, '_').replace(/^_|_$/g, '')
  }
  return normalized
}

export function buildMcpToolName(server: string, tool: string): string {
  return `mcp__${normalizeNameForMCP(server)}__${normalizeNameForMCP(tool)}`
}

Result Handling

MCP servers usando SSE ou HTTP transport podem requerer OAuth. O sistema implementa fluxo PKCE completo com XAA (Cross-App Access) extension support.

Elicitation: Dois Modos

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
})

Server Deduplication