MCP para agentes de código: conectar tools sem reinventar integração

Todo agente de código precisa do mesmo tipo de coisa: ler um doc oficial, abrir um ticket, consultar um schema, disparar um preview. Sem padrão, cada IDE inventa um plugin proprietário. O Model Context Protocol (MCP) é o protocolo aberto (JSON-RPC) que padroniza como clients (Cursor, Claude Code, OpenCode, Orca, etc.) falam com servers que expõem ferramentas e contexto.

Este artigo explica o modelo mental, o que colocar (e o que não) num server, e como encaixar MCP no fluxo de agentes sem transformar o repo numa feira de plugins.


O que o MCP padroniza

Um MCP server oferece três primitivas (spec oficial):

PrimitivaQuem controlaPara quêExemplo
ToolsModelo (com política do client)Ações / side effectscreate_issue, query_docs
ResourcesAplicação / clientContexto endereçável por URIfile://, schema SQL
PromptsUsuárioTemplates invocáveis“gerar release notes”

Na prática, no dia a dia de coding agents, tools dominam: o modelo lista (tools/list), escolhe, e chama com argumentos tipados por JSON Schema.

Sem MCP, você cola API keys em prompts ou escreve wrappers ad hoc por produto. Com MCP, o mesmo server de docs ou de browser pode ser reutilizado em vários clientes.


Anatomia de uma tool

Conceitualmente, cada tool declara nome, descrição e inputSchema:

{
  "name": "query_docs",
  "description": "Busca trechos na documentação da biblioteca X",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": { "type": "string" }
    },
    "required": ["query"]
  }
}

A qualidade da description define se o agente chama a tool certa. Description vaga = tool fantasma que nunca é escolhida, ou pior: escolhida na hora errada.


Onde configurar (visão geral)

Os paths mudam por produto, mas a ideia é a mesma — declarar servers no config do client:

ClientOnde costuma viver
Cursor.cursor/mcp.json (ou UI de MCP)
Claude Code.mcp.json / config do usuário
OpenCodeopencode.json → mcp.servers
Codexconfig TOML do usuário

Exemplo ilustrativo (formato varia):

{
  "mcpServers": {
    "docs": {
      "command": "npx",
      "args": ["-y", "@vendor/docs-mcp"],
      "env": {
        "API_KEY": "${DOCS_API_KEY}"
      }
    }
  }
}

Segredos: via env / secret store do SO — nunca hardcoded no git. Detalhes de schema de config: consulte a doc da versão do seu client.

Comparativo mais amplo das tools: OpenCode vs Cursor vs Claude Code vs Orca.


O que conectar (e o que deixar de fora)

Bom fit:

  • Documentação de libs (Context7 e similares).
  • Issue trackers com escopo read ou write controlado.
  • Schemas / catálogos internos.
  • Browser/preview quando o fluxo pede verificação visual.
  • Observabilidade read-only (logs de staging).

Mau fit:

  • Deploy em produção sem gate humano.
  • Shell irrestrito “porque é flexível”.
  • Dez servers que se sobrepõem (três jeitos de ler GitHub).
  • Tools que duplicam o que o agente já faz bem (ler arquivo local).

Cada tool no prompt system compete por atenção. Mais MCP ≠ mais inteligência; muitas vezes é mais superfície de erro.


MCP + rules + orquestração

MCP sem policy é perigoso; policy sem MCP é discurso.

  • Em Skills e Rules: declare quando usar cada server.
  • Em orquestração: dê MCP de escrita só ao worker executor; reviewer fica read-only.
  • Em worktrees: servers com estado local (caches) devem ser seguros sob paralelo.

Exemplo de rule:

MCP `db-prod` é proibido.
MCP `db-staging` só SELECT.
Para docs de lib, preferir o server de documentação à memória do modelo.

Padrão de implementação de um server mínimo

Se o time precisa de um server interno:

  1. Liste 3–7 tools no máximo no v1.
  2. JSON Schema estrito; rechace campos extras.
  3. Timeouts curtos; erros acionáveis (“auth expired”, não stack de 40 linhas).
  4. Idempotência em tools de escrita quando possível.
  5. Log de audit: quem (sessão) chamou o quê.
  6. Teste o server com o inspector/MCP client oficial antes de plugar no IDE.

Não exponha “run arbitrary SQL” no dia 1. Exponha list_tables + explain_query se o objetivo é ajudar o agente a pensar.


Debugging quando o agente “não vê” a tool

  1. Client realmente carregou o server? (status na UI / log).
  2. Description compete com outra tool parecida?
  3. Arguments falhando no schema?
  4. Rule/skill proibindo a categoria?
  5. Sandbox/rede bloqueando o processo do server?

Trate MCP como dependência de runtime: se quebra o login, o agente regride para alucinação educada.


Checklist

  • Cada server tem um job claro?
  • Secrets fora do git?
  • Tools de escrita com gate / ambiente não-prod?
  • Descriptions testadas com prompts reais do time?
  • Lista de servers revisada no PR como código?

Conclusão

MCP é cola, não cérebro. Use para capacidades externas estáveis; combine com rules curtas e, quando necessário, workers isolados. O time que escolhe poucos servers bons ganha dos que instalam o catálogo inteiro.

Quer conhecer o restante do meu trabalho em engenharia de software? Comece pelo portfolio.