Per usarlo davvero, avvolgi il tuo server nella configurazione MCP del tuo client.```json
{
  "mcpServers": {
    "my-server": {
      "command": "mcpsnoop",
      "args": ["--", "node", "build/index.js"]
    }
  }
}

`wrap` trova `claude_desktop_config.json`, lo copia in
`claude_desktop_config.json.mcpsnoop.bak` la prima volta e riscrive solo
la voce di quel singolo server, così la tua formattazione e tutti gli altri
server restano intatti. All'interno della voce riscritta le chiavi tornano
in ordine alfabetico. `unwrap` ripristina il file e rimuove il backup quando
nessun server è più avvolto. Riavvia Claude Desktop dopo l'una o l'altra
operazione, poiché i server MCP vengono avviati una sola volta all'avvio.

Quindi usa il tuo client come al solito e apri la UI.```bash
mcpsnoop

Lo stato HTTP di ogni risposta appare nello stream, quindi una risposta che non trasporta alcun messaggio JSON-RPC proprio è comunque un frame visibile, non un nulla: la sfida 401, il 403 su un Origin rifiutato, il 202 che riconosce una notifica e il 502 quando il target non può essere raggiunto affatto. L'header `WWW-Authenticate` di un 401 viene conservato verbatim e mostrato nell'ispettore, poiché indica lo schema di autenticazione e i metadati della risorsa a cui andare successivamente. Filtra per stato con `status:401` nella TUI, oppure per qualsiasi errore con `status:err`. Un 4xx o 5xx conta come errore, quindi un'esecuzione predefinita di `mcpsnoop check` fallisce su di esso.

