Bitrix24 recense huit erreurs classiques dans le développement de serveurs MCP pour LLM

Un développeur de l'équipe IA de Bitrix24 a publié une analyse pratique des erreurs qui font le plus souvent dérailler les serveurs MCP pour LLM. L'idée centrale est simple : MCP ressemble à une surcouche déterministe au-dessus d'une API, mais c'est un modèle non déterministe qui pilote cette couche. Résultat, les approches d'ingénierie habituelles y échouent régulièrement.

Où tout se casse

Premier problème : l'autorisation. Sur le papier, la spécification est propre : OAuth, des champs clairs et un flow attendu. En pratique, les clients MCP la prennent en charge de façon inégale. Chez certains, l'autorisation fonctionne partiellement, chez d'autres avec des extensions maison, et ailleurs elle ne fonctionne quasiment pas. Pour les serveurs stdio locaux, l'enjeu reste limité, mais dès que le serveur passe sur le réseau, la fragmentation commence. C'est pourquoi les équipes se rabattent souvent sur une solution moins élégante mais stable : des jetons émis à l'avance, que l'utilisateur ajoute manuellement à sa configuration.

Deuxième grand piège : la tentation d'encapsuler un Swagger tel quel dans MCP. Pour un développeur, c'est logique : chaque endpoint de l'API devient un outil distinct. Pour le modèle, c'est un piège de choix. Face à des dizaines d'outils similaires, il confond les scénarios, choisit les mauvaises commandes et se trompe dans les paramètres. La situation empire dès qu'il faut enchaîner une longue série d'actions : trouver un utilisateur, retenir son ID, créer une tâche, puis ajouter un observateur. Un humain s'en sort ; le modèle, lui, peut facilement perdre l'état dès la moitié du parcours.

• Les clients implémentent l'autorisation chacun à leur manière, si bien qu'un même serveur se comporte de façon imprévisible.
• Un large jeu d'outils réduit les chances que le modèle choisisse le bon.
• Les longues chaînes d'appels augmentent le risque d'ID mélangés et de paramètres erronés.
• Des erreurs sans explication sur l'étape suivante laissent le modèle dans une impasse.
• Des réponses trop volumineuses consomment vite le contexte et cassent le dialogue.

Comment concevoir les outils

La conclusion de l'auteur est sévère mais utile : un outil MCP ne doit pas refléter la structure de la base de données, mais une action compréhensible pour l'utilisateur. Si quelqu'un veut « assigner une tâche à Ivan pour demain », l'outil doit accepter un nom, une échéance et le texte de la tâche, au lieu d'obliger le modèle à chercher séparément le user_id, puis le task_id, avant de relier les entités. Plus un outil est autonome, plus le modèle a de chances d'exécuter le scénario sans accroc et sans orchestration bricolée dans le prompt.

«

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

Second volet de la conception : les textes. Pour le modèle, la description d'un outil, son nom et les champs du schéma d'entrée tiennent de fait lieu d'interface. Il ne voit pas le README, ne connaît pas l'architecture et ne saisit pas les intentions de l'auteur au-delà du schéma JSON. Les formulations doivent donc être sémantiquement denses : courtes, mais précises. Pour un LLM, la différence entre `search_users`, `find_users` et `lookup_user_by_email` n'est pas cosmétique, elle est comportementale. Même chose pour les erreurs : un bon message d'erreur ne se contente pas de signaler l'échec, il indique pourquoi il s'est produit et quoi tenter ensuite.

Tests et protection

Les tests unitaires classiques restent indispensables, mais ils ne suffisent pas. Ils vérifient le code de l'outil, pas la manière dont le modèle va le choisir et l'appeler. L'article recommande donc des evals : des jeux de requêtes utilisateur permettant d'observer quel outil a été appelé, avec quels paramètres, et dans quelle mesure la réponse correspond au scénario. Le problème, c'est que le comportement des modèles est instable et change même d'une version à la suivante. Ce qui fonctionnait sur une version de GPT ou de Claude peut se comporter autrement après une mise à jour : les tests manuels dans le chat restent donc, pour l'instant, une étape obligatoire du développement.

Un bloc entier est consacré à la sécurité. MCP élargit la surface d'attaque sur deux fronts à la fois : via l'utilisateur, avec l'injection de prompt, et via les données renvoyées par le serveur lui-même ou par des systèmes externes. Si un outil dispose de droits superflus, le modèle finira tôt ou tard par tenter d'en faire plus qu'il ne devrait.

La recette pratique : privilèges minimaux, filtrage du contenu externe, confirmation explicite pour les actions irréversibles et limitation de la taille des réponses. L'auteur conseille de ne renvoyer que les champs nécessaires, 10–20 enregistrements maximum à la fois, et de toujours garder à l'esprit que même un modèle puissant cesse d'être utile quand son contexte est saturé de JSON brut.

Ce que cela signifie

Les serveurs MCP passent rapidement de l'expérimentation à la production, et le coût des erreurs de conception des outils augmente d'autant. Les gagnantes ne seront pas les équipes qui alignent le plus de méthodes d'API, mais celles qui savent construire pour le modèle des actions courtes, claires et sûres, puis les revalider en permanence sur des scénarios réels.