Mergulho Profundo no Open Agent SDK (Parte 3): Integração do MCP na Prática

O artigo anterior analisou as 34 ferramentas integradas do SDK — leitura/escrita de arquivos, execução de Bash, busca de código — cobrindo cenários comuns de desenvolvimento. Mas as capacidades de um Agente não podem depender apenas de ferramentas integradas. Você precisa se conectar a bancos de dados, chamar APIs empresariais e operar sistemas internos. Isso requer uma abordagem de integração padronizada.

O MCP (Modelo de Protocolo de Contexto) foi projetado exatamente para isso. Este artigo examina como o Open Agent SDK utiliza o protocolo MCP para trazer ferramentas externas para o Loop do Agente.

O Que É o Protocolo MCP

O MCP é um protocolo aberto proposto pela Anthropic que define padrões de comunicação entre aplicações LLM e ferramentas/fontes de dados externas. O conceito:

• Lado da ferramenta (Servidor MCP) expõe um conjunto de ferramentas, cada uma com um nome, descrição e esquema de entrada
• Lado da chamada (Cliente MCP) descobre ferramentas, as invoca e obtém resultados através de um protocolo padrão
• A comunicação é baseada em JSON-RPC com transportes intercambiáveis

Por que um Agente precisa disso? Porque é impossível construir todas as ferramentas no SDK. Com o MCP, qualquer um pode escrever um Servidor MCP (por exemplo, @modelcontextprotocol/server-filesystem), e qualquer Agente pode se conectar — nenhuma alteração de código do SDK é necessária, nenhum adaptador para escrever, apenas uma linha de configuração.

A integração do MCP do Open Agent SDK tem dois caminhos:

1. Servidores MCP externos: Conectar-se a Servidores MCP de terceiros via stdio/HTTP/SSE, executando o protocolo MCP completo
2. Servidores MCP em processo: Usar InProcessMCPServer para envolver ferramentas do SDK como um Servidor MCP com zero sobrecarga de protocolo

Vamos examinar cada um.

Cinco Configurações de Transporte

O SDK usa o McpServerConfig enum para unificar todos os métodos de transporte:

public enum McpServerConfig: Sendable, Equatable {
    case stdio(McpStdioConfig)       // Entrada/Saída padrão do processo filho
    case sse(McpTransportConfig)     // Eventos enviados pelo servidor
    case http(McpTransportConfig)    // HTTP POST
    case sdk(McpSdkServerConfig)     // Em processo, zero sobrecarga
    case claudeAIProxy(McpClaudeAIProxyConfig) // Proxy ClaudeAI
}

Stdio: Lançando Processos Filhos

A abordagem mais comum. O Agente lança um processo filho e troca mensagens JSON-RPC via stdin/stdout. Adequado para Servidores MCP escritos em Node.js/Python:

let servers: [String: McpServerConfig] = [
    "filesystem": .stdio(McpStdioConfig(
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    )),
    "git": .stdio(McpStdioConfig(
        command: "uvx",
        args: ["mcp-server-git"],
        env: ["GIT_REPO_PATH": "/my/repo"]
    ))
]

MCPStdioTransport usa internamente o Process da Foundation para lançar processos filhos e FileDescriptor para I/O de baixo nível. Alguns detalhes:

• Resolução de comando: Se o comando não for um caminho absoluto, ele é procurado via which primeiro. Retorna a tratar como um caminho de arquivo se não encontrado
• Delimitação de mensagens: Cada mensagem JSON-RPC é delimitada por quebras de linha, com suporte a CRLF
• Filtragem de segurança: CODEANY_API_KEY não é passado para processos filhos por padrão, a menos que especificado explicitamente em env
• Reconexão: MCPClient é configurado com até 2 tentativas automáticas, intervalo inicial de 1 segundo, retrocesso exponencial até um máximo de 10 segundos

SSE e HTTP: Conectando a Serviços Remotos

Servidores MCP remotos se conectam via HTTP, em dois modos:

// Modo SSE (conexão longa, push do servidor)
let sseServer: [String: McpServerConfig] = [
    "remote-tools": .sse(McpTransportConfig(
        url: "https://mcp.example.com/sse",
        headers: ["Authorization": "Bearer token123"]
    ))
]

// Modo HTTP (requisição-resposta)
let httpServer: [String: McpServerConfig] = [
    "api-tools": .http(McpTransportConfig(
        url: "https://mcp.example.com/api"
    ))
]

SSE é para cenários que requerem...