Um es tatsächlich zu verwenden, binden Sie Ihren Server in die MCP-Konfiguration Ihres Clients ein.```json
{
  "mcpServers": {
    "my-server": {
      "command": "mcpsnoop",
      "args": ["--", "node", "build/index.js"]
    }
  }
}

`wrap` findet `claude_desktop_config.json`, kopiert sie beim ersten Mal nach `claude_desktop_config.json.mcpsnoop.bak` und überschreibt nur den Eintrag dieses einen Servers, sodass deine Formatierung und alle anderen Server unangetastet bleiben. Im neu geschriebenen Eintrag stehen die Schlüssel wieder in alphabetischer Reihenfolge. `unwrap` stellt die Datei wieder her und entfernt das Backup, sobald kein Server mehr umhüllt ist. Starte Claude Desktop danach neu, da MCP-Server beim Programmstart nur einmal gestartet werden.

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

Der HTTP-Status jeder Antwort erscheint im Stream, sodass eine Antwort, die
keine eigene JSON-RPC-Nachricht trägt, dennoch ein sichtbarer Frame ist und nicht nichts: die
401-Herausforderung, die 403 bei abgelehntem Origin, die 202, die eine
Benachrichtigung bestätigt, und die 502, wenn das Ziel gar nicht erreichbar ist. Der
`WWW-Authenticate`-Header der 401 wird unverändert beibehalten und im Inspector angezeigt, da er
das Authentifizierungsschema und die Ressourcen-Metadaten für den nächsten Schritt nennt. Filtern Sie nach Status
mit `status:401` im TUI oder nach jedem Fehler mit `status:err`. Ein 4xx- oder 5xx-
Status zählt als Fehler, daher schlägt ein standardmäßiger `mcpsnoop check`-Lauf dabei fehl.

Keinen eigenen Server? [Probieren Sie es tatsächlich aus](https://github.com/kerlenton/mcpsnoop/blob/HEAD/docs/TRY_IT.md) gegen einen veröffentlichten
Testserver, gesteuert durch Ihren eigenen Client. Um eine Sitzung im Nachhinein zu prüfen,
siehe [vergangene Sitzungen aus Logs überprüfen](https://github.com/kerlenton/mcpsnoop/blob/HEAD/docs/POST_MORTEM.md).

### Konfigurationsdatei

Wenn Sie dieselben Shim-Flags in einem Projekt wiederverwenden, legen Sie sie in einer
`.mcpsnoop.toml`-Datei im aktuellen Arbeitsverzeichnis ab.```toml
label = "filesystem"
trace-file = "trace.jsonl"
redact-secrets = true
redact-key = "token,authorization"
redact-value = "sk-[A-Za-z0-9]+"
redact-path = "$.params.arguments.password"
no-trace = false

### Homebrew```bash
brew install mcpsnoop

`--older-than` ist erforderlich (es gibt keinen Standardwert, der etwas löschen würde) und
akzeptiert eine Tagesanzahl wie `30d` oder eine Go-Dauer wie `72h`. Tool-Baselines werden
nicht angefasst, da eine Baseline über das Server-Label und nicht über die Sitzung identifiziert wird.

Da es direkt in der eigentlichen Pipe sitzt und nicht abseits wie der Inspector, sieht es
genau das, was dein realer Client und Server einander sagen, egal in welcher Sprache der
Server geschrieben ist.

## Tastenkürzel

| Taste | Aktion | | Taste | Aktion |
|---|---|---|---|---|
| `enter` | inspizieren / aufklappen | | `/` | filtern |
| `esc` | zurück | | `:` | Befehl |
| `j` / `k` | bewegen | | `r` | Aufruf erneut abspielen |
| `g` / `G` | Anfang / Ende | | `c` | Fähigkeiten |
| `ctrl-f` / `ctrl-b` | blättern | | `s` | Tool-Zusammenfassung |
| `p` | Pause | | `y` | kopieren |
| `shift`+`<key>` | nach Spalte sortieren | | `e` | exportieren |
| `ctrl-d` | Sitzung löschen | | `f` | folgen |
| `?` | Hilfe | | | |

