O problema
Um servidor MCP expõe uma ferramenta chamada search. A descrição diz apenas: "busca dados". O modelo, ao decidir se deve chamar essa ferramenta, tem que adivinhar: busca em quê? Com que sintaxe de consulta? O que volta se não encontrar nada? Sem essas respostas na própria descrição, o modelo erra a escolha da ferramenta com mais frequência, ou monta argumentos no formato errado — e cada erro desses custa uma rodada inteira de tentativa e correção.
MCP (Model Context Protocol) resolve um problema estrutural: sem ele, cada integração entre um cliente (como o Claude Code) e uma fonte de capacidade (um banco de dados, uma API interna, um sistema de arquivos) exigiria código específico dos dois lados. MCP padroniza essa interface, separando quem fornece a capacidade (o servidor) de quem a consome (o host). Mas essa separação só funciona bem se o lado do servidor for projetado com cuidado — e é aí que a maior parte dos erros de arquitetura acontece.
Descrições de ferramenta são a interface real
Uma ferramenta MCP malfeita não é aquela que tem bugs no código — é aquela cuja descrição não dá ao modelo informação suficiente para decidir corretamente quando e como chamá-la. Uma descrição precisa cobrir:
- O que a ferramenta faz, em termos concretos (não "busca dados", mas "busca tickets de suporte por ID de cliente ou palavra-chave no título")
- Quais argumentos são obrigatórios e o formato esperado de cada um
- O que a ferramenta retorna, incluindo o caso de "nada encontrado"
- Restrições relevantes (limites de taxa, escopo de acesso, efeitos colaterais)
Isso não é documentação para humanos — é a informação que o modelo usa para decidir se essa é a ferramenta certa para o pedido atual. Uma descrição vaga produz o mesmo efeito que uma função sem assinatura de tipo: funciona às vezes, por acidente.
Escopo de configuração: projeto vs. pessoal
MCP define onde um servidor pode ser configurado, e essa escolha tem consequência de segurança e de colaboração:
- Configuração de projeto (
.mcp.json, versionada no repositório): serve para servidores que toda a equipe deve usar da mesma forma — um servidor de acesso ao banco de dados de staging, por exemplo. Fica sob controle de versão, então mudanças passam por revisão. - Configuração pessoal ou experimental (
~/.claude.json): serve para servidores que só fazem sentido para uma pessoa, ou que ainda estão sendo testados antes de virar parte do fluxo do time.
Colocar um servidor experimental na configuração de projeto espalha instabilidade para toda a equipe. Colocar um servidor que a equipe inteira depende só na configuração pessoal de alguém quebra o fluxo de todo mundo quando essa pessoa sai de férias. O escopo errado é, sozinho, motivo suficiente para uma resposta de cenário estar errada — mesmo que o resto da configuração esteja tecnicamente correto.
Segredos usados por um servidor MCP (uma chave de API, por exemplo) nunca devem ser escritos literalmente no arquivo de configuração versionado. O padrão é usar expansão de variável de ambiente (como ${GITHUB_TOKEN}) e nunca commitar o valor.
Descrições e resultados são superfície de ataque
Um servidor MCP externo (que você não controla) pode retornar uma descrição de ferramenta, ou o próprio resultado de uma chamada, contendo texto malicioso projetado para manipular o comportamento do modelo — um ataque conhecido como injeção via descrição ou via resultado de ferramenta. Tratar toda descrição e todo resultado vindos de um servidor MCP de terceiros como dado não confiável, e nunca como instrução, é parte do design de qualquer integração séria. Isso é especialmente relevante ao decidir se um servidor deve ir para a configuração de projeto (afetando todo o time) sem antes ser auditado.
Recursos em vez de chamadas repetidas
Quando o conteúdo que uma ferramenta exporia é um catálogo grande e relativamente estável (um schema, uma lista de categorias), expor isso como resource em vez de exigir uma chamada de ferramenta a cada consulta reduz o número de rodadas necessárias — o modelo pode inspecionar o recurso diretamente. Reservar chamadas de ferramenta para operações que realmente variam por invocação é parte do mesmo raciocínio de design que evita usar tool calls para trabalho determinístico.
Coloque em prática
O laboratório desta lição pede pra você escrever um validador de descrição de ferramenta MCP: dado um dicionário de definição de ferramenta, o script verifica se a descrição cobre os elementos mínimos (o que faz, argumentos obrigatórios, formato de retorno) e sinaliza quando o resultado de uma ferramenta parece conter uma instrução embutida em vez de dado puro — o tipo de verificação que evita os dois erros mais caros de um servidor MCP mal desenhado.