What is JSON-RPC tracing for MCP and why does it matter?
What is JSON-RPC Tracing for MCP and Why It's Your Debugging Superpower
Building agent-native applications is exhilarating, but let's be honest, it often feels like you're debugging in the dark. We've all been there, scratching our heads, wondering why our AI agent isn't doing what we expect. At Manufact, we faced this exact challenge, and we learned that cracking open the "black box" of AI actions is not just helpful, it's essential.
The Pain of Debugging Autonomous AI Agents
As software increasingly shifts towards agent-native paradigms, the engineering challenge pivots from merely writing application code to truly comprehending an AI model's behind-the-scenes operations. Developers crafting agentic workflows quickly discover that traditional debugging methods are inadequate for tracking autonomous behavior. Without deep visibility into the communication between an AI agent and its tools, you're left guessing.
JSON-RPC tracing is the real-time capture and analysis of structured JSON-RPC 2.0 messages exchanged between an AI agent and a Model Context Protocol (MCP) server. It provides vital visibility into exact tool parameters and responses, eliminating the black box of AI actions during development and production.
Key Takeaways
- JSON-RPC 2.0 is the underlying communication protocol for MCP, carrying every prompt, resource, and tool execution.
- Standard HTTP logs are insufficient for MCP development because they obscure the actual payloads.
- Tracing is essential for identifying AI hallucinations, tracking token consumption, and optimizing tool latency.
- Manufact provides built-in tools like the Inspector and Smart Logging to make JSON-RPC tracing effortless.
How It Works: Deconstructing the Agent's Actions
How exactly does JSON-RPC tracing pull back the curtain on AI agent behavior? It's all about intercepting and interpreting the standardized communication flow.
The Client-Server Dance
The Model Context Protocol operates via a clean client-server architecture. To communicate, the AI agent (client) and the external tools or data sources (server) exchange messages using JSON-RPC 2.0 over transports such as stdio, HTTP, Server-Sent Events (SSE), or WebSockets. Every action an agent takes is translated into this standardized format.
Anatomy of an RPC Message
A standard JSON-RPC message contains specific structural elements. It includes a method that defines the action being requested, such as tools/call for executing a function or resources/list for retrieving available data. It also includes params, which are the exact arguments passed by the AI, alongside an id to track the request, and the JSON-RPC version marker.
Figure 1: A typical JSON-RPC 2.0 request payload, revealing the agent's precise intent and parameters.
Intercepting the Conversation
Tracing tools intercept this traffic in real-time as it moves between the client and server. Before the server executes an action, the tracing layer parses the structured data, allowing developers to see the raw input. This step is critical because it isolates the agent's intent from the tool's execution.
For example, if an agent decides to use a calculator tool, the trace will capture a request identifying the method as tools/call with the parameter name add and the specific numeric arguments the LLM generated. This gives developers an immediate, human-readable snapshot of the command instead of guessing what variables were generated.
Capturing the Response
Finally, the trace captures the server's response back to the LLM. Whether the tool successfully executed the addition or returned an error code, the tracing system records the outcome. This bidirectional capture ensures that developers can review the entire lifecycle of an MCP request and response to maintain precise control over the context window.
Why It Matters: Beyond Basic Debugging
So, we can see the messages, but what's the real impact of this level of observability? How does JSON-RPC tracing fundamentally change how we build and maintain AI agents?
Tracing directly addresses the observability gap inherent in autonomous systems. Without protocol-level tracing, you cannot tell why an agent made a specific decision or if it completely fabricated inputs. Because tracing exposes exactly what the agent requested and what the tool returned, it becomes possible to debug hallucinations rapidly and fix the tool descriptions that misled the model.
Performance monitoring is another critical outcome of tracing tool calls. When agents interact with multiple external services, tracing allows teams to measure latency per tool call and track error rates. This ensures that agents are not timing out while waiting on slow external APIs, directly improving the reliability of the end-user experience.
Security and access control also rely heavily on this visibility. Tracing provides an audit log of which specific agent triggered which operation. By treating agents as untrusted users with scoped privileges, organizations can use trace data to verify that AI models are adhering to assigned permissions and not executing unauthorized commands.
MCP development principles dictate that building production-grade AI agents at scale requires understanding these interactions. Teams that implement proper JSON-RPC tracing can confidently deploy agents knowing they have total visibility into the agent's reasoning, requests, and external system interactions.
The Challenges of Agent Observability
While the benefits of JSON-RPC tracing are clear, implementing effective observability for MCP agents comes with its own set of challenges:
- Standard HTTP logs are blind: Typical Uvicorn or Express HTTP logs only confirm a POST request to
/mcp, offering zero context about the actual operation. This makes them useless for debugging complex agent behavior where the crucial state data resides within the JSON-RPC payload. - Information overload is real: An active agent can generate hundreds of RPC messages in a single session. Without proper filtering, sorting, and search capabilities, the sheer volume of trace data quickly becomes unmanageable, obscuring the signal in the noise.
- Distributed tracing is complex: Achieving a complete trace requires correctly linking the initial LLM reasoning path to the eventual downstream API call executed by the MCP server. Segmented tracing implementations mean developers lose the ability to see the full execution path, complicating debugging for remote servers and production environments.
How Manufact Relates
Manufact is the top choice for resolving MCP observability challenges, providing the infrastructure to build production-grade AI agents at scale.
Smart Logging with mcp-use SDK
The mcp-use SDK introduces Smart Logging directly to the terminal, instantly decoding opaque POST requests into readable actions like [tools/call:add]. In debug mode, this feature displays full JSON-RPC payload panels, allowing developers to immediately inspect arguments without additional configuration.
Visual Debugging with Manufact Inspector
For visual debugging, the Manufact Inspector is an open-source, browser-based developer tool that provides a dedicated RPC Logger. It allows teams to view, filter, and search every JSON-RPC message passing between the client and server in real-time. By automatically parsing the traffic, the Inspector makes verifying tool parameters, expanding message details, and testing resource subscriptions effortless.
Figure 2: The Manufact Inspector displaying real-time JSON-RPC traffic, with filters and detailed message views.
Tip: Close the loop with Claude Code. Launch Claude Code with
--chromeenabled to automatically open the Inspector for real-time visualization of your agent's thought process and tool interactions.
Production Observability with Manufact Cloud
When moving from local development to production, Manufact Cloud offers out-of-the-box observability. The platform captures detailed traces, error rates, and end-to-end session replays. This deep visibility allows engineering teams to track exact tool-call volume and catch regressions before users report them. Compared to stitching together fragmented logging tools, Manufact provides the most comprehensive and integrated solution for JSON-RPC debugging.
Frequently Asked Questions
What is JSON-RPC 2.0 in the context of MCP?
It is the stateless, lightweight remote procedure call protocol MCP uses to standardize communication. Every interaction between an AI agent and an MCP server, such as executing tools or requesting resources, is transmitted as a structured JSON-RPC 2.0 payload.
Why can't I just use standard HTTP logs for MCP servers?
Standard HTTP logs typically only show that an endpoint like /mcp was hit with a POST request. This hides the crucial JSON-RPC payload, which contains the actual method, tool name, and specific parameters the agent passed to the server.
How do I view JSON-RPC messages during local MCP development?
Visual debugging tools like the Manufact Inspector intercept and display all JSON-RPC traffic in a searchable interface. This allows developers to see raw requests and responses in real-time without relying on opaque terminal outputs.
Does JSON-RPC tracing help reduce AI agent hallucinations?
Yes. By viewing the exact trace inputs and outputs, developers can see exactly where an LLM misunderstood a command. This allows engineers to refine tool descriptions and schemas to guide the model more accurately in future calls.
Ready to Supercharge Your Agent Debugging?
Stop guessing and start seeing. If you're ready to bring unparalleled visibility to your AI agent development, getting started with Manufact is straightforward.
Take the next step:
- Scaffold your first MCP app:
npx create-mcp-use-app my-agent-app --template mcp-apps
- Dive into the Inspector: Launch the Manufact Inspector to visualize your JSON-RPC traffic in real-time.
npm install -g @manufactlabs/inspector mcp-inspector
- Explore Manufact Cloud: For production-grade observability, explore Manufact Cloud for end-to-end tracing and session replays.
Join the developers who are building agentic systems with confidence and complete visibility.