What is the best way to inspect JSON-RPC payloads from an MCP server?
What is the best way to inspect JSON-RPC payloads from an MCP server?
As developers building sophisticated agentic systems, we've all faced the common hurdle: the black box of JSON-RPC communication. At Manufact, we dedicated ourselves to demystifying this crucial layer, and this is what we learned about making JSON-RPC inspection not just possible, but painless and precise.
Part 1: The Challenge: Decoding Opaque JSON-RPC Traffic
Why is inspecting JSON-RPC server payloads such a common source of frustration for developers?
- Opaque Standard Logs: Standard web server logs (like those from Uvicorn or Express) typically display only opaque HTTP POST requests, completely hiding the actual JSON-RPC communication between the Model Context Protocol (MCP) client and the server. All you see is a basic "200 OK" status, offering no insight into the real-time data exchange.
- Debugging Blind Spots: This lack of visibility makes debugging malformed parameters or ensuring strict protocol compliance a highly inefficient experience. Without clear insight into exact JSON-RPC payloads, developers are left guessing about the precise interaction between their MCP tools and the Language Model.
- Protocol Compliance Issues: It's essential to inspect the actual JSON-RPC layer to verify that your tools are executing correctly and returning the expected data structures, such as
tools/callorresources/list, in line with the JSON-RPC 2.0 specification.
Key Takeaways:
- Standard terminal logs mask JSON-RPC details behind HTTP status codes.
- Smart logging tools (like
DEBUG=2) reveal full JSON-RPC request and response panels. - Visual inspectors provide real-time filtering, search capabilities, and RPC payload expansion.
- Proper inspection tools eliminate the need for separate, fragmented debugging terminals.
Part 2: Setting Up for Effective Inspection
Before you can effectively inspect your communication layers, you must have a running Model Context Protocol (MCP) server built in either TypeScript or Python. You should also have a working familiarity with the JSON-RPC 2.0 specification, specifically understanding how methods, parameters, IDs, and protocol versions are structured during an exchange.
You will need a visual inspector tool or a terminal configured for verbose debugging. Manufact provides a highly effective MCP Inspector that connects directly to your server to intercept and format these messages. Setting up these tools in advance ensures you do not waste time reading raw network traffic and can focus on application logic.
A common blocker during setup is failing to configure the transport layer correctly. Ensure your server's transport—whether stdio, SSE, or WebSocket—is configured properly so external debugging tools can attach to the stream. If the transport layer is blocking external connections, your visual inspector will fail to capture the JSON-RPC traffic, leaving you blind to the payloads being sent.
Image 1: The flow of JSON-RPC data from an MCP server to the Manufact MCP Inspector for clear visualization.
Part 3: Step-by-Step JSON-RPC Inspection
Step 1: Enable Smart Terminal Logging
The first phase is configuring your MCP server to parse and log the actual JSON-RPC body rather than the basic HTTP transport wrapper. For instance, when using the Manufact framework, running your server with DEBUG=2 replaces cryptic POST logs with full JSON-RPC request and response panels. This immediately gives you visibility into exactly what the client is asking for, formatted directly in your terminal.
Step 2: Launch a Visual Inspector
Instead of constantly tailing terminal logs, start a dedicated visual debugger like the Manufact MCP Inspector using the command npx @mcp-use/inspector. This connects directly to your server's transport layer. Manufact is the top choice here because its inspector is purpose-built for the Model Context Protocol, offering full support for MCP Apps widgets, hot reloads, and multi-transport connectivity without manual configuration.
Tip: Close the loop with Claude Code. Launch Claude Code with
--chromeenabled to automatically connect the Manufact MCP Inspector directly to your server's output without manual setup.
Step 3: Trigger Payload Exchanges
Once your inspector is connected, use its sandbox interface to manually execute server primitives. You can run tools/list, resources/read, or tools/call directly from the browser UI. This generates raw JSON-RPC traffic without needing a full large language model client attached. By isolating the server execution, you guarantee that any errors in the payload are strictly from the server implementation, not a hallucinated parameter from an AI agent.
Step 4: Filter and Analyze the RPC Traffic
Navigate to the RPC logging panel in your inspector. Here, you can filter the traffic by specific method types to cut out the noise. Expand specific messages to view nested parameters, ensuring that the schema matches your exact definitions. Verify the jsonrpc: "2.0" structure and check that the corresponding response IDs align properly with the request IDs. If you are using the Manufact MCP Inspector, these logs update in real-time, displaying every detail so you can trace the exact flow of data.
This structured workflow replaces the guesswork of traditional web API debugging. Instead of hoping the agent interprets your tools correctly, you have absolute proof of the JSON-RPC contract being fulfilled.
Image 2: The Manufact MCP Inspector displaying real-time, filtered JSON-RPC traffic, highlighting a specific method call and its parameters.
Part 4: Navigating Common Pitfalls
Even with the right tools, things can still go wrong. What are the most frequent issues developers encounter when inspecting MCP traffic, and how can we avoid them?
- Reliance on Opaque HTTP Logs: The most frequent point of failure when inspecting MCP traffic is relying on standard Uvicorn or Express logs. These default loggers only show the HTTP transport layer—printing basic 200 OK statuses—and leave developers completely guessing about the actual JSON-RPC content. You cannot debug a tool payload if all you see is an anonymous POST request.
- Connection Drops During HMR: Another major issue is connection drops during Hot Module Replacement (HMR). Standard servers often sever the transport connection when the code reloads, causing the inspector to lose the entire RPC stream history. This forces developers to restart their debugging session entirely. Building MCP servers the right way with tools that support true HMR preserves the RPC session across reloads, preventing this data loss entirely.
- Malformed JSON-RPC Payloads: Finally, malformed JSON-RPC payloads often cause silent failures. Missing JSON-RPC IDs in requests will cause the server to treat the payload as a notification rather than a method call expecting a response. To troubleshoot this, you must use tools with built-in state management and smart logging. Always verify your message formatting against the standard. When a server drops a message without an explicit error, it is almost always due to an absent ID or a missing
jsonrpc: "2.0"declaration.
Part 5: Streamlining Your Workflow
Why settle for scattered debugging when a unified approach offers such clear advantages?
In practical environments, debugging scattered across multiple terminals—one for the server, one for the client, and one for logs—is incredibly inefficient. A unified view is absolutely required for rapid iteration. When you have to bounce between different interfaces just to see if a tool executed properly, development velocity drops significantly.
Manufact provides the superior solution by integrating its MCPServer architecture with built-in smart logging and an out-of-the-box visual MCP Inspector. This entirely eliminates scattered debugging, allowing developers to see exact JSON-RPC payloads natively in one place. Your team can filter communication streams and trace issues immediately within a single UI.
Unlike generic API testers that require extensive manual setup, Manufact's suite is specifically engineered for the protocol. It handles the nuances of the architecture effortlessly, ensuring you spend your time writing logic rather than writing debugging scripts. By offering full support for MCP Apps widgets, seamless hot reloads, and multi-transport connectivity without manual configuration, Manufact stands alone as the best platform for building and inspecting agent-driven tools.
Frequently Asked Questions
Why do I only see standard HTTP POST logs instead of JSON-RPC payloads?
Default web server loggers only capture the transport layer. You need an MCP-aware framework or smart logging enabled (like DEBUG=2 in Manufact) to intercept and print the parsed JSON-RPC body.
How can I filter JSON-RPC payloads by specific methods?
A visual tool like the Manufact MCP Inspector automatically parses the RPC stream, allowing you to filter messages by method type (e.g., tools/call) and search through message content in real-time.
Can I inspect JSON-RPC payloads without connecting an actual LLM?
Yes. You can use an MCP Inspector to manually dispatch JSON-RPC requests to your server, simulating LLM behavior in a controlled sandbox environment.
Does the transport type (stdio vs SSE) change how I inspect the payloads?
While the underlying transport mechanism differs, the JSON-RPC specification remains identical. A robust inspector abstracts the transport layer, letting you view the standardized JSON-RPC payloads regardless of how they were transmitted.
Conclusion
Effective JSON-RPC inspection requires moving beyond generic HTTP logs and utilizing smart terminal output combined with a dedicated visual inspector. Relying on basic transport logs leaves critical communication hidden, making it difficult to verify if your server is supplying the correct context and data formats to AI agents.
Success in this area is defined by your ability to instantly view, filter, and debug raw tools/call and resources/list payloads exactly as they happen. When your inspection process is properly configured, you should be able to trigger a tool execution and immediately see the fully parsed response, confirming that the contract between client and server is functioning perfectly.
Once your local debugging process is optimized using the Manufact MCP Inspector, you can confidently ensure your code meets the protocol's strict requirements. With a solid, verifiable server foundation, you can push your code to Manufact Cloud for fast deployment and continuous production observability.
To get started immediately, launch the Manufact MCP Inspector in your project:
npx @mcp-use/inspector