L'inspecteur de serveur

Vous venez d’écrire deux outils, et la question qui vient immédiatement est de savoir s’ils fonctionnent. Assembler toute une application cliente pour le vérifier serait absurde à ce stade : vous passeriez une heure à brancher Claude, la CLI et le client MCP simplement pour découvrir qu’un identifiant de document est mal orthographié dans votre dictionnaire. L’Inspector MCP, l’outil de référence du projet, résout ce problème : un client MCP générique, dans le navigateur, qui liste et exécute outils, ressources et prompts sans une ligne de code de test. À la fin de cette leçon, vous saurez le lancer, vous y repérer, tester vos outils, provoquer une erreur et lire les messages JSON-RPC échangés.

Démarrer l’inspecteur

Vérifiez d’abord que votre environnement Python est activé, l’oubli le plus fréquent. Lancez ensuite l’inspecteur en lui indiquant le fichier de votre serveur :

mcp dev mcp_server.py

La commande mcp dev du SDK (extra cli, leçon 4) lance en réalité npx @modelcontextprotocol/inspector, d’où le prérequis Node 22.19 ou supérieur. Voici, mot pour mot, ce qu’elle a affiché sur notre poste avec l’Inspector 2.13.0 :

Starting MCP inspector...

MCP Inspector Web is up and running at:
   http://127.0.0.1:6274?MCP_INSPECTOR_API_TOKEN=74b339b7…

   Sandbox (MCP Apps): http://127.0.0.1:6275/sandbox

   Auth token: 74b339b7…

   Secrets: OS keychain

Ouvrez l’URL complète, jeton compris : le serveur Node qui se cache derrière l’interface peut lancer des processus sur votre machine, et chaque route est protégée par ce jeton généré au lancement. Taper localhost:6274 de mémoire ne suffira pas. L’Inspector existe aussi en ligne de commande (npx @modelcontextprotocol/inspector --cli … --method tools/list, pratique pour un script ou une intégration continue) et en interface terminal (--tui), avec la même mécanique de connexion.

Se repérer dans l’interface

L’interface est en développement actif et peut évoluer d’une version à l’autre, mais son organisation reste cohérente. Vous arrivez sur l’onglet Servers, qui liste votre serveur avec son transport (ici STDIO et la commande qui le lance) et un interrupteur « Disconnected ». Basculez-le : l’inspecteur démarre le processus serveur, négocie le protocole et passe à « Connected ». Trois onglets apparaissent alors dans la barre du haut, Tools, Prompts et Resources, un par primitive ; seuls ceux que votre serveur annonce sont affichés. À droite, une colonne de suivi (Protocol, Console) enregistre chaque message JSON-RPC échangé, avec sa durée et son statut.

Regardez la colonne de droite sur cette capture : au moment de la connexion, l’inspecteur a enchaîné initialize, notifications/initialized, puis resources/list, tools/list, prompts/list et resources/templates/list. C’est le trajet de découverte de la leçon 3, observé en vrai. Le badge LEGACY et la mention « MCP 2025-11-25 » signalent l’ère de protocole négociée : par défaut, l’inspecteur se connecte avec la poignée de main initialize des versions antérieures, sans sonder server/discover, pour ne pas polluer la transcription que vous êtes venu lire ; le réglage Protocol Era du serveur (legacy, auto, modern) permet d’exiger la version 2026-07-28. Notre serveur, écrit avec le SDK v2, sait parler aux deux.

Tester vos outils

Ouvrez l’onglet Tools : les deux outils sont déjà listés, puisque tools/list a été envoyé à la connexion. C’est une première vérification utile, puisque vous voyez ici exactement ce que Claude verrait. Sélectionnez read_doc_contents : le panneau central affiche sa description et un formulaire généré à partir du schéma d’entrée, un champ par argument, avec la description que vous avez écrite dans Field.

La procédure tient en quatre gestes : sélectionner l’outil, saisir un identifiant (deposition.md), cliquer Execute Tool, vérifier le résultat. Le formulaire se replie et le panneau Results affiche le contenu retourné ; dans la colonne de droite, une entrée tools/call read_doc_contents apparaît avec son temps de réponse et le statut OK.

Vérifier les enchaînements et les erreurs

Un outil pris isolément ne dit pas tout : ce qui compte souvent, c’est l’effet d’un appel sur le suivant. Appelez edit_document pour modifier un document, puis enchaînez immédiatement avec read_doc_contents sur le même identifiant afin de confirmer que le remplacement a bien été appliqué. L’inspecteur garde le même processus serveur entre les appels, donc les modifications persistent et vous observez le comportement réel de votre serveur, pas une simulation.

Pensez aussi aux cas d’erreur, que l’on néglige presque toujours. Entrez un doc_id inexistant et regardez ce qui revient :

Cette capture a été prise avant la correction de la leçon 5 : le serveur levait une ValueError, et le client ne reçoit que « Error executing tool read_doc_contents ». Avec ToolError, le même écran affiche « Error executing tool read_doc_contents: Document avec l’id inconnu.md introuvable ». Ce détail a des conséquences directes en production : c’est ce message que Claude recevra et interprétera pour décider de la suite, redemander l’information, proposer une correction, ou signaler le problème à l’utilisateur. L’inspecteur est l’endroit où l’on s’en aperçoit à temps.

Une boucle de retour très courte

L’inspecteur finit par devenir une pièce centrale de votre processus de développement. Plutôt que d’écrire des scripts de test séparés ou de connecter des applications complètes, vous itérez rapidement sur vos implémentations d’outils, vous éprouvez les cas limites et les conditions d’erreur, vous vérifiez les interactions entre outils ainsi que la gestion d’état, et vous lisez, dans la colonne Protocol, les messages JSON-RPC exacts que votre serveur a reçus et renvoyés. Cette boucle de rétroaction immédiate déplace la détection des défauts très tôt dans le cycle, là où ils coûtent le moins cher à corriger. Gardez l’inspecteur ouvert dans un onglet pour la suite du cours : vous y reviendrez à chaque nouvelle primitive ajoutée au serveur.

À vous de jouer

1. Lancez mcp dev mcp_server.py, ouvrez l’URL complète, connectez le serveur et retrouvez dans la colonne Protocol les six messages de la découverte.
2. Exécutez edit_document sur plan.md (remplacez « étapes » par « phases »), puis read_doc_contents sur le même document : la modification est-elle visible ?
3. Provoquez une erreur avec un identifiant inconnu, d’abord avec ValueError, puis avec ToolError : comparez les deux messages dans Results.
4. Dépliez une entrée tools/call dans la colonne Protocol et lisez la requête et la réponse JSON brutes : c’est ce qui circule entre client et serveur.

Sources officielles : The server inspector (Claude Academy) · MCP Inspector · Client web, onglet par onglet · Ères de protocole · Configuration et variables d’environnement

Points clés à retenir

• mcp dev mcp_server.py lance l’Inspector MCP (un outil Node, 22.19+) ; ouvrez l’URL complète avec son jeton de session.
• Servers (connexion), puis Tools, Prompts, Resources : un onglet par primitive annoncée ; la colonne Protocol enregistre chaque message JSON-RPC.
• La découverte à la connexion envoie tools/list, resources/list, resources/templates/list et prompts/list ; par défaut l’inspecteur parle l’ère « legacy » (poignée de main initialize), réglable en auto ou modern.
• Le formulaire d’un outil est généré depuis son schéma ; le serveur garde son état entre les appels ; testez les erreurs, et levez ToolError pour qu’elles soient lisibles.
• L’inspecteur est votre boucle de retour la plus courte : gardez-le ouvert à chaque primitive ajoutée.