mcpsnoop — AI Agent Development

MCP(Model Context Protocol) communication is inspected and analyzed in real time — an AI agent development tool.

Basic Information

What is this program?

mcpsnoop is a development tool that captures and analyzes communication between AI agents and MCP(Model Context Protocol) servers. It acts as a proxy between the MCP server and client, displaying tool calls, resource requests, and notification messages in a human-readable format.

When developing MCP-based agents, checking which tools were called, what parameters were passed, and what responses the server returned is a core debugging task. mcpsnoop records this flow in real time and provides filtering, search, and replay features.

What problems does it solve?

• ('Agent debugging', 'When you don’t know which MCP tools the agent calls', 'You can see the list of tool calls and parameters in the proxy capture.')
• ('Server development', 'When you need to verify that an MCP server returns correct responses', 'You can display request-response pairs side by side to find schema and type errors.')
• ('Integration testing', 'When you need to include MCP communication in automated tests', 'You can export captured communication as JSON and use it for replay testing.')

Key Features

Proxy Capture

Capture communication by placing a proxy between the MCP client and server.

• When to use: Analyzing agent-server communication
• What you get: View communication without modifying the server
• Limitations: Additional setup is needed if the MCP server requires a proxy certificate.

Tool Call Tracing

Visualize tool calls, resource reads, and notifications on a timeline.

• When to use: Understanding agent behavior flow
• What you get: Visually see which tools were called in what order
• Limitations: The timeline can become crowded with high-frequency calls.

JSON Export & Replay

Save captured communication as JSON and replay it.

• When to use: Regression testing and sharing
• What you get: Verify communication compatibility after MCP server changes
• Limitations: Replay does not make real server calls, so watch out for external effects.

Filter & Search

Filter in real time by tool name, parameters, and response content.

• When to use: Extracting only relevant communication from high traffic
• What you get: Quickly find the communication you need
• Limitations: Regex filters can be CPU-intensive.

Installation and Execution

Node.js (npm)

Install globally with npm.

npm install -g mcpsnoop
mcpsnoop --version

Python (pip)

Install with pip in Python environments.

pip3 install mcpsnoop

Source Build

Node.js 18+ is required to build from source.

git clone https://github.com/mcpsnoop-dev/mcpsnoop
cd mcpsnoop
npm install
npm run build

Real-World Usage Examples

Run in Proxy Mode

Start capturing by wrapping the MCP server with a proxy.

$ mcpsnoop --proxy --server "npx @modelcontextprotocol/server-filesystem /data" --port 9229

[mcpsnoop] proxy listening on :9229
[mcpsnoop] MCP server attached: filesystem
[mcpsnoop] ready — connect your client to localhost:9229

Check Tool Calls

Check captured tool calls in real time.

[tool.call]  read_file  {"path": "/data/config.yaml"}
[tool.result] 200 OK  (128 bytes, 3ms)
[tool.call]  list_directory  {"path": "/data"}
[tool.result] 200 OK  (14 entries, 5ms)

Save and Replay Captures

Save captures as JSON and replay them later.

$ mcpsnoop --save session.json
$ mcpsnoop --replay session.json --server mock://filesystem
# replay complete: 24 calls, 0 errors

Advantages and Limitations

Advantages

• Capture MCP communication via proxy without modifying the server
• Visualize tool calls and responses in a human-readable timeline
• Support regression testing with JSON export and replay
• Support installation via both Node.js and Python

Points to Consider Before Use

• The MCP specification changes quickly, so support for the latest protocol features may lag.
• Going through a proxy adds a small amount of latency (usually a few ms).
• Memory usage needs to be managed when capturing large volumes of traffic.

Comparison with Similar Programs

Official Resources and Further Learning

• Official homepage — https://mcpsnoop.dev/
• Official documentation / knowledge base — https://mcpsnoop.dev/docs/
• Official downloads — https://mcpsnoop.dev/downloads
• Release notes — https://mcpsnoop.dev/changelog
• Source / development resources — https://github.com/kerlenton/mcpsnoop

Version and supported environment information was confirmed on the official site as of 2026-10-18. Installation commands may vary depending on your distribution and version, so please also check the official installation documentation.

Actual Execution Screen

The screen below is a synthetic example created to help you understand the usage flow (not an actual execution result). The screen is a synthetic example, not an actual execution result.

!mcpsnoop proxy capture example: capturing read_file and list_directory calls on an MCP filesystem server

Actual production server

Source (HTML): https://games.aidebatehub.com/programs/apps/agentdev/mcpsnoop.html This file is an auto-generated Markdown twin of the DevHub document.