Comment tester et déboguer des serveurs MCP avec MCP Inspector

Si vous êtes arrivé ici en recherchant « MCP Inspector ne se connecte pas » ou « comment tester mon serveur MCP », vous êtes au bon endroit. Et si votre serveur compile sans problème, mais que vous ignorez s’il se comporte réellement correctement jusqu’à ce qu’un vrai client échoue dessus, cet article est précisément fait pour vous.

MCP Inspector vous offre une boucle de débogage complète, adaptée au transport, pour tout serveur MCP que vous développez ou maintenez. Mais uniquement si vous configurez correctement le type de transport, les chemins et l’authentification dès le départ. Faites une erreur sur l’un de ces trois éléments, et vous passerez une heure à chercher une erreur de connexion qui n’a rien à voir avec le code de votre serveur.

Ce qui échoue avant même la connexion

• MCP Inspector affiche séparément les outils, les ressources et les prompts, afin que vous puissiez valider chaque primitive du protocole indépendamment.
• Un mauvais type de transport produit des délais d’attente silencieux, pas des erreurs utiles ; c’est l’origine de la plupart des tickets de configuration.
• Les serveurs HTTP nécessitent le segment de chemin /mcp ; l’omettre entraîne des échecs de routage, même lorsque le serveur répond aux requêtes ping.
• Un test Inspector réussi confirme une connexion propre et des schémas corrects, mais pas que votre client de production se comportera de manière identique.

Prérequis pour exécuter MCP Inspector

Préparez ces éléments avant de toucher à Inspector. L’absence de l’un d’entre eux génère un mode d’échec différent et déroutant.

• Node.js et npm installés

  Inspector est lancé via npx, fourni avec npm. Sans Node.js sur votre machine, la commande CLI échoue immédiatement avec une erreur « command not found » qui ressemble à un problème d’Inspector, mais ce n’en est pas un. C’est un problème d’environnement d’exécution.

• Un serveur MCP en cours d’exécution avant la connexion

  Il s’agit d’un outil open source pour les développeurs destiné aux tests et au débogage : il ne démarre pas votre serveur à votre place. Si le processus serveur n’est pas déjà actif, Inspector tentera une connexion, expirera, puis vous affichera une erreur qui ressemble à une mauvaise configuration du transport. Le serveur doit être actif avant qu’Inspector n’entre en jeu.

• Un navigateur moderne pour l’interface graphique

  Inspector fournit son interface depuis un processus Node local sur le port 6274. Utilisez Chrome ou Firefox dans une version actuelle. Des navigateurs plus anciens peuvent empêcher le rendu de l’interface. L’outil est une interface graphique basée sur un navigateur, pas une application de bureau, ce qui surprend beaucoup de personnes la première fois.

• VS Code avec l’extension MCP installée (si vous utilisez la variante IDE)

  Inspector intégré, disponible dans VS Code et dans des IDE similaires, nécessite l’installation de l’extension avant que le lancement automatique fonctionne. Ignorer cette étape et s’attendre à ce que la voie npx lance la variante intégrée à l’IDE ne produit rien d’utile.

• Identifiants OAuth prêts si votre serveur requiert une authentification

  Vous devez disposer du Client ID, du client secret et de l’URL de redirection avant de vous connecter à un serveur protégé par authentification. Essayer de résoudre les identifiants après l’ouverture d’Inspector mène à des flux partiels, à une confusion autour de l’état de session et à des erreurs de jeton qui ressemblent à des problèmes de serveur.

Premiers pas : comment lancer MCP Inspector

Il existe deux principales façons de démarrer Inspector. La voie CLI via npx est la plus directe et fonctionne partout où Node est installé. La voie intégrée à l’IDE se lance automatiquement dans votre environnement de développement si vous disposez de la bonne extension. Les deux servent la même interface basée sur navigateur sur localhost.

Exécuter MCP Inspector via la CLI npx

Ouvrez votre terminal et exécutez :

npx @modelcontextprotocol/inspector@latest

C’est tout pour la commande. Voici ce qui se passe ensuite : un processus Node local démarre et Inspector sert son interface dans le navigateur, par défaut à l’adresse http://localhost:6274. Votre navigateur devrait s’ouvrir automatiquement. Sinon, accédez-y manuellement.

