mcpsnoop: A Transparent Proxy and TUI for Debugging MCP Traffic
mcpsnoop: A Transparent Proxy and TUI for Debugging MCP Traffic
mcpsnoop provides real-time visibility into the communication between AI clients (such as Claude Desktop, Cursor, or Claude Code) and Model Context Protocol (MCP) servers by acting as a transparent proxy. Unlike traditional inspectors that connect as separate clients, mcpsnoop sits directly in the data path, capturing every tool call, response, and notification as they occur.
Solving the MCP Visibility Gap
The primary challenge in debugging MCP servers is that official tools, like the MCP Inspector, operate as independent clients. This means they cannot see the actual traffic generated by a user's real AI client. When a tool fails to trigger, capabilities mismatch, or a request hangs, developers are often forced to rely on manual log tailing in /tmp and guesswork.
mcpsnoop eliminates this gap by wrapping the server command. It forwards bytes verbatim between the client and server while simultaneously streaming a copy of every JSON-RPC frame to a live terminal UI. This ensures that developers see exactly what the real client is sending and what the server is returning.
Core Features and Debugging Capabilities
Live Traffic Monitoring and Analysis
mcpsnoop offers a color-coded live stream of JSON-RPC frames, including requests, responses, and notifications. Key monitoring features include:
- Hung-Call Detection: In-flight requests are marked as
PENDINGwith a live timer, making stuck tools immediately obvious. - Error Flagging: The tool flags both standard JSON-RPC errors and tool-level
result.isErrorflags. - Frame Inspection: Users can drill into any frame (using the
enterkey) to view pretty-printed JSON with full-text search capabilities. - Capability Inspection: By pressing
c, developers can verify the exact capabilities agreed upon during the initial handshake between the client and server.
Rapid Iteration with Replay
One of the most powerful features of mcpsnoop is the ability to re-run any captured tool call against a fresh, isolated instance of the server. This allows developers to iterate on tool logic without having to manually trigger the action again through the AI client.
Advanced Filtering
To manage high-volume traffic, mcpsnoop supports a query-based filtering system. Users can combine space-separated tokens to narrow the stream:
- Field-specific filters:
tool:,method:,id:,kind:,dir:, andstatus:. - Example: A query like
tool:search status:slowisolates slow calls specifically made to a search tool.
Architecture and Implementation
mcpsnoop is implemented as a single binary with two distinct roles:
- The Shim: When run as
mcpsnoop -- <server>, it acts as the transparent proxy that the AI client spawns. - The Hub/TUI: When run as
mcpsnoopwithout arguments, it launches the terminal interface.
These two components communicate via a well-known socket and on-disk logs. Because the TUI backfills past sessions from disk, the UI can be opened either before or after the AI client starts.
For streamable-HTTP servers, mcpsnoop can function as a reverse proxy using the following command:
mcpsnoop http --target http://localhost:3000/mcp --listen :7000
Comparison with Other MCP Tools
| Feature | MCP Inspector | mcp-trace | mcpsnoop |
|---|---|---|---|
| Sees real client–server traffic | No | Yes | Yes |
| Interactive terminal UI | No | Yes | Yes |
| Zero-config / No flags | No | No | Yes |
| Capability inspector | Partial | No | Yes |
| Replay captured calls | No | No | Yes |
| Single binary (no runtime deps) | No | Varies | Yes |
Installation
mcpsnoop can be installed via Go, Homebrew, or by downloading prebuilt binaries:
- Go:
go install github.com/kerlenton/mcpsnoop/cmd/mcpsnoop@latest - Homebrew:
brew tap kerlenton/mcpsnoop && brew install mcpsnoop
Community Insights
While the tool is praised for filling a critical visualization gap in the AI client workflow, community discussions suggest potential areas for future growth:
"Remote debugging and post-mortem debugging support might be useful. There are many AI auditability proxies... Aegis and LiteLLM, for example, are pre-execution firewalls that add a cryptographic audit trail."
Other users have suggested extending the tool's utility by adding a browser-based interface for data browsing or creating an MCP server for Wireshark itself to further integrate network analysis into the protocol.