Drücke `?` in der App für die vollständige Liste.

## Den Datenstrom filtern

Drücke `/` in einer Sitzung und kombiniere durch Leerzeichen getrennte, UND-verknüpfte Tokens. Klartext
wird gegen Methode, Tool, ID und Payload abgeglichen.

| Token | Filtert nach | Beispiel |
|---|---|---|
| `tool:` | Tool-Name | `tool:search` |
| `method:` | JSON-RPC-Methode | `method:tools/call` |
| `id:` | Anfrage-ID und alle Wiederholungen, die sie fortsetzen | `id:7` |
| `task:` | Task-ID | `task:01J...` |
| `dir:` | Richtung (`c2s`, `s2c`) | `dir:s2c` |
| `kind:` | Frame-Typ (`req`, `resp`, `notify`, `stderr`, `invalid`) | `kind:invalid` |
| `status:` | Aufrufergebnis (`ok`, `error`, `cancel`, `late`, `cancelled`, `pending`, `bad`, `warn`, `mismatch` oder ein HTTP-Status wie `401`) | `status:error` |

Kombiniere Tokens, um gezielter zu filtern.```text
tool:search status:pending        # in-flight calls to one search tool
status:cancel                     # calls the client gave up on (status:cancelled is a cancelled task)
status:late                       # results that arrived after the cancellation
method:tools/call status:error    # tool calls that failed
dir:s2c kind:req                  # server-initiated requests (servers before 2026-07-28)

| Format | Was du bekommst |
|---|---|
| `json` | korrelierte Aufrufe, Zählungen pro Tool sowie p50/p95/p99-Latenz, langsamste Aufrufe, Fähigkeiten und Roh-Frames |
| `html` | eine eigenständige Browserdatei mit Suche und aufklappbarem JSON |
| `text` | eine übersichtliche Klartext-Ausgabe |
| `har` | ein Eintrag pro korreliertem Aufruf, in den Browser-Devtools und allem anderen, das HAR lesen kann, geöffnet werden kann |
| `otlp` | OTLP-JSON mit einem Span pro korreliertem Aufruf; W3C-Trace-Kontext verbindet Aufrufer-Traces, andernfalls wird pro Sitzung ein Trace verwendet |

MCP ist nicht HTTP, daher sind die URL, der Statuscode und die Zeitangaben eines HAR-Eintrags eine bewusste Zuordnung jedes Aufrufs und kein Transkript der tatsächlichen Übertragung.

Für OTLP liefert der `_meta.traceparent` einer Anfrage die Trace- und Parent-Span-IDs dieses Aufrufs, und `_meta.tracestate` reist auf dem Span mit. Wenn der Traceparent fehlt oder ungültig ist, behält mcpsnoop den aus der Sitzung abgeleiteten Trace bei und führt keinen State mit. mcpsnoop beobachtet, nimmt aber nicht teil, daher fügt es keinen eigenen Vendor-Eintrag hinzu und gibt den State des Aufrufers unverändert weiter.```bash
mcpsnoop export -T html -o out.html                    # an HTML file to open in a browser
mcpsnoop export -T text server.py-48213-7f3a1c9e2b04   # a specific session, as text
mcpsnoop export -T json | jq                           # the newest session, piped to jq
mcpsnoop export -T har -o session.har                  # a HAR file to open in browser devtools
mcpsnoop export -T otlp -o trace.json                  # import into an OTLP-compatible tracing backend

These Flags schreiben die exportierte Datei oder die In-Memory-TUI-Ansicht um, niemals das Quell-JSONL. `export` verweigert eine Ausgabe, die denselben Dateinamen wie die Eingabe trägt, und schreibt über eine temporäre Datei, die anschließend an Ort und Stelle umbenannt wird, sodass ein fehlgeschlagener Lauf die vorherige Datei unversehrt lässt.

