Dissecando o Agente de Código (07): Como Ferramentas Externas São Integradas? Um Mergulho Profundo no MCP

O Tipo de Capacidade que Habilidades Não Conseguem Lidar

As Habilidades do artigo anterior são instruções locais em Markdown: sem Python, sem novos processos — o modelo lê o conteúdo sob demanda e segue adiante. Elas funcionam bem para conhecimento procedural como 'diretrizes de revisão de código da equipe'.

Capacidades externas têm uma forma diferente. Pesquisa na web, bibliotecas de documentação, navegadores, APIs internas da empresa — elas rodam em outro processo, com seus próprios parâmetros e ciclo de vida. Escrever uma subclasse Tool para cada serviço funciona, mas cada novo serviço significa mexer no código novamente.

O significado de engenharia de MCP (Modelo de Protocolo de Contexto) é concreto: permitir que processos externos exponham ferramentas seguindo um protocolo padrão, fazer o agente descobri-las na inicialização, disfarçá-las como Ferramentas locais já registradas, e a partir desse ponto, elas fluem através do mesmo pipeline introduzido no artigo 05 — esquema, orquestração, permissões e gravações de observação.

A Conclusão Antecipada

O ponto de entrada de inicialização do MCP não está em extensions/mcp/, está durante a montagem do contexto do agente:

CodeAgent._initialize_runtime_components()
        │
        ▼
build_runtime_context()              ← runtime/factory.py
        │
        ├─ _register_builtin_tools()   ferramentas embutidas entram no Registro primeiro
        │
        ├─ if host.enable_mcp:         ← Falso por padrão; pulado se não habilitado
        │       host._register_mcp_tools()
        │           │
        │           ▼
        │   register_mcp_servers()     ← extensions/mcp/bootstrap.py
        │           │
        │           ├─ load_mcp_servers()   lê mcp.json / MCP_SERVERS
        │           ├─ MCPClient (stdio / http)
        │           ├─ list_tools() descobre ferramentas remotas
        │           └─ MCPToolAdapter → ToolRegistry
        │
        └─ ContextBuilder(...)         ← grava _mcp_tools_prompt nos Contratos de Ferramentas
                │
                ▼
        Os passos ReAct subsequentes funcionam da mesma forma que Read/Bash:
        tools= schema / Orchestrador → Executor → adapter.run()
                │
                ▼
        protocol.py normaliza o conteúdo MCP em um envelope unificado

Por que começar pela fábrica? O artigo 01 explicou que build_runtime_context() é onde o motor de contexto é montado na inicialização. Tanto as Habilidades quanto o MCP estão conectados aqui, em uma ordem fixa: ferramentas embutidas primeiro, depois MCP, depois ContextBuilder. As ferramentas MCP devem ser registradas antes que ContextBuilder seja criado, para que tool_prompt_allowlist=frozenset(host.tool_registry.list_tools()) possa incluir ferramentas externas, e mcp_tools_prompt possa ser passado de acordo.

A fronteira entre Habilidades e MCP:

Passo 1: Começando de if host.enable_mcp na fábrica

Para entender o MCP, comece abrindo build_runtime_context() em runtime/factory.py. Após lidar com Habilidades e ferramentas embutidas, vem o ramo MCP:

# runtime/factory.py — build_runtime_context()
host._register_builtin_tools()   # ① ferramentas embutidas entram no Registro primeiro

host._mcp_clients = []
host._mcp_tools_prompt = ""
if host.enable_mcp:              # ② Falso por padrão; todo o bloco pulado se não estiver definido
    host._register_mcp_tools()

host.context_builder = ContextBuilder(
    tool_registry=host.tool_registry,
    mcp_tools_prompt=host._mcp_tools_prompt,   # ③ A documentação MCP entra nos Contratos de Ferramentas
    tool_prompt_allowlist=frozenset(host.tool_registry.list_tools()) | {"Task"},
    ...
)

Essas três linhas formam o interruptor mestre para o MCP:

1. enable_mcp é Falso → nada acontece abaixo, _mcp_clients permanece vazio, o Registro só tem ferramentas embutidas
2. Verdadeiro → chama host._register_mcp_tools(), conecta-se a servidores externos, descobre ferramentas, registra Adaptadores
3. Independentemente, ContextBuilder é criado a seguir; quando o MCP está ativado, _mcp_tools_prompt já está populado e anexado aos Contratos de Ferramentas do sistema

De onde vem enable_mcp? O padrão Config.enable_mcp = Falso; CLI --enable-mcp ou variável de ambiente ENABLE_MCP=true o habilitam. Isso não é preguiça — stdio gera processos filhos, e o SDK (mcp, anyio) não deve ser incluído na instalação principal.

Passo 2: _register_mcp_tools() Delegates para Bootstrap

A fábrica apenas decide e chama; a lógica real vive em host._register_mcp_tools():

# runtime/host.py — _register_mcp_tools() (simplificado)
clients, tools_meta = register_mcp_servers(self.tool_registry, self.project_root)
self._mcp_clients = clients
self._mcp_tools_prompt = format_mcp_tools_prompt(tools_meta)