Bitrix24 lista oito erros comuns no desenvolvimento de servidores MCP para LLMs

Um desenvolvedor da equipe de AI da Bitrix24 publicou uma análise prática dos erros que mais quebram servidores MCP para LLMs. A ideia central é simples: o MCP parece um wrapper determinístico sobre uma API, mas quem controla essa camada é um modelo não determinístico. Por isso, as abordagens de engenharia habituais falham com frequência aqui.

Onde tudo quebra

O primeiro problema é a autorização. Na especificação, tudo parece organizado: há OAuth, campos claros e um flow previsível. Na prática, os clientes MCP oferecem suporte desigual: em alguns, a autorização funciona parcialmente; em outros, depende de extensões customizadas; e em alguns quase não funciona. Para servidores stdio locais, isso não é tão crítico, mas, assim que o servidor vai para a rede, começa a fragmentação. É por isso que muitas equipes acabam adotando uma solução menos elegante, porém estável: tokens emitidos previamente, que o usuário adiciona manualmente ao arquivo de configuração.

A segunda grande armadilha é a tentação de simplesmente empacotar o Swagger no MCP, um para um. Para o desenvolvedor, parece lógico: cada endpoint da API vira uma ferramenta. Para o modelo, vira uma armadilha de escolha. Diante de dezenas de ferramentas parecidas, ele começa a confundir cenários, escolher os comandos errados e errar nos parâmetros. Fica ainda pior quando é preciso percorrer uma longa cadeia de ações: encontrar o usuário, guardar o ID, criar a tarefa e depois adicionar um observador. Uma pessoa dá conta disso, mas o modelo pode facilmente perder o estado no meio do caminho.

• Os clientes implementam a autorização de formas diferentes, então o mesmo servidor se comporta de maneira imprevisível.
• Um conjunto grande de ferramentas reduz a chance de o modelo escolher a certa.
• Cadeias longas de chamadas aumentam o risco de IDs trocados e parâmetros incorretos.
• Erros sem explicação sobre o próximo passo deixam o modelo sem saída.
• Respostas volumosas demais 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 como uma ação compreensível para o usuário, e não como reflexo da estrutura do banco de dados. Se a pessoa quer "atribuir uma tarefa ao Ivan para amanhã", a ferramenta deve aceitar o nome, o prazo e o texto da tarefa, em vez de obrigar o modelo a buscar separadamente o user_id, depois o task_id e então vincular as entidades. Quanto mais autossuficiente for a ferramenta, maior a chance de o modelo executar o cenário sem falhas e sem uma orquestração improvisada dentro do prompt.

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

estrutura do seu banco de dados."

A segunda parte do design são os textos. Para o modelo, a descrição da ferramenta, o nome e os campos do schema de entrada funcionam, na prática, como a interface. Ele não vê o README, não conhece a arquitetura e não entende as intenções do autor fora do JSON schema. Por isso, as formulações precisam ser semanticamente densas: curtas, mas precisas. Para um LLM, a diferença entre `search_users`, `find_users` e `lookup_user_by_email` é comportamental, e não cosmética. O mesmo vale para os erros: uma boa mensagem de erro vai além de informar a falha — ela indica por que o problema aconteceu e o que tentar em seguida.

Testes e proteção

Os testes unitários clássicos são necessários aqui, mas não bastam. Eles verificam o código da ferramenta, e não como exatamente o modelo vai escolhê-la e chamá-la. Por isso, o artigo recomenda evals: conjuntos de solicitações de usuários que permitem observar qual ferramenta foi chamada, 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 vizinhas. O que funcionava em uma versão do GPT ou do Claude pode passar a se comportar de outra forma após uma atualização, então o teste manual no chat ainda continua sendo parte obrigatória do desenvolvimento.

Um bloco à parte trata de segurança. O MCP amplia a superfície de ataque por dois lados ao mesmo tempo: pelo usuário, via prompt injection, e pelos dados que o próprio servidor ou sistemas externos retornam. Se a ferramenta tiver permissões em excesso, cedo ou tarde o modelo 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 limite no tamanho das respostas. O autor recomenda retornar apenas os campos necessários, no máximo 10–20 registros por vez, e lembrar sempre que até um modelo forte deixa de ser útil quando seu contexto está entupido de JSON bruto.

O que isso significa

Os servidores MCP estão migrando rapidamente da fase de experimentos para a produção, e com isso cresce o custo dos erros no design das ferramentas. Vão sair na frente não as equipes com mais métodos de API, e sim as que sabem construir ações curtas, claras e seguras para o modelo — e depois revalidá-las constantemente em cenários reais.