MCP failures are difficult to diagnose when a standalone inspector works but the real client does not. mcpsnoop addresses that gap by operating as a transparent shim or proxy in the actual data path and exposing the JSON-RPC frames exchanged by client and server.
It can reveal whether a client discovered the expected schema, which arguments it sent, how the server responded and where a timeout occurred. The project supports stdio wrapping and HTTP proxying, so setup depends on the server transport.
A focused workflow
- Reproduce the issue with the smallest possible request.
- Insert mcpsnoop between the real client and server.
- Capture one failing interaction.
- Compare tool names, schemas, parameters, result envelopes and timing.
- Fix one layer, repeat, and save a known-good baseline.
The repository documents demo, export, check, baseline, diff, open and prune commands. Baseline-and-diff is particularly useful after an MCP server upgrade because it turns an invisible protocol change into a reviewable artifact.
Captures are sensitive
Frames may contain prompts, paths, document excerpts, arguments, access tokens or personal data. mcpsnoop includes redaction, but describes it as best effort. Use synthetic data where possible, restrict capture-directory permissions, keep retention short and inspect exports before sharing.
mcpsnoop shows what crossed the boundary; it does not explain why a model selected a tool or prove that a server action was correct. Pair traces with client and server logs. If the problem is model-context volume, see the tokdiet guide.
Primary source: mcpsnoop repository.
What to compare in a trace
Check initialization, protocol version, capability negotiation and the tool list before focusing on the final call. Compare JSON types as well as values: an empty string, missing property and null can behave differently. Record timestamps around client and server to separate network delay from execution. After the fix, prune sensitive captures and preserve only a sanitized minimal regression example.