Non hai un server tuo? [Provalo sul serio](https://github.com/kerlenton/mcpsnoop/blob/HEAD/docs/TRY_IT.md) contro un server di test pubblicato, guidato dal tuo client. Per ispezionare una sessione dopo che è avvenuta, vedi [rivedere sessioni passate dai log](https://github.com/kerlenton/mcpsnoop/blob/HEAD/docs/POST_MORTEM.md).

### File di configurazione

Se riutilizzi gli stessi flag shim in un progetto, inseriscili in un file `.mcpsnoop.toml` nella directory di lavoro corrente.```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` è obbligatorio (non esiste un default che cancellerebbe qualcosa) e accetta un conteggio in giorni come `30d` o una durata Go come `72h`. Le baseline degli strumenti vengono lasciate intatte, poiché una baseline è associata all'etichetta del server piuttosto che alla sessione.

Poiché si trova nel pipe effettivo, non in disparte come l'Inspector, vede esattamente ciò che il tuo client e server reali si dicono a vicenda, qualunque sia il linguaggio in cui è scritto il server.

## Tasti di scelta rapida

| Tasto | Azione | | Tasto | Azione |
|---|---|---|---|---|
| `enter` | ispeziona / approfondisci | | `/` | filtra |
| `esc` | indietro | | `:` | comando |
| `j` / `k` | sposta | | `r` | riproduci una chiamata |
| `g` / `G` | in alto / in basso | | `c` | capacità |
| `ctrl-f` / `ctrl-b` | pagina | | `s` | riepilogo strumento |
| `p` | pausa | | `y` | copia |
| `shift`+`<key>` | ordina per colonna | | `e` | esporta |
| `ctrl-d` | elimina sessione | | `f` | segui |
| `?` | aiuto | | | |

Premi `?` nell'app per l'elenco completo.

## Filtrare il flusso

Premi `/` in una sessione e combina token separati da spazi, con AND logico. Il testo semplice corrisponde a metodo, strumento, id e payload.

| Token | Filtra per | Esempio |
|---|---|---|
| `tool:` | nome dello strumento | `tool:search` |
| `method:` | metodo JSON-RPC | `method:tools/call` |
| `id:` | id della richiesta e qualsiasi nuovo tentativo che la prosegue | `id:7` |
| `task:` | id dell'attività | `task:01J...` |
| `dir:` | direzione (`c2s`, `s2c`) | `dir:s2c` |
| `kind:` | tipo di frame (`req`, `resp`, `notify`, `stderr`, `invalid`) | `kind:invalid` |
| `status:` | esito della chiamata (`ok`, `error`, `cancel`, `late`, `cancelled`, `pending`, `bad`, `warn`, `mismatch`, o uno stato HTTP come `401`) | `status:error` |

Combina i token per essere più specifico.```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)

| Formato | Cosa ottieni |
|---|---|
| `json` | chiamate correlate, conteggi per strumento e latenza p50/p95/p99, chiamate più lente, capacità e frame grezzi |
| `html` | un file browser autonomo con ricerca e JSON richiudibile |
| `text` | un dump di testo semplice e leggibile |
| `har` | una voce per chiamata correlata, apribile negli strumenti di sviluppo del browser e in qualsiasi altro programma che legga HAR |
| `otlp` | JSON OTLP con uno span per chiamata correlata; il contesto di traccia W3C unisce le tracce del chiamante, altrimenti viene usata una traccia per sessione |

MCP non è HTTP, quindi l'URL, il codice di stato e i tempi di una voce HAR sono una
mappatura deliberata di ogni chiamata piuttosto che una trascrizione di rete.

Per OTLP, il `_meta.traceparent` di una richiesta fornisce l'ID di traccia e di span
genitore di quella chiamata, e `_meta.tracestate` viaggia insieme allo span. Quando il
traceparent è assente o non valido, mcpsnoop mantiene la traccia derivata dalla sessione
e non trasporta alcuno stato. mcpsnoop osserva piuttosto che partecipare, quindi non
aggiunge una propria voce di vendor e passa lo stato del chiamante inalterato.```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 rewrite the exported file or the in-memory TUI view, never the
source JSONL. `export` refuses an output that names the same file as its input,
and writes through a temporary file that is renamed into place, so a run that
fails leaves the previous file whole.

L'`inputSchema` e l'`outputSchema` di uno strumento, come pubblicizzati in un risultato di `tools/list`, non vengono modificati da `--redact-key` e `--redact-secrets`. Un nome all'interno di uno schema è una dichiarazione di tipo piuttosto che un valore; il nome stesso rimane comunque nel log, e ripulire il sottoschema sotto una proprietà chiamata `token` si porterebbe dietro anche i controlli dello strumento. L'esenzione vale solo per quella posizione; quindi un argomento che capita di chiamarsi `inputSchema` viene ripulito come qualsiasi altro, e la pulizia si ferma a `default`, `const`, `examples` e `enum`, che contengono dati piuttosto che struttura. Usa `--redact-path` per indicare qualcosa all'interno di uno schema, oppure `--redact-value`, che trova corrispondenze di testo ovunque si trovi, tranne nelle due parole chiave che mcpsnoop analizza, `type` e `x-mcp-header`.

Ciò che ogni flag raggiunge è diverso, quindi controlla il risultato piuttosto che dare per scontato. Tutti e quattro ripuliscono i payload JSON-RPC, e `--redact-key`, `--redact-path` e `--redact-secrets` raggiungono solo quelli. Solo `--redact-value` ripulisce anche stderr, altro testo non JSON e l'interno di una stringa. Un header `Mcp-Param-*` viene ripulito insieme al valore del corpo che rispecchia; gli altri metadati dell'involucro, le etichette dei server, `Mcp-Name`, `Mcp-Method` e lo stato HTTP, vengono lasciati così come catturati. La redazione è best effort, quindi usa un percorso di output separato e leggi il risultato prima di condividerlo.

### Trasmettere in streaming le chiamate completate a un collector OTLP

Invia span mentre il proxy è in esecuzione puntandolo verso un endpoint di trace JSON OTLP/HTTP. Ripeti `--otlp-header` per l'autenticazione del collector o per gli header tenant.```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

Il report mostra gli strumenti aggiunti o rimossi, le modifiche alla descrizione e allo `inputSchema`, le chiamate di strumenti corrispondenti il cui stato è cambiato e i notevoli cambiamenti di durata. Le chiamate vengono abbinate per nome dello strumento e argomenti, quindi le chiamate riordinate vengono comunque confrontate correttamente. Per impostazione predefinita, le variazioni di durata devono differire di almeno 100 ms e 2x; usa `--duration-threshold` e `--duration-ratio` per regolare queste soglie.

Passa `--exit-code` per controllare la CI sulle regressioni: esce con codice non zero quando la sessione successiva rimuove uno strumento, modifica una descrizione, un titolo, uno schema di input, uno schema di output o delle annotazioni, ha una chiamata il cui stato è peggiorato o rallenta. I miglioramenti (strumenti aggiunti, chiamate corrette, accelerazioni) escono comunque con zero, e così anche un cambio di icona, che altera l'aspetto di uno strumento senza cambiarne il funzionamento.

## Verifica delle sessioni in CI

Applica un controllo a una sessione registrata dell'agente in base a errori, corruzione dello stream, avvisi di protocollo, mancate corrispondenze dell'intestazione di routing, chiamate che non hanno mai ricevuto risposta, frame scartati che lasciano la cattura incompleta, deriva delle definizioni degli strumenti o uso di funzionalità di protocollo deprecate.```bash
mcpsnoop check [--format text|junit|sarif] [--fail-on error,invalid,warn,mismatch,pending,late-result,drift,deprecated,incomplete,schema] [session-id|log.jsonl|-]

Il conteggio dei frame persi viaggia anche con gli artefatti, quindi una cattura che si sottostima lo dichiara ovunque venga aperta: `missing_frames` nell'export JSON, `log.comment` in HAR e l'attributo di risorsa `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

### Segnalalo dove la CI guarda già

`--format junit` scrive un `<testcase>` per segnale e sessione, e i suoi fallimenti
seguono la stessa selezione `--fail-on` dell'output testuale.```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

### Rileva un header di routing in disaccordo con il body

Sul trasporto streamable-HTTP un gateway instrada in base a `Mcp-Method` e `Mcp-Name`
mentre il server legge il body, quindi un header in disaccordo con il body significa
che i due stanno osservando due richieste diverse. Il segnale `mismatch` copre questo caso,
un header che viaggia su un batch che non può indirizzare e un header obbligatorio mancante
del tutto.

In 2026-07-28 un header di routing mancante è un errore di validazione e un server
conforme rifiuta la richiesta con `400` e `-32020`. mcpsnoop lo segnala solo dopo
che la sessione è nota per supportare quella revisione o successiva, poiché le revisioni
precedenti non definiscono affatto questi header e ometterli lì è corretto. Il rifiuto
`-32020` del server stesso conta come lo stesso segnale.

Un nome o un URI di risorsa che non rientra in un valore di campo HTTP viaggia in Base64 in
un sentinel `=?base64?…?=`, che viene decodificato prima del confronto, quindi un client
che codifica correttamente non viene mai segnalato.

Nelle richieste HTTP `tools/call` mcpsnoop mostra anche ogni header `Mcp-Param-{Name}`
e, quando è nota la definizione dello strumento pubblicizzato corrispondente, la confronta
con il percorso annotato dell'argomento. Proprietà annidate, sentinel Base64, booleani e
interi sicuri numericamente equivalenti vengono gestiti senza falsi positivi da confronto
di stringhe. Gli header di parametri sconosciuti e le sessioni senza una definizione dello
strumento corrispondente restano a livello osservativo. La redazione basata su chiave e
valore si applica ai valori degli header dei parametri catturati prima che raggiungano un
sink, e un valore ripulito dallo stesso mcpsnoop non viene mai segnalato come disaccordo.

### Rileva la deriva delle definizioni degli strumenti

La prima `tools/list` completa osservata per un'etichetta di server diventa la sua baseline
attendibile. Le sessioni successive confrontano quella baseline campo per campo: la
descrizione, il titolo, gli schemi di input e output, le annotazioni e le icone, oltre
agli strumenti aggiunti o rimossi. Le annotazioni sono ciò che conta di più, poiché uno
strumento approvato con `readOnlyHint` che in seguito si dichiara distruttivo è il tiro
del tappeto per cui questo controllo esiste, e la specifica dice ai client di trattare le
annotazioni come non attendibili. Il titolo e le icone vengono tracciati perché sono ciò
che l'utente vede, e la specifica colloca il `title` di uno strumento al di sopra di
`annotations.title` e del suo nome. La tabella delle sessioni e il riepilogo degli
strumenti segnalano la deriva senza bloccare o modificare il traffico MCP.

Le annotazioni vengono confrontate tramite i loro valori predefiniti di specifica, quindi
un server che inizia a esplicitare un suggerimento su cui faceva già affidamento non viene
segnalato. Una baseline registrata prima che mcpsnoop tracciasse un campo continua a
funzionare per i campi che registra e indica quali non può verificare; registra di nuovo
con `mcpsnoop baseline --accept` una volta che ti fidi delle definizioni correnti.

Modificare ciò che la redazione registra modifica ciò che la deriva confronta. Una baseline
acquisita senza `--redact-value` e poi verificata con una cattura effettuata con
quell'opzione segnala i campi ripuliti come modificati, il che è corretto, poiché la
definizione registrata è davvero cambiata. Registra di nuovo con `--accept` dopo aver
modificato le impostazioni di redazione.

Usa un `--label` stabile e univoco per ogni server il cui nome di comando o host di
destinazione entrerebbe altrimenti in collisione. Le baseline sono archiviate nella
normale directory di stato di mcpsnoop, quindi si applicano `MCPSNOOP_HOME` e
`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` è opt-in per `check`; il gate predefinito `error,invalid,warn` rimane invariato.

### Contrassegna le funzionalità del protocollo deprecate

La revisione del 2026-07-28 depreca Roots, Sampling e Logging. Continuano a funzionare per almeno un anno, quindi mcpsnoop li contrassegna invece di trattarli come errori. Il flusso, l'ispettore delle capacità e l'esportazione li contrassegnano tutti, e ogni marcatore indica il sostituto.

Due dei tre sono ora raggiungibili solo tramite una richiesta multi round-trip, in cui il nome del metodo si trova all'interno della mappa `inputRequests` del server anziché sul frame stesso. Anche questi vengono contrassegnati, così un server che è passato al nuovo pattern non smette silenziosamente di segnalare.```bash
mcpsnoop check --fail-on deprecated session.jsonl

La colonna porta il colore di avviso e mai il rosso della colonna ERR, e mcpsnoop continua a non cambiare nulla nel traffico che inoltra.

Niente viene risolto o recuperato. Un `$ref` esterno viene riconosciuto solo dalla sua forma, e lo schema a cui punta non viene mai letto.

### Scopri quanto ti costa il server nel contesto

Le definizioni degli strumenti entrano nel contesto del modello a ogni conversazione, e i risultati degli strumenti a ogni chiamata. Il riepilogo degli strumenti (`s`) misura entrambi a partire dalla sessione che hai effettivamente catturato.

La riga `definitions` è il costo fisso: quanto pesa `tools/list` di questo server prima che venga effettuata una singola chiamata. La colonna `DEF` lo suddivide per strumento e `RESULT` è ciò che le risposte di ciascuno strumento sono costate finora. La tabella rimane ordinata per errori e latenza, quindi scorri `DEF` per trovare le definizioni costose; l'export le elenca prima quelle più pesanti. Una riga sotto la tabella indica il singolo risultato più pesante, che un totale nasconde.

Le cifre relative alle definizioni sono il JSON con rimossi gli spazi bianchi insignificanti, quindi un server che stampa in modo pretty il proprio `tools/list` non viene conteggiato come più costoso di uno che non lo fa, e lo stesso server misura uguale tra diverse catture. `RESULT` è il numero di byte così come sono arrivati: un risultato è un payload una tantum, non un contratto che vale la pena normalizzare.```bash
mcpsnoop export -T json | jq '.summary.definitions'

Il socket risiede nella directory di stato del remoto, risolta come `MCPSNOOP_HOME`,
altrimenti `XDG_STATE_HOME/mcpsnoop`, altrimenti `~/.local/state/mcpsnoop`. Di default mcpsnoop
assume la home Linux `/home/<user>` dal tuo `user@host` e stampa un promemoria
su stderr ogni volta che ripiega su quella ipotesi. Se il remoto risolve altrove,
indica l'unico componente non predefinito.```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

Per conservare invece una copia locale, scp i log nella tua directory delle sessioni ed esegui
la TUI come al solito.```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

Per i flussi di lavoro remoti, usa il tunnelling SSH o il trasferimento file via SSH, così autenticazione del trasporto, cifratura, verifica dell'host, rotazione delle chiavi e policy di audit restano nella tua configurazione SSH esistente.

## Contributing

Issue e pull request sono benvenuti. Vedi [CONTRIBUTING.md](https://github.com/kerlenton/mcpsnoop/blob/HEAD/CONTRIBUTING.md) per i dettagli.

## License

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