mcpsnoop

Wireshark per MCP. Un proxy trasparente che mostra ogni chiamata reale agli strumenti tra il tuo client AI e i tuoi server MCP, in tempo reale nel tuo terminale.

Il problema

L'MCP Inspector ufficiale si connette come client a sé stante, quindi non vede mai cosa il tuo client (Cursor, Claude Code, Codex) invia effettivamente al tuo server. E qualsiasi cosa che attenda l'arrivo di una richiesta non può mostrare la chiamata che il modello non ha mai effettuato, o che ha effettuato con argomenti errati. Quando uno strumento non viene chiamato silenziosamente, le capacità non coincidono, o una chiamata semplicemente si blocca, ti ritrovi a scavare nei log e a fare supposizioni.

mcpsnoop si posiziona invece nel percorso dati reale. Avvolgi il comando del tuo server con esso e osserva ogni frame JSON-RPC in tempo reale, mentre il tuo client e server reali comunicano.

In CI

Questa pagina è anche la scheda per la mcpsnoop GitHub Action, quindi ecco tutto quanto. Verifica una sessione catturata, registra ogni riscontro come avviso di code scanning, e fa fallire il job su ciò su cui hai impostato i gate.```yaml permissions: security-events: write contents: read

steps:

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

Scegli la release che preferisci. La più recente è nella
[pagina delle release](https://github.com/kerlenton/mcpsnoop/releases). Ogni input,
il significato dei codici di uscita e come collegarlo senza l'action sono descritti
in [The GitHub Action](#the-github-action) più in basso.

## Avvio rapido

Provalo subito, senza alcuna configurazione.```bash
mcpsnoop demo

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

Tutto ciò che segue `--` è il comando che normalmente avvia il tuo server. Sostituiscilo
con quello che già usi, come `python server.py`, `npx -y @scope/server`, o un
binario compilato.

Su Claude Desktop non devi fare questa modifica a mano.```bash
mcpsnoop wrap my-server     # route my-server through mcpsnoop
mcpsnoop unwrap my-server   # put it back

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 vengono lasciati intatti. All'interno della voce riscritta le chiavi tornano in ordine alfabetico. unwrap ripristina il file e rimuove il backup una volta che nessun server è più avvolto. Riavvia Claude Desktop dopo entrambe le operazioni, poiché i server MCP vengono avviati una sola volta all'avvio.

Poi usa il tuo client come al solito e apri l'interfaccia utente.```bash mcpsnoop

Nessun flag, nessun percorso socket, nessun ordine di avvio da ricordare. Lo shim e l'interfaccia si trovano
da soli, e l'interfaccia recupera le sessioni passate dal disco.

Per un server HTTP streamable, esegui mcpsnoop come proxy inverso.```bash
mcpsnoop http --target http://localhost:3000/mcp --listen :7000

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

Nessun server tuo? Provalo davvero contro un server di test pubblicato, guidato dal tuo client. Per ispezionare una sessione dopo che è avvenuta, vedi rivedi sessioni passate dai log.

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

Ripeti `redact-key`, `redact-value` e `redact-path` su righe separate per aggiungerne più di uno per tipo.

Queste sono tutte le chiavi che supporta.

Il file viene cercato solo nella directory di lavoro corrente, non nelle directory
padri.

I flag espliciti da riga di comando sovrascrivono i valori del file di configurazione.

## Comandi

| Comando | Cosa fa |
|---|---|
| `mcpsnoop -- <server>` | avvolge un server stdio come shim trasparente |
| `mcpsnoop` | apre la TUI live |
| `mcpsnoop http --target <url>` | fa da proxy a un server HTTP streamable |
| `mcpsnoop export` | renderizza una sessione in json, html, text, har o otlp |
| `mcpsnoop check` | fa fallire la CI su errori, frame non validi, avvisi, disallineamenti di routing, chiamate bloccate, risultati tardivi o un budget di latenza |
| `mcpsnoop baseline` | ispeziona, accetta o reimposta le definizioni di tool fidate |
| `mcpsnoop diff` | confronta tool e chiamate tra due sessioni catturate |
| `mcpsnoop open` | apre una sessione salvata nella TUI |
| `mcpsnoop inventory` | elenca ogni server che è passato attraverso mcpsnoop su questa macchina |
| `mcpsnoop stats` | comprime ogni cattura salvata in una riga per server e tool |
| `mcpsnoop prune` | elimina i log di sessione salvati più vecchi di una soglia |
| `mcpsnoop wrap <server>` | instrada uno dei server di Claude Desktop attraverso mcpsnoop |
| `mcpsnoop unwrap <server>` | ripristina la voce di quel server come era prima |
| `mcpsnoop remote <user@host>` | stampa il comando del tunnel SSH |
| `mcpsnoop demo` | riproduce una sessione scriptata |

Esegui `mcpsnoop help` per l'elenco completo, oppure `mcpsnoop help <comando>` per i flag di uno specifico.

## Come si confronta

| | MCP Inspector | mcpsnoop |
|---|:---:|:---:|
| Vede il traffico reale del tuo client e server | no | sì |
| Segnala chiamate bloccate ed errori di stream | no | sì |
| Segnala output fuori posto che corrompe lo stream | no | sì |
| Segnala frame JSON-RPC malformati | no | sì |
| Rileva la deriva delle definizioni dei tool dopo l'approvazione | no | sì |
| Interfaccia terminale interattiva | no | sì |
| Zero configurazione, nessun flag o ordinamento | no | sì |
| Ispezionatore di capacità | parziale | sì |
| Riproduce una chiamata catturata | no | sì, su stdio e su HTTP |
| Esportazione sessione (json / html / text / otlp) | no | sì |
| Singolo binario, nessuna dipendenza runtime | no | sì |

## Installazione

### npm