Comment déboguer un serveur MCP avec l’inspecteur d’Anthropic

La création de serveurs MCP est devenue courante. Les développeurs adoptent avec enthousiasme l’ère des LLM en participant à la révolution MCP d’Anthropic et en créant activement des serveurs MCP. Quelques lignes de code suffisent pour démarrer avec un serveur MCP, mais comment le déboguer lorsqu’il se comporte de façon inattendue ?

Premiers pas avec un serveur MCP simple dans Node.js

Pour déboguer un serveur MCP, commençons par une implémentation très simple dans Node.js. Ce serveur MCP expose un outil qui permet aux développeurs de clients MCP, comme Cursor, Qodo, Claude Desktop et d’autres, d’obtenir des informations sur des packages open source tiers.

Le code complet du serveur MCP est disponible dans le dépôt snyk-labs/mcp-server-npm sur GitHub. En voici le code intégral :

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
import { execSync } from "child_process";

const server = new McpServer({
  name: "npm JavaScript package management tools",
  version: "1.0.0",
  description: "Provides tools to get information about open source npm packages from the npmjs registry"
});

server.tool(
  "getNpmPackageInfo",
  "Get information about an npm package",
  {
    packageName: z.string()
  },
  async ({ packageName }) => {    
    const output = execSync(`npm view ${packageName}`, {
      encoding: "utf-8",
    });

    return {
      content: [
        {
          type: "text",
          text: output
        },
      ],
    };
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);

Comme vous pouvez le constater dans le code ci-dessus, ce serveur MCP s’appuie sur l’utilitaire en ligne de commande du gestionnaire de packages npm, puis lance un processus système avec l’argument de ligne de commande view pour récupérer des informations depuis le registre npm officiel.

L’implémentation de serveur MCP ci-dessus est volontairement vulnérable à l’injection de commandes, afin de sensibiliser les développeurs aux risques de sécurité liés aux serveurs MCP malveillants et non sécurisés.

MCP Inspector d’Anthropic

Anthropic a fourni une interface utilisateur de débogage appelée MCP Inspector, dans l’espace de noms officiel du package @modelcontextprotocol : @modelcontextprotocol/inspector.

Pour un débogage ponctuel, vous pouvez le lancer avec npx, par exemple : npx @modelcontextprotocol/inspector <mcp-server-command>. Remplacez <mcp-server-command> par la commande et ses arguments pour lancer le serveur MCP.

Pour accéder rapidement à l’outil MCP Inspector, je vous recommande d’ajouter l’entrée suivante dans le fichier Node.js package.json :

{
"scripts": {
  "debug": "npx -y @modelcontextprotocol/inspector node index.js"
}
}

Lors de sa première exécution, npm run debug vous invitera à installer l’outil si vous ne fournissez pas l’argument -y à npx. Voici à quoi cela ressemble :

♥ 18:22  npm run debug           

> mcp-server-npm@1.0.0 debug
> npx @modelcontextprotocol/inspector node index.js

Need to install the following packages:
@modelcontextprotocol/inspector@0.11.0
Ok to proceed? (y)

Une fois l’installation terminée et l’outil prêt, le résultat suivant s’affichera dans la console :

Starting MCP inspector...
⚙️ Proxy server listening on port 6277
🔍 MCP Inspector is up and running at http://127.0.0.1:6274 🚀

Vous pouvez alors ouvrir http://127.0.0.1:6274 dans votre navigateur ;-)

Comme notre serveur MCP Node.js est exposé via STDIO de processus, nous conservons ce type de transport et cliquons sur le bouton Connect.

La connexion au serveur MCP affiche alors un nouvel onglet horizontal dans la zone de contenu principale, avec toutes les ressources disponibles sur le serveur. Dans notre cas, le serveur MCP n’expose que des outils (un seul, pour rechercher des informations sur un package npm dans le registre npm). En cliquant sur List Tools, vous obtenez la liste de tous les outils disponibles :

Vous pouvez maintenant interagir directement avec le serveur MCP depuis l’interface Web de MCP Inspector. Cliquez simplement sur l’un des outils répertoriés — getNpmPackageInfo dans notre cas — pour l’afficher dans le panneau de droite, avec les paramètres que vous pouvez lui fournir.

Voici une capture d’écran de son exécution avec le package snyk comme paramètre.

MCP Inspector affiche également dans la console des informations sur les interactions avec les serveurs MCP. À titre de référence, voici la sortie de débogage générée lors de l’enregistrement des appels d’outils ci-dessus :

New connection
Query parameters: [Object: null prototype] {
  command: 'node',
  args: 'index.js',
  env: '{"HOME":"/Users/lirantal","LOGNAME":"lirantal","PATH":"/Users/lirantal/.npm/,"SHELL":"/bin/zsh","TERM":"xterm-256color","USER":"lirantal"}',
  transportType: 'stdio'
}
Stdio transport: command=/Users/lirantal/.local/state/fnm_multishells/34121_1745832579143/bin/node, args=index.js
Spawned stdio transport
Connected MCP client to backing server transport
Created web app transport
Set up MCP proxy
Received message for sessionId 83514436-7b4b-492f-8026-957684f3b736
Received message for sessionId 83514436-7b4b-492f-8026-957684f3b736
Received message for sessionId 83514436-7b4b-492f-8026-957684f3b736

En savoir plus sur le débogage des serveurs MCP

Le débogage des serveurs MCP consiste souvent aussi à afficher des informations de débogage à l’écran avec console.log() en JavaScript. Toutefois, avec les serveurs MCP basés sur des processus utilisant STDIO, cela ne fonctionnera pas comme prévu. Pour le moment, je vous recommande une solution simple : écrire les journaux de débogage dans un fichier.