Estamos Construindo Servidores MCP Errado

Quando a maioria dos desenvolvedores constrói seu primeiro servidor MCP, eles fazem algo previsível: pegam sua API REST e envolvem cada endpoint como ferramenta MCP. GET /users vira get_users. O mapeamento é 1:1, mecânico e errado.

É errado porque APIs REST são projetadas para desenvolvedores que leem documentação e encadeiam chamadas na cabeça. LLMs não funcionam assim. Trabalham com descrições de ferramentas, não docs.

Quando você mapeia cegamente REST para MCP, força o LLM a reconstruir o modelo mental que sua documentação teria dado a um desenvolvedor humano.

A mudança fundamental: endpoints REST modelam recursos. Ferramentas MCP deveriam modelar tarefas.

Uma API REST tem GET /users/{id}, GET /users/{id}/orders, GET /orders/{id}/items. Três endpoints, três chamadas, três respostas para montar.

Um servidor MCP deveria ter get_user_order_summary que retorna tudo em uma chamada. O LLM perguntou "o que este usuário pediu?" — dê a resposta, não três peças de quebra-cabeça.

Parece errado para puristas de API. Mas o consumidor não é um desenvolvedor — é um LLM que performa melhor com menos chamadas mais completas.

Em uma API REST, o caminho e método HTTP carregam informação semântica. GET /users é óbvio.

LLMs não parseiam padrões de URL. Leem descrições de ferramentas. Sua descrição é a única documentação que importa.

Escreva descrições como se estivesse explicando para um colega muito literal sem contexto. Diga exatamente o que faz, o que retorna, quando usar e quando NÃO usar.

A maioria dos servidores MCP tem descrições que tirariam nota D em escrita técnica. Esta é a melhoria de maior alavancagem.

Padrão que vejo constantemente: servidor MCP com search_documents, find_documents e query_documents. Três ferramentas que fazem quase a mesma coisa.

Para um desenvolvedor, as diferenças são óbvias. Para um LLM, são três ferramentas com descrições similares. Erra cerca de 40% das vezes.

Sobreposição de ferramentas é a fonte número um de problemas de confiabilidade MCP. A solução é deduplicação impiedosa. Se duas ferramentas podem ser mescladas, mescle-as.

Menos ferramentas mais capazes sempre vencem muitas ferramentas especializadas.

A meta-lição é simples: ferramentas MCP têm um consumidor diferente das APIs REST.

Teste com LLMs reais. Não só "a ferramenta executa corretamente?" — mas "o LLM escolhe a ferramenta certa e passa os parâmetros certos?"

Monitore como LLMs realmente usam suas ferramentas em produção. Você encontrará padrões surpreendentes.

Os melhores servidores MCP não são os com mais ferramentas. São onde o LLM acerta na primeira tentativa, toda vez. Essa é a única métrica que importa.