mcpsnoop v0.22.0

Wireshark per MCP. mcpsnoop si colloca tra il tuo client AI e il tuo server MCP e registra ogni frame JSON-RPC che si scambiano, senza modificare nessuna delle due parti. Osservalo in tempo reale nel tuo terminale, fai fallire la CI in base a ciò che rileva, oppure invialo al tuo backend di tracing come span OpenTelemetry.

Il problema

L'MCP Inspector ufficiale si connette come client a sé stante, quindi non vede mai ciò che il tuo client (Cursor, Claude Code, Codex) invia effettivamente al tuo server. E qualsiasi strumento che attende 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 corrispondono, o una chiamata si blocca, ti ritrovi a scavare nei log e a tirare a indovinare.

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

In CI

Questa pagina è anche la scheda della GitHub Action mcpsnoop, quindi eccola per intero. Verifica una sessione catturata, registra ogni rilevamento come avviso di code scanning e fa fallire il job in base a ciò su cui hai impostato il controllo.

permissions:
  security-events: write
  contents: read

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

Non hai una cattura a portata di mano? Registra una sessione con il tuo client una volta, esegui il commit e lascia che l'action la riproduca su ogni build. Nessun modello e nessuna chiave API vengono eseguiti in CI. La riproduzione viene verificata come qualsiasi cattura, e il job fallisce anche quando il server peggiora rispetto alla registrazione. Un server raggiunto tramite Streamable HTTP riceve target con il suo endpoint, e una registrazione viene riprodotta su entrambi i trasporti.

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

Fissa la release che preferisci. La più recente è nella pagina delle release. Ogni input e output è in The GitHub Action più in basso, e ogni segnale sul quale il controllo può fallire è in docs/CI.md.

OpenTelemetry

La revisione MCP 2026-07-28 depreca il Logging a livello di protocollo e indica alle implementazioni di passare a stderr su stdio, oppure a OpenTelemetry per un'osservabilità strutturata. mcpsnoop copre entrambi senza toccare il client o il server. Le righe stderr di un server stdio compaiono nello stream accanto ai suoi frame, e ogni richiesta diventa uno span che segue le convenzioni semantiche OpenTelemetry per 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

Una chiamata a uno strumento arriva come span denominato tools/call search, che trasporta mcp.method.name, gen_ai.tool.name e error.type, così finisce in una dashboard costruita per MCP anziché per mcpsnoop. Le metriche live degli strumenti per Prometheus sono a un flag di distanza. Entrambe sono in docs/OPENTELEMETRY.md.

Avvio rapido

Provalo subito, senza alcuna configurazione.

mcpsnoop demo

Per un utilizzo reale, inserisci il tuo server nella configurazione MCP del tuo client.

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

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

Su Claude Desktop non devi effettuare questa modifica manualmente.

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 ogni altro server restano 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ù wrappato. Riavvia Claude Desktop dopo l'una o l'altra operazione, poiché i server MCP vengono avviati una sola volta all'avvio.

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

mcpsnoop

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

Per un server streamable-HTTP, esegui mcpsnoop come reverse proxy.

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

Lo stato HTTP di ogni risposta è visibile nello stream, quindi una risposta che non trasporta alcun messaggio JSON-RPC proprio resta comunque un frame visibile anziché nulla. Questo vale per la challenge 401, per il 403 su un Origin rifiutato, per il 202 che conferma una notifica e per il 502 quando il target non è raggiungibile affatto. L'header WWW-Authenticate di un 401 viene mantenuto verbatim e mostrato nell'inspector, poiché indica lo schema di autenticazione e i metadati della risorsa a cui rivolgersi 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 in tal caso, e la chiamata a cui ha risposto risulta fallita anziché ancora in attesa.

Nessun server tuo? Provalo davvero contro un server di test pubblico, pilotato dal tuo client. Per ispezionare una sessione dopo che si è verificata, vedi rivedere sessioni passate dai log.

Installazione

npm

Nessuna toolchain Go necessaria. La maggior parte dei server MCP è scritta in Node o Python, quindi questa è la via più breve.

npx mcpsnoop -- node build/index.js

Il pacchetto npm non contiene codice proprio. Sei pacchetti di piattaforma contengono ciascuno una build, e npm installa quello singolo che corrisponde alla tua macchina, quindi non c'è nulla da scaricare al momento dell'installazione e nulla da sbloccare in un proxy. Per mantenerlo disponibile invece di scaricarlo a ogni esecuzione, npm i -g mcpsnoop.

Homebrew

brew install mcpsnoop

Go