· reAPI Team
Appels d’outils MCP : pourquoi ils échouent après un changement d’API
Suis les appels d’outils MCP de la découverte à la prise en charge par le modèle, à l’exécution et aux résultats renvoyés. Diagnostique les échecs de migration d’API avant de réessayer ou de soumettre des tâches payantes.

Le serveur MCP indique qu’il est connecté. Pourtant, l’assistant répond toujours en texte ordinaire ou affirme avoir vérifié une tâche sans afficher de résultat. Si le problème a commencé après un changement d’API de modèle, examine ce qui a transité par cette nouvelle connexion avant de modifier encore le prompt.
Un serveur d’outils connecté et un modèle capable de demander des outils sont deux éléments distincts de l’application. MCP définit la découverte et l’invocation des outils. L’hôte doit ensuite présenter les outils appropriés au modèle, exécuter tout appel autorisé qu’il demande et lui renvoyer le résultat.[1][2] La réussite de la première étape ne prouve pas celle de la dernière.
Trouve l’outil dans la liste reçue par le client
Commence par un outil. Lis le résultat réel de tools/list reçu par le client concerné, y compris les pages suivantes, s’il y en a. Conserve son nom, sa description et son schéma d’entrée. Un indicateur de connexion ne montre pas si cet outil précis a été découvert.
S’il est absent, vérifie le serveur sélectionné, le transport pris en charge et l’authentification dans le processus qui exécute le client. La spécification MCP actuelle permet aux outils disponibles de varier selon l’autorisation fournie.[1] Voir un outil ne prouve donc pas que le même appelant peut voir tous les outils proposés par ce serveur.
Pour une connexion reAPI, le serveur documenté utilise Streamable HTTP à distance avec un en-tête d’autorisation Bearer personnalisé. Un client qui ne propose qu’une connexion OAuth sans en-têtes personnalisés ne peut pas se connecter avec cette configuration.[3] Répéter une instruction au modèle ne peut pas fournir un transport ni un mécanisme d’identification dont le client ne dispose pas.
Dans ton enquête, distingue les identifiants du fournisseur de modèle de ceux du serveur d’outils. Ils peuvent appartenir à des connexions différentes. Remplacer une clé d’API de modèle ne corrige pas un identifiant manquant sur la connexion MCP ; remplacer l’identifiant MCP n’ajoute pas non plus d’outils à une requête envoyée au modèle. Note des identifiants de configuration sûrs plutôt que les secrets.
Compare le schéma découvert à ce que voit le modèle
Prends comme exemple cet outil fictif en lecture seule. Il recherche une tâche existante par son ID. Ce fragment illustre une entrée de découverte ; ce n’est ni une réponse de protocole complète ni un outil que nous avons déployé :
{
"name": "inspect_task_example",
"description": "Look up the status of an existing task.",
"inputSchema": {
"type": "object",
"properties": {
"task_id": { "type": "string" }
},
"required": ["task_id"]
}
}Examine maintenant la requête sérialisée envoyée au modèle. Son format d’outil peut différer de celui de inputSchema dans MCP, mais le nom, la propriété et le sens du champ obligatoire doivent être préservés lors de la conversion. Si l’hôte envoie le nom de l’outil sans la propriété task_id ni la liste des champs obligatoires, le modèle a reçu un contrat différent.
C’est un point précis où corriger l’adaptateur. Un prompt plus long demandant au modèle d’« utiliser correctement l’outil » ne rétablit pas le schéma manquant. Compare les deux objets avant d’ajouter des instructions ou de changer encore de fournisseur.
Dans cet exemple, compare task_id à trois endroits : la propriété découverte, la propriété présentée au modèle et les arguments que l’hôte transmet ensuite. Il doit toujours désigner la même valeur de chaîne obligatoire. Si un convertisseur le renomme en id à un endroit tout en conservant task_id ailleurs, il a introduit une incohérence. Utilise le wrapper de définition pris en charge par l’API du modèle, en préservant le nom, le type et le caractère obligatoire du champ.
Vérifie aussi les définitions obsolètes. Un outil renommé sur le serveur peut conserver son ancien nom dans une liste client mise en cache. Enregistre la définition utilisée dans la requête en échec afin que la comparaison porte sur ce que le modèle a réellement reçu, et non sur le dernier schéma visible dans une autre page de documentation.
Le modèle a-t-il demandé un outil ou a-t-il seulement décrit son utilisation ?
Lis la structure de la réponse du modèle. La phrase ordinaire « Je vais vérifier la tâche » n’est pas un appel d’outil structuré. Un refus, une réponse simple, un appel mal formé et un appel valide appellent des étapes suivantes différentes, même s’ils sont tous arrivés dans des réponses HTTP réussies.
Si la requête incluait le bon schéma mais qu’aucun appel n’a été renvoyé, vérifie la prise en charge par le modèle, les paramètres de choix des outils et la route utilisée. La sélection automatique des outils peut produire une réponse ordinaire ; un paramètre qui désactive les outils peut empêcher leur sélection. La prise en charge des valeurs de choix d’outils plus strictes varie aussi selon le modèle.[2] Ne considère pas chaque absence comme un argument mal formé.
Le routage compte lorsqu’un intermédiaire choisit un fournisseur. OpenRouter documente require_parameters pour limiter les routes aux fournisseurs qui prennent en charge tous les paramètres demandés. Ses préférences de paramètres par défaut, y compris celles concernant les outils, ne correspondent pas à un filtrage strict.[4] Vérifie les modèles de secours et la route qui a traité la requête. Ne copie pas cette option propre à un fournisseur dans une autre API en supposant qu’elle aura le même comportement.
Si un appel structuré est bien arrivé, arrête de déboguer la sélection et suis cet appel. Le modèle a demandé une action ; l’application doit encore l’exécuter. Le tutoriel d’OpenRouter sur les appels d’outils attribue explicitement l’exécution à l’appelant, et non au modèle.[2]
Suis le même ID d’appel pendant l’exécution et le renvoi
Voici la suite de l’exemple fictif, au format de message Chat Completions. Les ID et le résultat sont inventés. Ce sont des fragments de message à examiner, pas un script qui envoie une requête :
[
{
"role": "assistant",
"content": null,
"tool_calls": [
{
"id": "call_example_1",
"type": "function",
"function": {
"name": "inspect_task_example",
"arguments": "{\"task_id\":\"example_task_7\"}"
}
}
]
},
{
"role": "tool",
"tool_call_id": "call_example_1",
"content": "{\"task_id\":\"example_task_7\",\"status\":\"processing\"}"
}
]Entre ces deux messages, l’hôte doit transmettre l’appel autorisé à l’outil et recevoir son résultat. Une réponse du modèle contenant call_example_1 ne prouve pas que cette transmission a eu lieu. Cherche l’enregistrement d’exécution correspondant et le résultat du serveur.
Si l’exécution attend une approbation, conserve cet état. Si l’utilisateur a refusé, l’opération refusée est le résultat ; un autre outil ou une nouvelle tentative ne donne pas l’autorisation de contourner cette décision. Si l’approbation a été accordée mais que l’appel n’a jamais été transmis, examine la logique d’exécution de l’hôte.
Vérifie aussi le nom et les arguments de l’outil transmis par rapport à l’appel demandé. Dans cet exemple, la recherche doit recevoir example_task_7 ; si l’hôte réutilise par erreur l’ID de tâche précédent, il a effectué une autre recherche, même si le serveur renvoie un résultat valide. Enregistre la correspondance entre l’ID d’appel du modèle, l’invocation de l’outil et le contenu renvoyé. Cela permet de repérer un résultat associé à la mauvaise tâche avant que le modèle ne l’intègre à une réponse assurée. Corrige cette correspondance locale sans modifier le schéma de l’outil source ni élargir son accès.
Pour les appels en flux, attends que les arguments soient complets. OpenRouter décrit la collecte des deltas par index d’appel et leur analyse une fois la chaîne d’arguments complète.[2] Un fragment initial qui s’arrête au milieu de task_id n’est pas encore un JSON valide. Distingue ce cas d’une chaîne d’arguments complète qui reste invalide.
Le deuxième message ci-dessus porte le même ID d’appel que le premier. Dans la boucle Chat Completions documentée, le tour de l’assistant avec appel d’outil est suivi d’un message de résultat pour chaque appel demandé.[2] Si plusieurs appels ont été renvoyés, conserve l’identité et le résultat de chacun. Envoyer un seul résultat sous chaque ID peut donner l’impression que la conversation est complète tout en associant les mauvaises données aux actions demandées.
Supposons que l’outil ait bien renvoyé processing, mais que la requête suivante au modèle ait omis le message de l’outil. L’exécution a réussi ; le modèle n’a jamais reçu le résultat. Ou supposons que l’hôte ait remplacé le résultat par une chaîne vide lors de la conversion. Changer de modèle laisserait la même information manquante dans la conversation.
Compare le résultat réel du serveur à la suite envoyée. Conserve le contenu pertinent et les erreurs, pas seulement un indicateur de réussite dans un journal client. Évalue la formulation finale du modèle à partir du résultat qu’il a reçu ; affirmer qu’il a vérifié la tâche ne remplace pas cet enregistrement.
Garde les erreurs des outils visibles
MCP distingue les problèmes de protocole des échecs d’exécution des outils. Un outil inconnu ou une requête de protocole mal formée peut produire une erreur JSON-RPC. Un échec d’exécution d’outil peut plutôt être renvoyé avec isError: true.[1] Préserve cette distinction et le message associé lorsque tu convertis le résultat pour le modèle.
Pour la recherche de l’exemple, une erreur indiquant que la tâche est inaccessible ne doit pas devenir un statut de réussite vide. Si le modèle ne reçoit qu’une chaîne vide, il a perdu les informations nécessaires pour expliquer l’échec ou choisir la prochaine étape appropriée. Examine la conversion avant d’accuser la réponse finale.
Une vérification locale utile consiste à faire passer dans l’adaptateur des messages enregistrés ou synthétiques : un résultat normal, une erreur d’exécution et deux appels avec des ID différents. Vérifie que le contenu, le sens de l’erreur et l’identité sont préservés. Cela teste le traitement de ces exemples par l’adaptateur ; cela ne démontre pas qu’un modèle distant sélectionnera correctement l’outil. Une évaluation sur un modèle en direct peut entraîner des frais d’inférence même si l’outil choisi est en lecture seule.
Rends les deux résultats synthétiques visiblement différents, puis renvoie-les dans l’ordre inverse des requêtes. L’hôte doit les associer d’après leurs ID d’appel, et non d’après leur ordre d’arrivée. Des résultats de test identiques peuvent masquer cette erreur, car leur inversion ne change rien de visible dans la prochaine entrée du modèle.
Termine la vérification de connexion avant de soumettre une génération
Pour reAPI, commence par les outils pertinents qui ne soumettent rien. La référence MCP indique que la découverte des modèles, la récupération du schéma, l’estimation, l’état des tâches et les opérations de solde ne consomment pas de crédits. submit_task est différent : un appel qui crée une tâche est facturé pour cette tâche.[3]
Le serveur documenté est sans état et accepte un seul message JSON-RPC par requête HTTP, pas des tableaux de lots. Les entrées multimédias doivent être des URL HTTP ou HTTPS publiques, et non du base64 ou des URI de données.[3] Si l’étape d’exécution échoue, vérifie ces exigences réelles de l’interface ; ne soumets pas plusieurs générations pour tester la connexion.
Conserve l’ID de tâche renvoyé et interroge cette tâche existante. reAPI documente la soumission de tâches comme non idempotente : répéter une requête de création peut générer une autre tâche facturable.[3] Si la réponse à une soumission est perdue, effectue une vérification de l’acceptation au lieu de supposer que rien ne s’est passé.
Pour la recherche fictive, la comparaison de migration est terminée lorsque tu peux montrer où les messages divergent pour la première fois : découverte, définition présentée au modèle, appel structuré, exécution ou résultat renvoyé. Corrige cette différence précise, puis répète la même vérification sans risque. Garde ensemble le serveur, le modèle, la version du client et l’appel enregistré afin que la personne suivante voie ce qui a été vérifié sans se fier à l’indicateur de connexion.
Références
- Model Context Protocol, Tools specification, revision 2026-07-28. Consulté le 16 novembre 2026. Les versions du protocole et les implémentations de serveur peuvent différer.
- OpenRouter, « Tool Calling Across Any Model: Write the Loop Once, Swap the Model String », tutoriel officiel, mis à jour le 24 septembre 2026. Consulté le 16 novembre 2026.
- reAPI, MCP Server documentation. Vérifié le 16 novembre 2026. Aucune génération en direct ni aucun test de compatibilité client n’a été effectué pour ce guide.
- OpenRouter, « Provider Routing », documentation officielle, sections « Requiring Providers to Support All Parameters » et « Default parameter preferences ». Consulté le 16 novembre 2026.