Ce que les utilisateurs manquent souvent à ce stade des premiers pas, c’est qu’ils s’attendent à une application de bureau. Inspector n’en est pas une. C’est un onglet de navigateur servi par un serveur local. Cela signifie que si vous fermez le terminal, l’interface disparaît. Gardez le processus actif pendant que vous utilisez l’interface d’Inspector.

Lorsque vous transmettez directement une commande de serveur via la CLI, Inspector peut également lancer le processus du serveur stdio en ligne pour vous, par exemple :

npx @modelcontextprotocol/inspector node /absolute/path/to/server.js

C’est un raccourci utile lorsque vous utilisez MCP Inspector avec un serveur stdio local. La ligne de commande devient la connexion.

Exécuter MCP Inspector depuis un IDE ou un environnement intégré

Certains environnements, notamment VS Code avec l’extension MCP installée, intègrent Inspector et lancent automatiquement l’interface du navigateur lorsque vous l’activez depuis l’IDE. Le dépôt officiel sur GitHub est la source de référence pour les détails d’architecture et les comportements spécifiques à chaque version.

Ces variantes intégrées à l’IDE gèrent plus directement l’intégration avec Claude Desktop, car l’extension connaît le contexte de votre espace de travail. Toutefois, l’extension doit d’abord être installée. Essayer d’invoquer Inspector depuis VS Code sans celle-ci ne produit rien : aucune erreur, aucune interface, aucun retour utile. Installez l’extension, puis déclenchez-le.

Choisir le bon transport : stdio, SSE et HTTP Streamable

C’est là que naissent la plupart des tickets de support. Un mauvais type de transport ne produit pas une erreur claire. Il génère un délai d’attente silencieux ou un échec de handshake sans message expliquant ce qui s’est mal passé. Vous regarderez l’indicateur de statut de connexion tourner et supposerez que le serveur est indisponible. Il ne l’est probablement pas.

MCP prend en charge trois modes de transport distincts, qui ne sont pas interchangeables. Sélectionner le mauvais dans Inspector revient exactement à essayer de parler français à quelqu’un qui ne parle que portugais : vous êtes techniquement dans la même réunion, mais rien ne passe.

Configurer le transport stdio : commande, arguments et chemins absolus

Utilisez le transport stdio lorsque votre serveur MCP s’exécute en tant que processus enfant local, démarré directement par Inspector ou par un client. La configuration du serveur dans Inspector exige deux champs : Commande (l’exécutable) et Arguments (les indicateurs ou chemins de fichiers).

L’erreur de configuration la plus fréquente que je rencontre avec stdio : utiliser un chemin relatif plutôt qu’un chemin absolu. Les chemins relatifs échouent silencieusement lors du démarrage du processus serveur. L’erreur renvoyée ne dit pas « mauvais chemin ». La connexion ne s’établit simplement pas. Utilisez systématiquement le chemin absolu complet.

Une configuration stdio valide ressemble à ceci :

Transmettez les variables d’environnement via le champ Environnement, et non en modifiant votre session shell. Inspector doit pouvoir les voir au niveau du processus.

Configurer les transports HTTP et SSE : format de l’URL et chemin /mcp

Utilisez le transport HTTP ou SSE lorsque votre serveur MCP expose un endpoint HTTP, localement ou à distance. La documentation Cloudflare Agents recommande explicitement cette approche pour tester des serveurs MCP et des passerelles distants avant de les connecter à un agent.

Le champ URL configurable est simple. Le piège se trouve dans le segment de chemin. Pour les serveurs qui implémentent le protocole MCP via HTTP, l’URL doit inclure /mcp à la fin :

https://your-server.example.com/mcp

Omettre /mcp provoque des échecs de routage qui ressemblent à des erreurs de connexion, même lorsque le serveur est parfaitement accessible. Le serveur répond à sa racine. L’endpoint du protocole MCP, lui, n’y répond pas. Vous obtiendrez une erreur 404 ou un délai d’attente silencieux selon la manière dont le serveur traite les routes non reconnues. Ajoutez ce segment de chemin : il n’est pas facultatif.

Si vous devez exposer des en-têtes personnalisés, tels qu’un en-tête Authorization pour une passerelle, la configuration du transport HTTP d’Inspector inclut une section En-têtes. Ajoutez-les avant de vous connecter.

Comment gérer l’authentification pour les serveurs MCP sécurisés par OAuth

