Anatomia do Agente de Código (23): Conectando ao Ecossistema de Ferramentas Externas do MCP

Apresentando o Problema

Os métodos de extensão abordados nos dois artigos anteriores eram todos "faça você mesmo": escreva sua própria classe de ferramenta, escreva seu próprio arquivo Skill.

Mas existem muitos serviços de ferramentas prontos no mundo: Tavily pode pesquisar na web, Context7 pode consultar a documentação mais recente, GitHub CLI pode gerenciar repositórios... se o agente pudesse chamar esses serviços diretamente, não haveria necessidade de reinventar a roda.

MCP (Modelo de Protocolo de Contexto) é o padrão de protocolo que resolve esse problema. Ele define um conjunto de especificações: provedores de serviços de ferramentas expõem ferramentas nesse formato, frameworks de agentes as chamam nesse formato, e ambos os lados concordam com a interface sem precisar escrever um adaptador dedicado para cada serviço.

A Conclusão Primeiro

Conectar um serviço de ferramenta MCP requer apenas duas etapas:

O framework se conectará automaticamente aos serviços, descobrirá a lista de ferramentas e registrará cada ferramenta remota como uma ferramenta local — depois disso, a cadeia de chamadas é idêntica às ferramentas integradas.

I. O Modelo Básico do MCP

Primeiro entenda como o MCP funciona, depois olhe para o código.

O MCP define o conceito de um "servidor de ferramentas": um processo independente (ou serviço HTTP remoto) que possui várias ferramentas registradas, cada uma com seu próprio nome, descrição e esquema de parâmetros.

O fluxo de comunicação entre o agente (cliente) e o servidor de ferramentas tem apenas três etapas:

1. Aperto de Mão: conectar ao servidor
         ↓
2. Descoberta: list_tools() → obter a lista de ferramentas (nome + descrição + inputSchema)
         ↓
3. Invocação: call_tool(nome, params) → obter o resultado

É isso — três etapas, nada mais complexo. O valor do protocolo está na "padronização" — qualquer servidor MCP suporta essas três etapas, e qualquer cliente MCP pode se comunicar com qualquer servidor MCP.

MyCodeAgent implementa o lado do cliente do MCP, encapsulando essas três operações com MCPClient.

II. O Arquivo de Configuração: mcp_servers.json

Para configurar um servidor MCP, basta criar (ou modificar) mcp_servers.json na raiz do projeto:

{
  "mcpServers": {
    "tavily": {
      "command": "uvx",
      "args": ["mcp-server-tavily"],
      "env": {
        "TAVILY_API_KEY": "tvly-xxxxx"
      }
    },
    "context7": {
      "command": "uvx",
      "args": ["--from", "context7-mcp", "context7-mcp"],
      "env": {
        "CTX7_API_KEY": "sua-chave"
      }
    }
  }
}

Dois campos principais:

• command: o comando para iniciar o servidor de ferramentas (uvx é um executor de pacotes Python que executa pacotes diretamente sem instalação)
• args: argumentos passados para o comando
• env: variáveis de ambiente necessárias pelo servidor de ferramentas (chaves de API, etc.)

Há também uma opção de configuração para servidores HTTP remotos:

{
  "mcpServers": {
    "remote-tool": {
      "transport": "http",
      "url": "https://seu-servidor-mcp.com/v1"
    }
  }
}

extensions/mcp/config.py é responsável por ler este arquivo e é compatível com o formato de wrapper da aplicação de desktop Claude {"mcpServers": {...}}, permitindo que arquivos de configuração sejam reutilizados em diferentes agentes.

III. Conexão e Descoberta: O que register_mcp_servers Faz

Quando o agente inicia (com --enable-mcp), register_mcp_servers() é chamado:

# extensions/mcp/bootstrap.py
def register_mcp_servers(tool_registry, project_root):
    # 1. Ler mcp_servers.json
    servers = load_mcp_servers(project_root)

    # 2. Criar um MCPClient para cada servidor (ainda não conectado)
    for server_name, spec in servers.items():
        config = _build_client_config(project_root, spec,