mcpsnoop v0.22.0

Wireshark für MCP. mcpsnoop sitzt zwischen deinem KI-Client und deinem MCP-Server und zeichnet jeden JSON-RPC-Frame auf, den beide austauschen, ohne dass eine der beiden Seiten geändert werden muss. Beobachte es live in deinem Terminal, lass CI aufgrund der Befunde fehlschlagen oder sende es als OpenTelemetry-Spans an dein Tracing-Backend.

Das Problem

Der offizielle MCP Inspector verbindet sich als eigener Client und sieht daher nie, was dein Client (Cursor, Claude Code, Codex) tatsächlich an deinen Server sendet. Und alles, was auf das Eintreffen einer Anfrage wartet, kann den Aufruf nicht zeigen, den das Modell nie ausgeführt hat oder mit den falschen Argumenten ausgeführt hat. Wenn ein Tool stillschweigend nicht aufgerufen wird, die Capabilities nicht zusammenpassen oder ein Aufruf einfach hängt, bleibt dir nur das Durchwühlen von Logs und Raten.

mcpsnoop sitzt stattdessen im echten Datenpfad. Umgib deinen Server-Befehl damit und beobachte jeden JSON-RPC-Frame live, während dein echter Client und Server kommunizieren.

In CI

Diese Seite ist auch der Eintrag für die mcpsnoop GitHub Action, hier also der vollständige Inhalt. Sie prüft eine aufgezeichnete Sitzung, meldet jeden Befund als Code-Scanning-Alert und lässt den Job anhand dessen fehlschlagen, worauf du die Prüfung beschränkt hast.

permissions:
  security-events: write
  contents: read

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

Keine Aufzeichnung zur Hand? Zeichnen Sie einmal eine Sitzung mit Ihrem eigenen Client auf, committen Sie sie und lassen Sie die Action sie gegen jeden Build erneut abspielen. In CI läuft weder ein Modell noch ein API-Schlüssel. Die Wiedergabe wird wie jede Aufzeichnung geprüft, und der Job schlägt auch fehl, wenn der Server schlechter geworden ist als in der Aufzeichnung. Ein Server, der über Streamable HTTP erreicht wird, erhält target mit seinem Endpoint, und eine Aufzeichnung lässt sich über beide Transportwege wiedergeben.

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

Binden Sie die gewünschte Version ein. Die neueste finden Sie auf der Releases-Seite. Jede Eingabe und Ausgabe ist weiter unten in The GitHub Action aufgeführt, und jedes Signal, bei dem die Prüfung fehlschlagen kann, ist in docs/CI.md dokumentiert.

OpenTelemetry

MCP-Revision 2026-07-28 stuft Logging auf Protokollebene als veraltet ein und weist Implementierungen an, auf stderr bei stdio oder auf OpenTelemetry für strukturierte Observability umzusteigen. mcpsnoop deckt beides ab, ohne den Client oder den Server zu verändern. Die stderr-Zeilen eines stdio-Servers erscheinen im Stream neben seinen Frames, und jede Anfrage wird zu einem Span, der den OpenTelemetry-Semantikkonventionen für MCP folgt.

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

Ein Tool-Aufruf kommt als Span namens tools/call search an und trägt mcp.method.name, gen_ai.tool.name und error.type, sodass er in einem für MCP gebauten Dashboard landet statt in einem für mcpsnoop gebauten. Live-Tool-Metriken für Prometheus sind nur einen Flag entfernt. Beides ist in docs/OPENTELEMETRY.md beschrieben.

Schnellstart

Sofort ansehen, ohne etwas einrichten zu müssen.

mcpsnoop demo

Um es tatsächlich zu nutzen, binden Sie Ihren Server in die MCP-Konfiguration Ihres Clients ein.

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

Alles nach -- ist der Befehl, der normalerweise deinen Server startet. Ersetze ihn durch das, was du bereits verwendest, etwa python server.py, npx -y @scope/server oder eine kompilierte Binärdatei.

Auf Claude Desktop musst du diese Änderung nicht von Hand vornehmen.

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

wrap findet claude_desktop_config.json, kopiert die Datei beim ersten Mal nach claude_desktop_config.json.mcpsnoop.bak und schreibt nur den Eintrag dieses einen Servers um, sodass deine Formatierung und alle anderen Server unangetastet bleiben. Innerhalb des umgeschriebenen Eintrags werden die Schlüssel in alphabetischer Reihenfolge zurückgegeben. unwrap stellt die Datei wieder her und entfernt die Sicherung, sobald kein Server mehr umschlossen ist. Starte Claude Desktop nach beidem neu, da MCP-Server beim Start einmalig gestartet werden.

Verwende dann deinen Client wie gewohnt und öffne die UI.

mcpsnoop

Keine Flags, keine Socket-Pfade, keine Startreihenfolge, an die man sich erinnern muss. Das Shim und die UI finden sich von selbst, und die UI füllt vergangene Sitzungen von der Festplatte nach.

Für einen streamable-HTTP-Server führen Sie mcpsnoop als Reverse-Proxy aus.

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

Der HTTP-Status jeder Antwort erscheint im Stream, sodass eine Antwort, die keine eigene JSON-RPC-Nachricht enthält, dennoch als sichtbarer Frame erscheint und nicht als nichts. Das umfasst die 401-Herausforderung, die 403 bei einem abgelehnten Origin, die 202, die eine Benachrichtigung bestätigt, und die 502, wenn das Ziel überhaupt nicht erreichbar ist. Der WWW-Authenticate-Header einer 401 wird unverändert beibehalten und im Inspector angezeigt, da er das Authentifizierungsschema und die Ressourcen-Metadaten benennt, zu denen als Nächstes gegangen werden soll. Filtere nach Status mit status:401 in der TUI oder nach jedem Fehler mit status:err. Ein 4xx oder 5xx zählt als Fehler, sodass ein standardmäßiger mcpsnoop check-Lauf daran scheitert, und der beantwortete Aufruf gilt als fehlgeschlagen und nicht als noch wartend.

Kein eigener Server? Probiere es live aus gegen einen veröffentlichten Testserver, gesteuert von deinem eigenen Client. Um eine Sitzung im Nachhinein zu inspizieren, siehe vergangene Sitzungen aus Logs überprüfen.

Installation

npm

Keine Go-Toolchain erforderlich. Die meisten MCP-Server sind in Node oder Python geschrieben, daher ist dies der kürzeste Weg.

npx mcpsnoop -- node build/index.js