Les échecs d’authentification dans MCP Inspector sont presque toujours des problèmes d’ordre de configuration, et non des problèmes de serveur. Le serveur est accessible. Les identifiants existent. Mais un élément n’a pas été renseigné avant la tentative de connexion, ou pas dans le bon ordre, et le jeton est absent ou invalide lorsqu’Inspector effectue sa première requête.

Je retrouve constamment ce schéma : une personne débogue pendant 45 minutes en supposant que le serveur MCP présente un bug, puis découvre que le champ du jeton de session proxy est resté vide tout ce temps. Les messages d’erreur d’authentification côté client sont souvent silencieux ou trompeurs ; cela signifie que le signal dont vous avez besoin se trouve dans Inspector, pas dans les journaux de votre serveur.

Enregistrer le client MCP Inspector auprès de votre fournisseur d’identité

Avant qu’Inspector puisse terminer un flux OAuth, votre fournisseur d’identité doit savoir qu’Inspector existe en tant que client. Pour Auth0 et les fournisseurs similaires, cela implique de créer une application représentant le client Inspector et d’obtenir ses identifiants.

Vous aurez besoin d’un Client ID, d’un Client Secret et d’une URL de redirection enregistrée. L’URL de redirection doit correspondre exactement à celle attendue par Inspector, généralement quelque chose comme http://localhost:6274/oauth/callback. Une divergence à ce niveau fait échouer le flux de consentement à l’étape de redirection, avec une erreur générique qui ressemble à un problème d’autorisation.

Deux méthodes d’enregistrement existent :

Si votre fournisseur d’identité prend en charge DCR, Inspector peut gérer lui-même le flux d’enregistrement. Sinon, vous devez effectuer un enregistrement statique. Consultez la documentation de votre fournisseur : Auth0 prend en charge les deux, mais DCR requiert un indicateur de configuration explicite pour être activé. Une erreur à ce niveau signifie qu’Inspector arrive avec des identifiants que le fournisseur ne reconnaît pas, et vous obtenez une erreur 401 qui n’a rien à voir avec votre serveur MCP.

Côté autorisations, ne désactivez pas les scopes dans le but de simplifier la configuration. Le serveur MCP a besoin de scopes spécifiques pour exposer correctement ses outils. Des autorisations trop restrictives produisent des listes d’outils partielles et des erreurs 403 en cours de session qui ressemblent à des bugs d’Inspector.

Terminer le flux OAuth et saisir les identifiants dans Inspector

Dans l’interface d’Inspector, saisissez votre Client ID, votre Client Secret et le jeton de session proxy dans la section de configuration de l’authentification avant de cliquer sur Connecter. Cet ordre est important. Cliquer d’abord sur Connecter en pensant pouvoir saisir les identifiants dans une fenêtre contextuelle n’est pas le fonctionnement du flux.

Une fois que vous cliquez sur Connecter avec les identifiants en place, Inspector déclenche l’écran de consentement dans le navigateur. Terminez la connexion et acceptez les autorisations. Après cette redirection, Inspector détient un jeton de session actif et vous pouvez passer à l’onglet Outils.

Le jeton de session proxy est l’élément que la plupart des utilisateurs négligent. Il est distinct des identifiants client OAuth. C’est ce qui permet à la couche proxy d’Inspector de maintenir la session entre votre navigateur et le serveur MCP. Laissez-le vide et vous recevrez une erreur « token missing », même si l’endpoint serveur est parfaitement accessible et que les identifiants OAuth sont corrects.

C’est généralement à cet endroit que le ticket commence.

Comment tester des serveurs MCP : découverte et exécution d’outils

Une fois connecté, le workflow de test principal comporte trois étapes : Connecter, Lister les outils, Exécuter l’outil. Cette séquence résume l’essentiel. Son utilité repose sur une lecture attentive de ce qui est renvoyé à chaque étape.

Une connexion réussie affiche un indicateur de statut vert dans Inspector, avec le nom du serveur et la version du protocole visibles. Si vous voyez cela, vous n’avez pas terminé les tests : vous avez terminé la connexion. Les tests commencent maintenant.

Utiliser l’onglet Outils pour lister et inspecter les schémas d’outils

Cliquez sur Lister les outils dans l’onglet Outils. Inspector envoie la requête MCP tools/list à votre serveur et affiche la réponse : noms des outils, descriptions et schéma JSON complet des paramètres de chaque outil.

