Bitrix24 listou oito erros típicos no desenvolvimento de servidores MCP para LLMs

Um desenvolvedor da equipe de IA do Bitrix24 publicou uma análise prática dos erros que mais frequentemente danificam servidores MCP para LLM. A ideia principal é simples: o MCP parece uma camada determinística sobre uma API, mas essa camada é gerenciada por um modelo não-determinístico, então as abordagens de engenharia convencionais regularmente falham aqui.

Onde tudo quebra

O primeiro problema é a autorização. Na especificação, tudo parece bem organizado: há OAuth, campos claros e um fluxo esperado. Na prática, diferentes clientes MCP implementam isso de forma desigual: em alguns lugares a autorização funciona parcialmente, em outros com extensões personalizadas, e em alguns quase não funciona. Para servidores stdio locais isso não é tão crítico, mas assim que o servidor sai online, a fragmentação começa. É por isso que as equipes geralmente chegam a uma opção menos elegante, mas estável: tokens pré-emitidos que o usuário adiciona manualmente à configuração.

A segunda grande armadilha é o desejo de simplesmente envolver o Swagger em MCP um a um. Para um desenvolvedor, isso parece lógico: cada endpoint de API se torna uma ferramenta separada. Para o modelo, isso é uma armadilha de seleção. Quando tem dezenas de ferramentas semelhantes, começa a confundir cenários, escolhe comandos incorretamente e erra nos parâmetros. Fica ainda pior onde você precisa passar por uma longa cadeia de ações: encontrar um usuário, lembrar o ID, criar uma tarefa, depois adicionar um observador. Um humano consegue, mas um modelo facilmente perde o estado no meio do caminho.

• Clientes implementam autorização de forma diferente, então o mesmo servidor se comporta de forma imprevisível.
• Um grande conjunto de ferramentas reduz a chance de o modelo selecionar a correta.
• Longas cadeias de chamadas aumentam o risco de IDs confusos e parâmetros incorretos.
• Erros sem explicação do próximo passo deixam o modelo travado.
• Respostas muito grandes consomem rapidamente o contexto e quebram o diálogo.

Como projetar ferramentas

A conclusão do autor é dura, mas útil: uma ferramenta MCP deve ser projetada não como um reflexo da estrutura do banco de dados, mas como uma ação compreensível para o usuário. Se um humano precisa "atribuir uma tarefa para Ivan amanhã", a ferramenta deve ser capaz de aceitar um nome, prazo e texto da tarefa, ao invés de forçar o modelo a procurar separadamente por user_id, depois task_id e depois vincular entidades. Quanto mais autossuficiente a ferramenta, maior a chance de o modelo executar o cenário sem falhas e orquestração caseira dentro do prompt.

"As ferramentas devem refletir a intenção do usuário, não a estrutura

do seu banco de dados."

A segunda parte do design é o texto. Para um modelo, a descrição de uma ferramenta, seu nome e os campos do esquema de entrada efetivamente substituem a interface. Não vê README, não conhece a arquitetura e não entende as intenções do autor fora do esquema JSON. Portanto, as formulações devem ser semanticamente densas: curtas mas precisas. A diferença entre `search_users`, `find_users` e `lookup_user_by_email` para LLM não é cosmética mas comportamental. O mesmo vale para erros: uma boa mensagem de erro não apenas relata uma falha, mas sugere por que isso aconteceu e o que tentar a seguir.

Testes e proteção

Testes unitários clássicos são necessários aqui, mas não são suficientes. Eles verificam o código da ferramenta, não como exatamente o modelo a selecionará e a chamará. Portanto, o artigo recomenda evals: conjuntos de solicitações do usuário que permitem ver qual ferramenta foi invocada, com quais parâmetros e o quanto a resposta corresponde ao cenário. O problema é que o comportamento dos modelos é instável e muda até entre versões adjacentes. O que funcionou em uma versão do GPT ou Claude pode se comportar de forma diferente após uma atualização, então testes manuais no chat continuam sendo uma parte obrigatória do desenvolvimento por enquanto.

Uma seção separada é dedicada à segurança. MCP expande a superfície de ataque de dois lados ao mesmo tempo: através do usuário com injeção de prompt e através dos dados que o próprio servidor ou sistemas externos retornam. Se uma ferramenta tem privilégios extras, o modelo mais cedo ou mais tarde tentará fazer mais do que deveria. A receita prática é esta: privilégios mínimos, filtragem de conteúdo externo, confirmação explícita para ações irreversíveis e limitação do tamanho da resposta. O autor recomenda retornar apenas os campos necessários, no máximo 10-20 registros por vez, e sempre lembrar que até mesmo um modelo poderoso deixa de ser útil quando seu contexto está cheio de JSON bruto.

O que isso significa

Servidores MCP estão rapidamente saindo de experimentos para produção, e com isso, o custo de erros no design de ferramentas está crescendo. As equipes vencedoras não serão aquelas com mais métodos de API, mas aquelas que sabem como construir ações curtas, compreensíveis e seguras para o modelo, e depois verificá-las constantemente em cenários reais.