Die `inputSchema` und `outputSchema` eines Tools, wie sie in einem `tools/list`-Ergebnis angekündigt werden, werden von `--redact-key` und `--redact-secrets` unangetastet gelassen. Ein Name in einem Schema ist eine Typdeklaration und kein Wert – der Name selbst bleibt in jedem Fall im Protokoll, und das Bereinigen des Unterschemas unter einer Eigenschaft namens `token` würde die eigenen Prüfungen des Tools mit entfernen. Die Ausnahme gilt nur für diese Position, sodass ein Argument, das zufällig `inputSchema` heißt, wie jedes andere bereinigt wird, und sie stoppt bei `default`, `const`, `examples` und `enum`, die Daten statt Struktur enthalten. Verwende `--redact-path`, um etwas innerhalb eines Schemas zu benennen, oder `--redact-value`, das Text überall dort abgleicht, wo er steht, außer in den beiden Schlüsselwörtern, die mcpsnoop parst, `type` und `x-mcp-header`.

Was jedes Flag erreicht, unterscheidet sich, also prüfe das Ergebnis, statt Annahmen zu treffen. Alle vier bereinigen JSON-RPC-Nutzdaten, und `--redact-key`, `--redact-path` und `--redact-secrets` erreichen nur diese. Nur `--redact-value` bereinigt zusätzlich stderr, anderen Nicht-JSON-Text und das Innere eines Strings. Ein `Mcp-Param-*`-Header wird zusammen mit dem korrespondierenden Body-Wert bereinigt; die übrigen Envelope-Metadaten, Server-Labels, `Mcp-Name`, `Mcp-Method` und der HTTP-Status bleiben unverändert wie erfasst. Die Schwärzung erfolgt nach bestem Bemühen; verwende daher einen separaten Ausgabepfad und lies das Ergebnis, bevor du es teilst.

### Abgeschlossene Aufrufe an einen OTLP-Collector streamen

Sende Spans, während der Proxy läuft, indem du ihn auf einen OTLP/HTTP-JSON-Traces-Endpunkt ausrichtest. Wiederhole `--otlp-header` für Collector-Authentifizierung oder Tenant-Header.```bash
mcpsnoop \
  --otlp-endpoint http://localhost:4318/v1/traces \
  --otlp-header "Authorization=Bearer $OTLP_TOKEN" \
  -- node build/index.js

mcpsnoop http \
  --target http://localhost:3000/mcp \
  --otlp-endpoint http://localhost:4318/v1/traces

Der Bericht zeigt Werkzeuge, die hinzugefügt oder entfernt wurden, Änderungen an Beschreibung und `inputSchema`, passende Tool-Aufrufe, deren Status sich geändert hat, sowie bemerkenswerte Verschiebungen der Dauer. Aufrufe werden nach Tool-Name und Argumenten abgeglichen, sodass neu angeordnete Aufrufe weiterhin korrekt verglichen werden. Standardmäßig müssen sich Daueränderungen um mindestens 100 ms und den Faktor 2 unterscheiden; verwenden Sie `--duration-threshold` und `--duration-ratio`, um diese Grenzwerte anzupassen.

Übergeben Sie `--exit-code`, um CI anhand von Regressionen zu bewerten: Es wird mit einem Nicht-Null-Status beendet, wenn die Nachher-Sitzung ein Tool entfernt, eine Tool-Beschreibung, einen Titel, ein Eingabeschema, ein Ausgabeschema oder Annotationen ändert, einen Aufruf enthält, dessen Status sich verschlechtert hat, oder langsamer wird. Verbesserungen (hinzugefügte Tools, behobene Aufrufe, Beschleunigungen) enden weiterhin mit Exit-Code 0, ebenso wie eine Symboländerung, die das Aussehen eines Tools verändert, ohne seine Funktionsweise zu ändern.

## Sitzungen in CI prüfen

Bewerten Sie einen aufgezeichneten Agentenlauf anhand von Fehlern, Stream-Beschädigung, Protokollwarnungen, Routing-Header-Konflikten, Aufrufen, die nie eine Antwort erhalten haben, verworfenen Frames, die die Aufzeichnung unvollständig machen, Tool-Definitions-Abweichungen oder der Verwendung veralteter Protokollfunktionen.```bash
mcpsnoop check [--format text|junit|sarif] [--fail-on error,invalid,warn,mismatch,pending,late-result,drift,deprecated,incomplete,schema] [session-id|log.jsonl|-]

