MCP Inspector - Guide pour déboguer les serveurs Model Context Protocol
MCP Inspector est l’outil officiel de test visuel et de débogage pour les serveurs Model Context Protocol. Quand vous construisez un serveur MCP, vous devez voir ce qu’il expose réellement et comment il répond — Inspector se connecte à votre serveur, liste ses outils, ressources, et prompts, vous permet d’invoquer chacun avec des arguments arbitraires, et montre les messages JSON-RPC bruts circulant dans les deux directions. C’est le moyen le plus rapide de vérifier qu’un serveur fonctionne avant de le câbler dans Claude, Cursor, ou un autre client.
L’exécuter
| Méthode | Commande |
|---|
| npx (pas d’installation) | npx @modelcontextprotocol/inspector |
| Avec votre serveur | npx @modelcontextprotocol/inspector node build/index.js |
| Serveur Python | npx @modelcontextprotocol/inspector uv run server.py |
| Serveur distante/SSE | lancer, puis entrer l’URL dans l’UI |
| UI | s’ouvre dans le navigateur (défaut http://localhost:6274) |
Types de connexion
| Transport | Utiliser |
|---|
| STDIO | Serveur local exécuté en tant que sous-processus (le plus courant) |
| SSE | Serveur distant sur Server-Sent Events |
| HTTP streamable | Transport distant moderne |
# Inspecter un serveur stdio local, en passant des args et env
npx @modelcontextprotocol/inspector \
-e API_KEY=abc123 \
node build/index.js --verbose
L’interface
| Onglet | Montre |
|---|
| Outils | Chaque outil, son schéma JSON, et un formulaire pour l’appeler |
| Ressources | Ressources exposées et leur contenu |
| Prompts | Modèles de prompt et leurs arguments |
| Notifications | Messages/logs initiés par le serveur |
| Historique | Chaque paire request/response |
Tester les outils
| Étape | Action |
|---|
| 1 | Ouvrir l’onglet Outils ; confirmer que votre outil est listé |
| 2 | Vérifier que le schéma d’entrée se rend correctement (types, champs requis) |
| 3 | Remplir le formulaire généré et cliquer pour invoquer |
| 4 | Inspecter le contenu retourné et n’importe quel flag isError |
| 5 | Lire le JSON-RPC brut dans Historique pour déboguer les problèmes de forme |
Cette boucle attrape les bugs MCP les plus courants : un schéma malformé, un outil qui retourne la mauvaise forme de contenu, ou une erreur non-gérée.
Ce qu’il faut vérifier avant de déployer
| Vérification | Pourquoi |
|---|
| Les noms d’outils sont uniques/descriptifs | Les clients les surfacent au modèle |
| Les descriptions expliquent quand utiliser l’outil | Dirige la sélection correcte du modèle |
| Le schéma d’entrée est précis | Prévient les appels malformés |
Les erreurs retournent isError avec un message | Le modèle peut récupérer |
| Les sorties importantes sont paginées/tronquées | Évite de faire exploser la fenêtre de contexte |
| Les ressources ont des URIs stables | Les clients les mettent en cache/référence |
Astuces de débogage
| Symptôme | Regarder |
|---|
| Le serveur ne se connecte pas | Commande/args ; stderr dans le terminal de lancement |
| Outil manquant | Code d’enregistrement ; redémarrer le serveur |
| Schéma se rend bizarrement | Types de schéma JSON dans la définition de l’outil |
| Le client se comporte différemment | Comparer le JSON-RPC brut dans Historique |
| Bug dépendant d’env | Relancer Inspector avec -e KEY=value |
Flux de travail courants
# Boucle développer-et-tester pour un serveur MCP TypeScript
npm run build && npx @modelcontextprotocol/inspector node build/index.js
# Tester un serveur Python avec uv
npx @modelcontextprotocol/inspector uv run my_server.py
# Vérifier un serveur SSE distant avant de l'ajouter à un client
npx @modelcontextprotocol/inspector # choisir SSE, coller l'URL
MCP Inspector vs alternatives
| Approche | Trade-off |
|---|
| MCP Inspector | Construit pour cela, visuel, montre le protocole brut |
| Câbler dans un client réel | Réaliste mais boucle feedback lente |
| JSON-RPC écrit à la main | Contrôle complet, fastidieux |
| Tests unitaires | Rapide et répétable ; associer avec Inspector pour l’exploration |
Utiliser Inspector pendant la construction, puis ajouter des tests automatisés ; voir MCP servers pour les patterns d’implémentation du serveur.
Ressources
