Les symptômes, et ce qu'ils désignent
Quatre situations reviennent, et chacune oriente vers une étape précise du cycle vu au chapitre précédent.
Le serveur n'apparaît pas du tout. Problème de configuration ou de démarrage : le client n'a jamais réussi à le lancer ou à le joindre. Étape 1.
Le serveur apparaît, mais sans outils. La connexion fonctionne, la découverte échoue ou renvoie une liste vide. Étape 2.
Les outils apparaissent, le modèle ne les utilise pas. Ce n'est pas une panne : c'est un problème de description. Étape 4.
L'outil est appelé et échoue. Là seulement, le problème est dans votre exécution. Étape 6.
Le troisième cas est celui qu'on diagnostique le plus mal, parce qu'il ressemble à une panne alors que tout fonctionne.
Isoler le serveur du client
Le réflexe le plus rentable : tester le serveur sans client.
Lancez-le à la main et envoyez-lui directement une demande de liste d'outils, puis un appel. Si cela fonctionne, le serveur est hors de cause et le problème est dans la configuration du client. Si cela échoue, vous venez d'écarter toute la moitié cliente.
Ce test prend deux minutes et évite de chercher dans les deux endroits à la fois.
Les causes fréquentes, par ordre
Un chemin ou une commande erronés dans la configuration du client. La cause numéro un pour un serveur local.
Un environnement différent. Le serveur lancé par le client n'hérite pas forcément de vos variables d'environnement ni de votre PATH. Un serveur qui marche dans votre terminal et pas via le client relève presque toujours de ce cas.
Une sortie parasite. Sur un transport local, tout ce que le serveur écrit sur la sortie standard fait partie du protocole. Un message de démarrage affiché là casse la communication. Les journaux vont sur la sortie d'erreur, jamais sur la sortie standard.
Un blocage réseau pour un serveur distant, ou un certificat expiré.
Une version incompatible entre client et serveur, traitée dans la leçon suivante.
La troisième cause est spécifique à MCP et surprend systématiquement à la première rencontre.
Regarder au bon endroit
Trois sources, complémentaires :
- les journaux du client, qui disent s'il a lancé le serveur et ce qu'il a reçu
- la sortie d'erreur du serveur, où doivent aller vos traces
- un appel direct, qui tranche entre les deux
Instrumentez votre serveur dès le début : à chaque appel, notez l'outil, les arguments reçus et le temps d'exécution. Sans cela, vous diagnostiquez à l'aveugle.
Quand le modèle n'appelle pas l'outil
Ce n'est pas un problème technique, et le réflexe de redémarrer ne sert à rien. Trois causes, par fréquence : la description est trop vague, le nom ne correspond pas à l'intention de l'utilisateur, ou un autre outil semble mieux convenir.
Le test qui tranche : demandez explicitement l'appel de cet outil. S'il fonctionne, la mécanique est saine et il faut réécrire la description, pas le code.
À retenir
Testez le serveur sans client pour couper le problème en deux. Sur un transport local, rien ne s'écrit sur la sortie standard sauf le protocole. Et un outil ignoré par le modèle est un problème de rédaction, pas d'exécution.