Die Anzahl der verworfenen Frames wandert ebenfalls mit den Artefakten, sodass ein Capture, das sich selbst untertreibt, dies überall dort anzeigt, wo es geöffnet wird: `missing_frames` im JSON-Export, `log.comment` in HAR und das Ressourcenattribut `mcpsnoop.session.missing_frames` in OTLP.```bash
mcpsnoop check build-agent
mcpsnoop check --fail-on error,invalid artifacts/session.jsonl
mcpsnoop check --fail-on mismatch gateway-run.jsonl

### Melde es dort, wo die CI bereits sucht

`--format junit` schreibt ein `<testcase>` pro Signal und Sitzung, und seine Fehlschläge
folgen derselben `--fail-on`-Auswahl wie die Textausgabe.```yaml
- name: Check captured MCP session
  run: |
    mkdir -p test-results
    mcpsnoop check --format junit artifacts/session.jsonl > test-results/mcpsnoop.xml
- name: Upload mcpsnoop JUnit report
  if: always()
  uses: actions/upload-artifact@v4
  with:
    name: mcpsnoop-junit
    path: test-results/mcpsnoop.xml

### Einen Routing-Header erkennen, der nicht zum Body passt

Beim Streamable-HTTP-Transport leitet ein Gateway anhand von `Mcp-Method` und `Mcp-Name` weiter, während der Server den Body liest. Ein Header, der nicht zum Body passt, bedeutet also, dass beide zwei unterschiedliche Requests betrachten. Das `mismatch`-Signal deckt das ab, ebenso einen Header, der auf einem Batch reitet, den er nicht adressieren kann, sowie einen vollständig fehlenden erforderlichen Header.

Seit 2026-07-28 ist ein fehlender Routing-Header ein Validierungsfehler, und ein konformer Server lehnt den Request mit `400` und `-32020` ab. mcpsnoop meldet dies erst, wenn bekannt ist, dass die Session diese Revision oder neuer spricht, da frühere Revisionen diese Header überhaupt nicht definieren und das Weglassen dort korrekt ist. Eine eigene `-32020`-Ablehnung eines Servers zählt als dasselbe Signal.

Ein Name oder eine Resource-URI, der beziehungsweise die nicht in einen HTTP-Feldwert passt, wird als Base64 in einem `=?base64?…?=`-Sentinel übertragen, der vor dem Vergleich dekodiert wird. Ein Client, der korrekt kodiert, wird daher nie markiert.

Bei HTTP-`tools/call`-Requests zeigt mcpsnoop außerdem jeden `Mcp-Param-{Name}`-Header an und vergleicht ihn, sobald die passende beworbene Tool-Definition bekannt ist, mit dem annotierten Argumentpfad. Verschachtelte Eigenschaften, der Base64-Sentinel, boolesche Werte und numerisch äquivalente sichere Ganzzahlen werden ohne False Positives durch String-Vergleich behandelt. Unbekannte Parameter-Header und Sessions ohne passende Tool-Definition bleiben rein beobachtend. Schlüssel- und wertbasierte Redaktion wird auf erfasste Parameter-Header-Werte angewendet, bevor sie eine Senke erreichen; ein Wert, den mcpsnoop selbst geschwärzt hat, wird niemals als Abweichung gemeldet.

### Abweichungen bei Tool-Definitionen erkennen

