Bitrix24 a recensé huit erreurs typiques dans le développement de serveurs MCP pour les LLM

Un développeur de l'équipe IA de Bitrix24 a publié une analyse pratique des erreurs qui cassent le plus souvent les serveurs MCP pour LLM. L'idée principale est simple : MCP ressemble à un wrapper déterministe sur une API, mais cette couche est gérée par un modèle non-déterministe, donc les approches d'ingénierie conventionnelles échouent régulièrement ici.

Où tout casse

Le premier problème est l'autorisation. Dans la spécification, tout semble bien : il y a OAuth, des champs clairs et un flux attendu. En pratique, différents clients MCP le supportent inégalement : quelque part l'autorisation fonctionne partiellement, ailleurs avec des extensions personnalisées, et quelque part elle ne fonctionne presque pas. Pour les serveurs stdio locaux ce n'est pas si critique, mais dès que le serveur passe en ligne, la fragmentation commence. C'est pourquoi les équipes finissent souvent par une option moins élégante mais stable : des tokens pré-émis que l'utilisateur ajoute manuellement à la configuration.

Le deuxième piège majeur est le désir d'envelopper simplement Swagger dans MCP un à un. Pour un développeur, cela semble logique : chaque endpoint API devient un outil séparé. Pour le modèle, c'est un piège de sélection. Quand il a des dizaines d'outils similaires, il commence à confondre les scénarios, choisit mal les commandes et se trompe sur les paramètres. C'est encore pire quand il faut passer par une longue chaîne d'actions : trouver un utilisateur, mémoriser l'ID, créer une tâche, puis ajouter un observateur. Un humain s'en sortira, mais un modèle perd facilement l'état à mi-parcours.

• Les clients implémentent l'autorisation différemment, donc le même serveur se comporte de manière imprévisible.
• Un grand ensemble d'outils réduit les chances que le modèle choisisse le bon.
• Les longues chaînes d'appels augmentent le risque d'ID confus et de paramètres incorrects.
• Les erreurs sans explication de l'étape suivante laissent le modèle bloqué.
• Les réponses trop volumineuses consomment rapidement le contexte et cassent le dialogue.

Comment concevoir des outils

La conclusion de l'auteur est dure mais utile : un outil MCP doit être conçu non pas comme un reflet de la structure de la base de données, mais comme une action compréhensible pour l'utilisateur. Si un humain a besoin « d'assigner une tâche à Ivan pour demain », l'outil devrait pouvoir accepter un nom, une date limite et un texte de tâche, plutôt que de forcer le modèle à chercher séparément user_id, puis task_id et puis lier les entités. Plus l'outil est autosuffisant, plus il y a de chances que le modèle exécute le scénario sans problèmes et sans orchestration maison dans le prompt.

«

Les outils doivent refléter l'intention de l'utilisateur, pas la structure de votre base de données. »

La deuxième partie du design est le texte. Pour un modèle, la description d'un outil, son nom et les champs du schéma d'entrée remplacent effectivement l'interface. Il ne voit pas README, ne connaît pas l'architecture et ne comprend pas les intentions de l'auteur en dehors du schéma JSON. Par conséquent, les formulations doivent être sémantiquement denses : courtes mais précises. La différence entre `search_users`, `find_users` et `lookup_user_by_email` pour LLM n'est pas cosmétique mais comportementale. Il en va de même pour les erreurs : un bon message d'erreur ne rapporte pas juste une panne, il explique pourquoi c'est arrivé et ce qu'il faut essayer après.

Tests et protection

Les tests unitaires clássiques sont nécessaires ici, mais ne suffisent pas. Ils vérifient le code de l'outil, pas comment exactement le modèle le sélectionnera et l'appellera. C'est pourquoi l'article recommande les evals : des ensembles de requêtes utilisateur qui permettent de voir quel outil a été invoqué, avec quels paramètres et combien la réponse correspond au scénario. Le problème est que le comportement des modèles est instable et change même entre les versions adjacentes. Ce qui fonctionnait dans une version de GPT ou Claude peut se comporter différemment après une mise à jour, donc les tests manuels en chat restent une partie obligatoire du développement pour l'instant.

Une section séparée est consacrée à la sécurité. MCP élargit la surface d'attaque de deux côtés à la fois : via l'utilisateur avec l'injection de prompt et via les données que le serveur ou les systèmes externes retournent. Si un outil a des privilèges supplémentaires, le modèle essaiera tôt ou tard de faire plus qu'il ne le devrait.

La recette pratique est celle-ci : privilèges minimaux, filtrage du contenu externe, confirmation explicite pour les actions irréversibles et limitation de la taille de la réponse. L'auteur recommande de ne retourner que les champs nécessaires, au maximum 10-20 enregistrements à la fois, et de toujours se souvenir que même un modèle puissant cesse d'être utile quand son contexte est rempli de JSON brut.

Ce que cela signifie

Les serveurs MCP passent rapidement des expériences à la production, et avec cela, le coût des erreurs dans la conception des outils augmente. Les équipes gagnantes ne seront pas celles avec plus de méthodes API, mais celles qui savent construire des actions courtes, compréhensibles et sécurisées pour le modèle, et puis les vérifier constamment sur des scénarios réels.