C’est ici que vous validez plusieurs éléments à la fois. Les noms des outils sont-ils corrects ? Les descriptions des paramètres sont-elles exactes ? Les paramètres obligatoires apparaissent-ils comme obligatoires dans le schéma ? Le schéma d’entrée correspond-il à ce que votre serveur attend réellement ?

Pour les serveurs qui exposent plusieurs espaces de noms d’outils, ce qui est courant avec les serveurs MCP Ontology ou tout serveur encapsulant plusieurs API backend, la liste des outils permet de confirmer que les frontières entre espaces de noms fonctionnent. Un schéma qui affiche le mauvais type de paramètre pour un outil est un bug du serveur ; il vaut mieux le détecter ici que dans un agent de production qui transmet silencieusement le mauvais type et reçoit des données incohérentes.

Inspectez directement le schéma JSON brut dans Inspector avant d’exécuter quoi que ce soit. Cela prend 30 secondes et permet de détecter de vrais bugs qui ne seraient apparus qu’à la troisième ou quatrième invocation d’outil.

Exécuter un outil et lire la réponse en temps réel

Sélectionnez un outil dans la liste. Inspector affiche un formulaire basé sur le schéma d’entrée de l’outil : renseignez les paramètres obligatoires, ajoutez les paramètres facultatifs pertinents pour votre test, puis cliquez sur Exécuter l’outil.

Inspector affiche la charge utile brute de la requête envoyée et la réponse brute reçue. Lisez les deux. La requête vous montre ce qu’Inspector a réellement sérialisé à partir de vos entrées de paramètres, ce qui est utile pour détecter les coercitions de type. La réponse affiche la sortie complète du serveur, y compris toute charge utile d’erreur.

Pour un critère de réussite pratique, exécutez deux fois le même outil avec des entrées identiques. Les réponses doivent être identiques, ou différentes de manière déterministe si l’outil interroge des données en temps réel. Des réponses incohérentes avec des entrées identiques indiquent généralement un problème d’état côté serveur ou une condition de concurrence dans l’implémentation de l’outil. Exécutez-le cinq fois si l’outil interagit avec des API externes : le comportement face aux limites de débit et la gestion des délais d’attente se révèlent lors d’exécutions répétées d’une façon qu’un test unique ne montre pas.

Le guide de Chris Ebert sur le serveur MCP de documentation AWS dans Inspector est une bonne référence pour comprendre à quoi ressemble un workflow d’invocation d’outil propre de bout en bout : vous pouvez voir les paramètres de l’outil search_documentation, le schéma et la manière d’interpréter la réponse avant de connecter le serveur à un agent.

📊 En pratique :
Un test Inspector réussi confirme un statut de connexion propre, des schémas d’outils corrects et des réponses cohérentes pour les entrées attendues. Il ne confirme pas que votre client MCP de production, qu’il s’agisse d’un IDE IA, de Claude Desktop ou d’un framework d’agent, gérera les cas limites de la même manière. Inspector valide le comportement protocolaire de votre serveur. Le client introduit sa propre couche d’interprétation.

Déboguer les erreurs de serveur MCP : journaux, requêtes et vues au niveau du protocole

Lorsqu’un échec survient dans Inspector, la disposition en onglets est l’endroit où déterminer à quel niveau il s’est produit. Les onglets ne sont pas décoratifs. Chacun expose une couche différente de l’interaction avec le protocole.

Les serveurs MCP exposent trois primitives principales : des ressources pour le contexte, des outils pour les actions et des prompts pour les interactions basées sur des modèles. La discussion de la communauté GitHub sur l’architecture MCP les décrit clairement. Inspector expose les trois séparément, ce qui vous permet de les valider chacune indépendamment au lieu de supposer qu’une liste d’outils fonctionnelle signifie que tout le reste fonctionne. Ce n’est pas le cas.

Lire le panneau de sortie des erreurs et les journaux de requêtes/réponses

Le panneau de sortie des erreurs affiche les messages côté serveur, la sortie stderr et les codes d’erreur au niveau du protocole. Si l’invocation d’un outil échoue, commencez ici. Une erreur 401 signifie un problème de jeton d’authentification. Une erreur de non-conformité du schéma signifie que votre serveur renvoie une réponse qui ne correspond pas à ce que le schéma de l’outil a déclaré. Un délai d’attente sans code d’erreur signifie généralement que le serveur a reçu la requête puis a cessé de répondre pendant l’exécution.