Die erste vollständige `tools/list`-Antwort, die für ein Server-Label beobachtet wird, wird zur vertrauenswürdigen Baseline. Spätere Sessions vergleichen diese Baseline Feld für Feld: die Beschreibung, den Titel, die Eingabe- und Ausgabe-Schemas, die Annotationen und die Icons sowie hinzugefügte oder entfernte Tools. Annotationen sind am wichtigsten, denn ein Tool, das mit `readOnlyHint` genehmigt wurde und sich später als destruktiv deklariert, ist genau der Rug-Pull, für den dieser Check existiert, und die Spezifikation weist Clients an, Annotationen als nicht vertrauenswürdig zu behandeln. Titel und Icons werden nachverfolgt, weil sie das sind, was der Benutzer sieht, und die Spezifikation stuft den `title` eines Tools höher ein als `annotations.title` und seinen Namen. Die Sessions-Tabelle und die Tool-Übersicht kennzeichnen Drift, ohne den MCP-Datenverkehr zu blockieren oder zu verändern.

Annotationen werden über ihre Spezifikations-Standardwerte verglichen, sodass ein Server, der einen Hinweis, auf den er sich ohnehin schon verlassen hat, nun explizit angibt, nicht gemeldet wird. Eine Baseline, die aufgezeichnet wurde, bevor mcpsnoop ein Feld nachverfolgt hat, funktioniert weiterhin für die Felder, die sie erfasst, und gibt an, für welche sie keine Antwort geben kann. Nehmen Sie die Aufzeichnung mit `mcpsnoop baseline --accept` erneut vor, sobald Sie den aktuellen Definitionen vertrauen.

Wenn sich ändert, was die Redaktion aufzeichnet, ändert sich auch, was die Drift-Erkennung vergleicht. Eine Baseline, die ohne `--redact-value` erstellt und dann gegen einen mit `--redact-value` erstellten Capture geprüft wird, meldet die geschwärzten Felder als geändert – das ist korrekt, da sich die aufgezeichnete Definition tatsächlich geändert hat. Nehmen Sie nach einer Änderung der Redaktionseinstellungen die Aufzeichnung mit `--accept` erneut vor.

Verwenden Sie für jeden Server, dessen Befehlsname oder Zielhost andernfalls kollidieren würde, ein stabiles, eindeutiges `--label`. Baselines werden im normalen mcpsnoop-State-Verzeichnis gespeichert, daher gelten `MCPSNOOP_HOME` und `XDG_STATE_HOME`.```bash
mcpsnoop check --fail-on drift session.jsonl
mcpsnoop baseline session.jsonl
mcpsnoop baseline --accept session.jsonl  # trust a legitimate definition change
mcpsnoop baseline --reset session.jsonl   # trust the next complete tools/list

`drift` ist für `check` opt-in; das Standard-Gate `error,invalid,warn` bleibt unverändert.

### Veraltete Protokollfunktionen markieren

Die Revision vom 2026-07-28 erklärt Roots, Sampling und Logging für veraltet. Sie bleiben mindestens ein Jahr lang funktionsfähig, also kennzeichnet mcpsnoop sie, anstatt sie als Fehler zu behandeln. Der Stream, der Capability-Inspektor und der Export kennzeichnen sie alle, und jede Markierung benennt den Ersatz.

Zwei der drei sind nun nur noch über eine Multi-Round-Trip-Anfrage erreichbar, bei der sich der Methodenname in der `inputRequests`-Map des Servers befindet und nicht im Frame selbst. Auch diese werden gekennzeichnet, damit ein Server, der auf das neue Muster umgestellt wurde, nicht stillschweigend die Meldung einstellt.```bash
mcpsnoop check --fail-on deprecated session.jsonl

Die Spalte trägt die Warnfarbe und niemals das Rot der ERR-Spalte, und
mcpsnoop ändert weiterhin nichts an dem Datenverkehr, den es weiterleitet.

