mcpsnoop v0.22.0

Wireshark pour MCP. mcpsnoop s'intercale entre votre client IA et votre serveur MCP et enregistre chaque trame JSON-RPC qu'ils échangent, sans modifier ni l'un ni l'autre. Observez-le en direct dans votre terminal, faites échouer la CI sur ce qu'il détecte, ou envoyez-le à votre backend de traçage sous forme de spans OpenTelemetry.

Le problème

L'MCP Inspector officiel se connecte en tant que client à part entière, il ne voit donc jamais ce que votre client (Cursor, Claude Code, Codex) envoie réellement à votre serveur. Et tout ce qui attend qu'une requête arrive ne peut pas montrer l'appel que le modèle n'a jamais effectué, ou qu'il a effectué avec les mauvais arguments. Quand un outil n'est silencieusement pas appelé, que les capacités ne correspondent pas, ou qu'un appel reste bloqué, vous vous retrouvez à fouiller les journaux et à deviner.

mcpsnoop s'installe à la place dans le véritable chemin des données. Enveloppez votre commande de serveur avec lui et observez chaque trame JSON-RPC en direct, pendant que votre véritable client et votre serveur dialoguent.

En CI

Cette page sert aussi de fiche pour la GitHub Action mcpsnoop, en voici donc l'intégralité. Elle vérifie une session capturée, consigne chaque constat comme une alerte d'analyse de code, et fait échouer la tâche sur ce que vous avez défini comme critère.

permissions:
  security-events: write
  contents: read

steps:
  - uses: kerlenton/[email protected]
    with:
      session: artifacts/session.jsonl

Pas de capture sous la main ? Enregistrez une session avec votre propre client une fois, validez-la, et laissez l'action la rejouer contre chaque build. Aucun modèle et aucune clé API ne s'exécutent en CI. La relecture est vérifiée comme n'importe quelle capture, et la tâche échoue également lorsque le serveur s'est dégradé par rapport à l'enregistrement. Un serveur atteint via Streamable HTTP reçoit target avec son endpoint, et un enregistrement se rejoue sur l'un ou l'autre transport.

steps:
  - uses: kerlenton/[email protected]
    with:
      replay: tests/mcp/claude-code-session.jsonl
      server: node dist/index.js

Épinglez la version que vous souhaitez. La plus récente se trouve sur la page des releases. Chaque entrée et sortie est décrite dans The GitHub Action plus bas, et chaque signal sur lequel la vérification peut échouer se trouve dans docs/CI.md.

OpenTelemetry

La révision MCP 2026-07-28 déprécie le Logging au niveau du protocole et indique aux implémentations de passer à stderr sur stdio, ou à OpenTelemetry pour une observabilité structurée. mcpsnoop couvre les deux sans toucher au client ni au serveur. Les lignes stderr d'un serveur stdio apparaissent dans le flux à côté de ses trames, et chaque requête devient un span qui suit les conventions sémantiques OpenTelemetry pour MCP.

mcpsnoop export -T otlp -o trace.json   # spans from a capture
mcpsnoop --otlp-endpoint http://localhost:4318/v1/traces -- node build/index.js   # spans as calls complete

Un appel d'outil arrive sous la forme d'un span nommé tools/call search, portant mcp.method.name, gen_ai.tool.name et error.type, de sorte qu'il atterrit dans un tableau de bord conçu pour MCP plutôt que pour mcpsnoop. Les métriques d'outils en direct pour Prometheus sont à un flag près. Les deux sont dans docs/OPENTELEMETRY.md.

Démarrage rapide

Voyez-le immédiatement, sans rien à configurer.

mcpsnoop demo

Pour l'utiliser réellement, encapsulez votre serveur dans la configuration MCP de votre client.

{
  "mcpServers": {
    "my-server": {
      "command": "mcpsnoop",
      "args": ["--", "node", "build/index.js"]
    }
  }
}

Tout ce qui suit -- est la commande qui lance normalement votre serveur. Remplacez-la par ce que vous utilisez déjà, comme python server.py, npx -y @scope/server, ou un binaire compilé.

Sur Claude Desktop, vous n'avez pas besoin de faire cette modification à la main.

mcpsnoop wrap my-server     # route my-server through mcpsnoop
mcpsnoop unwrap my-server   # put it back

wrap trouve claude_desktop_config.json, le copie vers claude_desktop_config.json.mcpsnoop.bak la première fois, et ne réécrit que l'entrée de ce seul serveur, de sorte que votre mise en forme et tous les autres serveurs restent intacts. À l'intérieur de l'entrée réécrite, les clés reviennent dans l'ordre alphabétique. unwrap restaure le fichier, et supprime la sauvegarde une fois qu'aucun serveur n'est plus enveloppé. Redémarrez Claude Desktop après l'une ou l'autre opération, car les serveurs MCP sont lancés une seule fois au démarrage.

Utilisez ensuite votre client comme d'habitude et ouvrez l'interface.

mcpsnoop

Aucun flag, aucun chemin de socket, aucun ordre de démarrage à mémoriser. Le shim et l'interface se trouvent d'eux-mêmes, et l'interface récupère les sessions passées depuis le disque.

Pour un serveur HTTP streamable, exécutez mcpsnoop en tant que proxy inverse.

mcpsnoop http --target http://localhost:3000/mcp --listen :7000

Le statut HTTP de chaque réponse apparaît dans le flux, de sorte qu'une réponse qui ne porte aucun message JSON-RPC propre reste une trame visible plutôt que rien. Cela couvre le défi 401, le 403 sur une Origin rejetée, le 202 qui accuse réception d'une notification, et le 502 lorsque la cible est totalement inaccessible. L'en-tête WWW-Authenticate d'une réponse 401 est conservé verbatim et affiché dans l'inspecteur, puisqu'il nomme le schéma d'authentification et les métadonnées de ressource vers lesquelles se diriger ensuite. Filtrez par statut avec status:401 dans la TUI, ou par n'importe quel échec avec status:err. Un 4xx ou 5xx compte comme une erreur, donc une exécution par défaut de mcpsnoop check échoue dessus, et l'appel auquel il a répondu est considéré comme échoué plutôt que comme encore en attente.

Pas de serveur à vous ? Essayez-le pour de vrai contre un serveur de test publié, piloté par votre propre client. Pour inspecter une session après coup, voir revoir les sessions passées à partir des logs.

Installation

npm

Aucune chaîne d'outils Go nécessaire. La plupart des serveurs MCP sont écrits en Node ou en Python, c'est donc le chemin le plus court.

npx mcpsnoop -- node build/index.js