Les journaux de requêtes/réponses affichent les messages bruts du protocole MCP, y compris le handshake d’initialisation. C’est ici que vous inspectez les charges utiles et les détails du protocole dans leur intégralité. Si le handshake affiche une incompatibilité inattendue de capabilities, c’est souvent la cause profonde d’outils qui ne peuvent pas être listés alors même que la connexion semble active. Consultez le journal avant de supposer que le code serveur est incorrect. Le problème se situe fréquemment à l’étape de négociation.

Utilisez les onglets Prompts et Ressources de la même manière : listez-les, inspectez leurs schémas, invoquez-les avec des entrées de test. Un serveur qui liste correctement les outils mais renvoie des URI de ressources mal formées échouera dans certains workflows d’agent combinant appels d’outils et récupération de contexte. Détectez cela maintenant, pas après avoir intégré le serveur dans un workflow IA de production.

Itérez en modifiant le code serveur, en vous reconnectant et en relançant les tests. Inspector ne conserve pas les sessions entre les redémarrages du serveur, mais la reconnexion est rapide, et cette boucle (modifier le code → redémarrer le serveur → reconnecter Inspector → réexécuter l’outil) constitue le rythme de développement central de tout travail sur un serveur MCP.

Résoudre les erreurs de connexion et les mauvaises configurations courantes

Lorsque la connexion échoue, parcourez cette liste avant de supposer que le serveur présente un bug :

• Serveur non démarré avant la connexion

  Inspector ne peut pas démarrer votre serveur dans la plupart des configurations. Si le processus n’est pas actif, la connexion expirera. Démarrez le serveur, confirmez qu’il accepte les connexions, puis ouvrez Inspector.

• Mauvais type de transport sélectionné

  Un serveur stdio configuré comme HTTP, ou inversement, produit un échec de handshake sans message de diagnostic utile. Regardez comment votre serveur démarre : s’il s’agit d’un processus enfant, c’est stdio. S’il se lie à un port, c’est HTTP ou SSE.

• Segment de chemin /mcp absent de l’URL

  Pour les transports HTTP/HTTP Streamable, l’URL doit se terminer par /mcp afin que le routage du protocole fonctionne correctement. Le fait qu’un serveur soit accessible à sa racine ne signifie pas que l’endpoint MCP est accessible.

• Jeton d’authentification ou jeton de session proxy non saisi avant la connexion

  Saisissez tous les identifiants avant de cliquer sur Connecter. Les saisir après une tentative de connexion échouée laisse Inspector dans un état partiel qui exige parfois un rechargement complet pour être réinitialisé.

• Chemin relatif dans la configuration stdio

  Utilisez des chemins absolus pour la commande du serveur. Les chemins relatifs échouent silencieusement lors du démarrage du processus, ce qui ressemble à une erreur de connexion.

🤔 Attendez.
Inspector valide que votre serveur se comporte correctement pendant une session Inspector. Mais votre client MCP de production, qu’il s’agisse d’une configuration Claude Desktop, d’un IDE IA ou d’un agent personnalisé, possède sa propre interprétation du protocole, son propre comportement de nouvelle tentative et sa propre logique de délai d’attente. Les développeurs découvrent régulièrement des divergences uniquement après être passés d’Inspector à leur vrai client. Inspector est une étape nécessaire, mais pas la dernière.

Un autre point utile à connaître concernant la boucle de débogage : si votre serveur MCP gère des appels authentifiés et que vous observez des échecs d’authentification intermittents qui ne se reproduisent pas systématiquement dans Inspector, le problème vient souvent du scope du jeton plutôt que de sa validité. Dans Latenode, lorsque les ingénieurs connectent un serveur MCP à un workflow d’automatisation en plusieurs étapes, ils ajoutent un nœud JavaScript qui consigne le jeton exact, les scopes et le corps de requête à chaque appel. Ainsi, lorsqu’une erreur 401 survient, ils disposent du contexte complet en un seul endroit au lieu de le reconstituer à partir de trois journaux différents. Ce modèle est directement utile ici : intégrez la journalisation au workflow avant de supposer que le serveur est défaillant.