Es wird nichts aufgelöst oder abgerufen. Ein externer `$ref` wird allein an
seiner Form erkannt, und das Schema, auf das er verweist, wird nie gelesen.

### Sieh dir an, was dich der Server im Kontext kostet

Tool-Definitionen gelangen bei jeder Konversation in den Kontext des Modells
und Tool-Ergebnisse bei jedem Aufruf. Die Tool-Zusammenfassung (`s`) misst
beides anhand der Sitzung, die du tatsächlich erfasst hast.

Die Zeile `definitions` stellt die Fixkosten dar: wie viel die `tools/list`
dieses Servers wiegt, bevor ein einziger Aufruf getätigt wird. Die Spalte
`DEF` schlüsselt das pro Tool auf und `RESULT` ist, was die Antworten jedes
Tools bisher gekostet haben. Die Tabelle bleibt nach Fehlern und Latenz
sortiert; überfliege also `DEF`, um die teuren Definitionen zu finden; der
Export listet sie, die schwersten zuerst. Eine Zeile unter der Tabelle nennt
das einzelne schwerste Ergebnis, das eine Gesamtsumme verdeckt.

Bei den Kennzahlen der Definitionen handelt es sich um das JSON ohne
unbedeutende Leerzeichen, sodass ein Server, der seine `tools/list`
übersichtlich formatiert ausgibt, nicht als teurer gezählt wird als einer, der
das nicht tut, und derselbe Server über Aufzeichnungen hinweg dasselbe misst.
`RESULT` sind die Bytes, so wie sie angekommen sind: Ein Ergebnis ist eine
einmalige Nutzlast und kein Vertrag, den zu normalisieren sich lohnt.```bash
mcpsnoop export -T json | jq '.summary.definitions'

Der Socket befindet sich im State-Verzeichnis des entfernten Systems, aufgelöst als `MCPSNOOP_HOME`, andernfalls als `XDG_STATE_HOME/mcpsnoop`, andernfalls als `~/.local/state/mcpsnoop`. Standardmäßig nimmt mcpsnoop das Linux-Homeverzeichnis `/home/<user>` aus deinem `user@host` an und gibt eine Erinnerung an stderr aus, wann immer es auf diese Vermutung zurückfällt. Falls das entfernte System woanders auflöst, benenne das eine nicht standardmäßige Element.```bash
# a non-Linux or custom home, macOS is /Users/<user> and root is /root
mcpsnoop remote --remote-home /Users/remote-user remote-user@remote-host

# an explicit MCPSNOOP_HOME on the remote
mcpsnoop remote --remote-mcpsnoop-home /srv/mcpsnoop remote-user@remote-host

# an explicit XDG_STATE_HOME on the remote
mcpsnoop remote --remote-xdg-state-home /var/lib/state remote-user@remote-host

Um stattdessen eine lokale Kopie zu behalten, kopiere die Logs per scp in dein
Sessions-Verzeichnis und führe die TUI wie gewohnt aus.```bash
# copy the remote logs into your local sessions directory
mkdir -p ~/.local/state/mcpsnoop/sessions
scp remote-user@remote-host:'~/.local/state/mcpsnoop/sessions/*.jsonl' \
  ~/.local/state/mcpsnoop/sessions/

# open the TUI, it backfills the copied sessions
mcpsnoop

Für Remote-Workflows verwenden Sie SSH-Tunneling oder SSH-Dateiübertragung, sodass Transport-Authentifizierung,
Verschlüsselung, Host-Überprüfung, Schlüsselrotation und Audit-Richtlinie in Ihrer
vorhandenen SSH-Umgebung bleiben.

## Mitwirken

Issues und Pull-Requests sind willkommen. Einzelheiten finden Sie in [CONTRIBUTING.md](https://github.com/kerlenton/mcpsnoop/blob/HEAD/CONTRIBUTING.md).

## Lizenz

[MIT](https://github.com/kerlenton/mcpsnoop/blob/HEAD/LICENSE)