To trace MCP (Model Context Protocol) tool calls across a client and server, you need to instrument both sides of the connection: the client that initiates the request and the server that executes the tool. This article explains the exact steps, common pitfalls, and tools you can use to capture and follow a tool call from the user’s prompt to the tool’s result and back.
Background: What MCP Tool Calls Look Like
MCP (Model Context Protocol) is an open standard that lets AI applications (clients) connect to external tools and data sources (servers). A tool call is a request from the client to the server, asking the server to run a specific function with given arguments. The server responds with the result (or an error).
The protocol uses JSON-RPC 2.0 messages over transports like stdio (standard input/output) or HTTP/SSE. Each message has an id, a method (e.g., tools/call), and params containing the tool name and arguments.
Tracing a tool call means capturing these messages at both ends, correlating them by the request ID, and understanding the flow: client sends request → server receives → server executes → server sends response → client receives.
How MCP Tool Calls Are Structured
Here is a typical sequence for a tool call:
- Client sends a request – The client (e.g., an AI assistant) sends a JSON-RPC message with method
tools/call, including the tool name and arguments. - Server receives and validates – The server checks if the tool exists and if the arguments match the schema.
- Server executes the tool – The server runs the actual function (e.g., a database query, an API call).
- Server returns a response – The server sends a JSON-RPC response with the same
idand aresultobject. - Client processes the result – The client uses the result to continue the conversation or display it to the user.
In a distributed setup, there may be intermediate proxies or gateways, but the core request-response pattern remains.
How to Trace a Tool Call: Step-by-Step
To trace a tool call across client and server, follow these steps:
- Enable logging on both sides – Most MCP SDKs have built-in logging. For example, the TypeScript SDK uses
consoleor a logger; Python SDK useslogging. Set the log level toDEBUGto see message contents. - Add a unique request ID – JSON-RPC already includes an
idfield. Make sure your client generates unique IDs and your server echoes them back. - Capture network/stdio traffic – If using stdio, you can wrap the server process with a tool like
strace(Linux) ordtrace(macOS) to see raw data. For HTTP, use a proxy likemitmproxyorngrokto log requests. - Add timing and context – Include timestamps, session IDs, and user IDs in your logs to correlate across systems.
- Use a tracing tool – OpenTelemetry can be used to create spans for each tool call, linking client and server traces with trace IDs.
- Verify the result – Check that the response ID matches the request ID and that the result is what the tool returned.
Tools and SDKs for Tracing
Several tools and SDKs can help you trace MCP calls:
- MCP Inspector – A built-in debugging tool in the MCP TypeScript SDK that shows the JSON-RPC messages in a web UI.
- OpenTelemetry – Can instrument both client and server to produce distributed traces. Use the
@opentelemetry/instrumentation-jsonrpcor custom spans. - Logging libraries – Use
pino(Node.js) orstructlog(Python) to create structured logs that are easy to search. - Network sniffers –
tcpdumpor Wireshark for HTTP/SSE traffic;stracefor stdio. - Proxy tools –
mitmproxyfor HTTP, or a simple TCP proxy to log raw bytes.
For a quick test, you can also write a small script that reads from stdin and writes to stdout, logging every line, and place it between the client and server if they use stdio.
Common Problems When Tracing
Here are frequent issues you may encounter:
- Missing request IDs – If the server doesn’t echo the ID, you can’t correlate the response. Ensure your SDK does this.
- Logs not showing messages – Some SDKs only log at INFO level by default. Set the environment variable
MCP_LOG_LEVEL=debug(if supported) or configure the logger. - stdio buffering – When using stdio, output may be buffered. Use
stdbuf -o0on Linux to disable buffering. - HTTP/SSE connection issues – If using SSE, the connection stays open; you need to capture the stream, not just individual requests.
- Encryption – If using HTTPS, you need to set up MITM with a custom CA cert to decrypt traffic.
- Multiple clients/servers – In a complex setup, you may need to add a trace ID to the request context to follow a single call across hops.
Comparing Client-Side vs Server-Side Tracing
Client-side tracing shows what the AI model sees: the tool name, arguments, and the result. It helps debug why the model chose a tool or how it uses the result. Server-side tracing shows the actual execution: the function called, any internal errors, and the raw output. It helps debug tool implementation issues.
For a full picture, you need both. A common approach is to use a correlation ID that the client generates and passes to the server via the request params (or a header in HTTP). Then you can search logs on both sides for that ID.
If you only have access to one side, you can still trace the call by monitoring the network traffic between them, but you lose the internal context.
Costs and Performance Overhead
Tracing adds overhead:
- Logging every message can increase I/O and storage costs, especially at scale.
- OpenTelemetry instrumentation adds CPU and memory overhead, typically 1-5% depending on the volume.
- Network proxies add latency (usually a few milliseconds) and require additional infrastructure.
To minimize costs, sample traces (e.g., log only 10% of calls) or log only errors. Use structured logging to make searching efficient.
Safety and Security Considerations
When tracing tool calls, you may capture sensitive data:
- Tool arguments may contain user PII, API keys, or database credentials.
- Tool results may include private data.
- Logs should be stored securely and access-controlled.
Always redact sensitive fields before logging, or use a logging system that supports field-level masking. If you use a proxy, ensure it doesn’t log request bodies by default. For production, consider using a dedicated tracing service with encryption at rest and in transit.
Alternatives to Manual Tracing
If manual tracing is too cumbersome, consider these alternatives:
- MCP Inspector – For development, it provides a visual interface to send test calls and see responses.
- Distributed tracing platforms – Jaeger, Zipkin, or Datadog can automatically trace JSON-RPC calls if you use their SDKs.
- Log aggregation – Use ELK stack or Loki to centralize logs and search by request ID.
- Custom middleware – Write a wrapper around the MCP server that logs every call and result without modifying the tool code.
Choose the approach based on your environment: development vs production, scale, and budget.
Frequently Asked Questions
How do I trace an MCP tool call if I only have access to the client?
If you only have client access, you can log the request and response at the client side. To see what the server actually did, you need server logs or a network capture. Alternatively, you can add a custom field to the request that the server echoes back, and then ask the server team to search their logs for that field.
Can I trace MCP calls over stdio without extra tools?
Yes, you can wrap the server process in a script that reads stdin and writes stdout, logging every line. For example, a simple Python script that reads lines, logs them, and forwards them to the server process. This works but may add latency.
What is the difference between a trace and a log in MCP?
A trace is a structured representation of a single request’s lifecycle, often with spans and timing. A log is a timestamped message. Traces are more useful for correlating across services, while logs are simpler but harder to follow across systems.
Does MCP support distributed tracing natively?
No, MCP does not define a tracing standard. You need to implement your own correlation IDs or use OpenTelemetry to propagate context across the client and server.
How can I trace tool calls in production without exposing sensitive data?
Use a logging library that supports redaction, or write a custom serializer that masks fields like passwords, tokens, and personal data. Also, consider sampling and storing logs in a secure location with access controls.
Why don’t I see the tool call in my server logs?
Possible reasons: the server is not logging at DEBUG level, the log output is buffered, or the request is not reaching the server (network issue). Check that the server is listening on the correct transport and that the client is pointing to the right endpoint.
Related
Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.
More cards in this drawer
- How to Choose an Amplifier for Magico A3 Speakers
- How to Ban a Player from Your FiveM Server
- Pokemon Go Friend Codes: How to Add & Use Them33.33 XP/day
- Google Algorithm Change: Original Reporting Boost
- Create Folder for Selected Item on Mac: Full Guide
- Data Center Location Questions for AI Workloads