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):
| Primitiva | Quem controla | Para quê | Exemplo |
|---|---|---|---|
| Tools | Modelo (com política do client) | Ações / side effects | create_issue, query_docs |
| Resources | Aplicação / client | Contexto endereçável por URI | file://, schema SQL |
| Prompts | Usuário | Templates 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:
| Client | Onde costuma viver |
|---|---|
| Cursor | .cursor/mcp.json (ou UI de MCP) |
| Claude Code | .mcp.json / config do usuário |
| OpenCode | opencode.json → mcp.servers |
| Codex | config 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:
- Liste 3–7 tools no máximo no v1.
- JSON Schema estrito; rechace campos extras.
- Timeouts curtos; erros acionáveis (“auth expired”, não stack de 40 linhas).
- Idempotência em tools de escrita quando possível.
- Log de audit: quem (sessão) chamou o quê.
- 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
- Client realmente carregou o server? (status na UI / log).
- Description compete com outra tool parecida?
- Arguments falhando no schema?
- Rule/skill proibindo a categoria?
- 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.