Trace your MCP server
Record MCP tool calls as Judgment traces in Python or TypeScript, and group calls into sessions.
Record each MCP tool execution as a span in Judgment. Open the span to inspect the call and any instrumented work inside the tool.
This integration instruments a server you operate. To connect a coding agent to Judgment's tools, follow Connect your coding agent.
Before you start
Complete the tracing prerequisites in the process that runs your MCP server. Keep your server's existing transport and authentication configuration.
Use judgeval 1.9.0 or later for Python, or 1.8.1 or later for TypeScript.
Supported server libraries are:
- Python: the official
mcpSDK, versions 1.x and 2.x, and standalonefastmcp. - TypeScript:
@modelcontextprotocol/sdk1.x and@modelcontextprotocol/server2.x.
Both languages support high-level servers and the low-level Server API.
Instrument the server
Instrument your MCP server with your coding agent
Paste it into your agent from your repo's root.
Initialize tracing once, then instrument the server before it handles requests. These examples start a stdio server with one lunch-order tool:
Install the SDKs in the server's environment:
pip install "judgeval>=1.9.0" mcpSave this as server.py and run python server.py:
from mcp.server.fastmcp import FastMCP
from judgeval import Tracer
from judgeval.integrations.mcp import instrument_mcp_server
Tracer.init(project_name="lunch-order-agent", environment="development")
server = FastMCP("lunch-tools")
@server.tool()
def get_menu(restaurant: str) -> str:
"""Get a restaurant's catering menu."""
return f"{restaurant}: mezze platters and shawarma bowls"
instrument_mcp_server(server)
if __name__ == "__main__":
try:
server.run(transport="stdio")
finally:
Tracer.shutdown()Connect an MCP client to the server and call get_menu with restaurant set to Olive & Thyme. Each execution records its server name, tool name, duration, and outcome.
Instrumented operations inside the handler become child spans. The integration doesn't instrument database clients or other libraries by itself.
Each request starts a trace unless it supplies explicit incoming trace context, such as params._meta.traceparent. With that context, the MCP execution becomes a child in the incoming trace.
Control agent arguments
By default, the integration adds these fields to compatible tool input schemas for the calling agent to supply:
| Field | Advertised requirement | Purpose |
|---|---|---|
intent | Required | The agent's reason for calling the tool. |
llm_model | Required | The calling model, as reported by the agent. This value is unverified. |
conversation_id | Optional | An ID the agent repeats on later calls in the same conversation. |
Judgment records intent and model identity when the agent supplies them; it doesn't infer these values. The SDK still executes and traces calls that omit SDK-added fields.
SDK-added fields are removed before your handler runs. Tool results include conversation instructions when the SDK generates an ID.
An existing field with the same name stays unchanged and isn't read as telemetry unless you explicitly select it. Schemas that accept arbitrary argument names don't receive injected fields.
To reuse a tool's existing intent field, set the argument option:
instrument_mcp_server(server, intent_argument="intent")The existing field keeps its schema and reaches your handler unchanged. If a tool doesn't declare the selected field, the SDK adds it when injection is on.
Use model_argument and conversation_id_argument in Python, or modelArgument and conversationIdArgument in TypeScript, for the other fields.
To record calls without adding fields or conversation instructions, turn off argument injection:
instrument_mcp_server(server, inject_agent_arguments=False)Argument injection changes tool schemas and results even when tracing export is off. It also adds text to the agent's context.
Group calls into sessions
A session groups calls from one conversation. An application session takes priority over agent-reported conversation IDs.
The SDK selects the session in this order:
- An application session from the
session_idcallback, request-scoped tracing context, or an explicitly selected existing conversation field. - A conversation ID echoed by the agent.
- An ID generated for this call when conversation injection is on and the tool schema supports it.
- The MCP transport session ID, when available.
TypeScript names the callback sessionId. Return your application's conversation ID to group calls without relying on the agent to repeat it.
The first call uses its generated ID immediately, including on stateful HTTP. The result asks the agent to repeat that ID on later calls.
If the agent doesn't repeat it, each eligible call receives a different ID. A thrown exception has no returned result in which to deliver the instructions. A failed first call can therefore appear in a separate session.
To use transport grouping instead, turn off conversation injection while keeping intent and model fields:
instrument_mcp_server(server, inject_conversation_id=False)An application session still wins. Without one or a transport session, calls have no session ID.
Identify the calling client
The integration records the MCP client's reported name and version when available. These values identify the client software, not the authenticated user.
For legacy stateless Streamable HTTP clients, the SDK returns an opaque Mcp-Session-Id to carry client identity on later requests. Existing native transport session IDs stay unchanged. Client-reported identity isn't an authentication credential.
Python installs this behavior through the server's HTTP app factory. If your custom ASGI host bypasses that factory, add McpClientIdentityMiddleware to the app:
from judgeval.integrations.mcp import McpClientIdentityMiddleware
app.add_middleware(McpClientIdentityMiddleware)Control captured content
Input, output, and error-message capture are off by default. Agent-reported intent is recorded when supplied through an injected or explicitly selected field.
Use these options to control content before export:
| Python | TypeScript | Effect |
|---|---|---|
capture_input | captureInput | Record the tool's business arguments. |
capture_output | captureOutput | Record the tool's original result. |
capture_error_messages | captureErrorMessages | Record failure text. |
redact_payload | redactPayload | Transform captured input and output. |
redact | redact | Transform reported intent and failure text. |
The SDK doesn't scrub sensitive data automatically. Review the content your tools can expose before turning capture on.
Verify the calls
- Open your project and select MCP under Monitoring in the sidebar.
- Open Calls and select the
get_menucall to see its details. Check the server name, tool name, duration, outcome, and session ID. - Select View source trace to open the trace with the tool's span selected. Inspect any instrumented child spans there.
Use Overview for charts, Tools for tool-level metrics, Failures to investigate errors, and Sessions to explore related calls.
You can also inspect the execution through Monitoring → Logs → Traces.
Nested tool executions appear in MCP Analytics too. Judges and Issues operate on the containing trace, not only the selected MCP span.
If something looks wrong
| Symptom | Check |
|---|---|
| Calls don't appear | Initialize tracing before serving requests, check credentials and project, and flush before the process exits. |
| Calls appear as separate sessions | Check whether the client repeats conversation_id. Supply an application session callback when the application knows the conversation ID. |
| The tool rejects an added argument | Low-level servers must expose their original schemas. Supply resolve_original_tool in Python or resolveOriginalTool in TypeScript for a request-scoped lookup. |
| A strict client rejects a result after deployment | Injection changes output schemas too. Refresh cached tool listings and keep replicas on compatible schemas during deployment. |
Error types show as tool_error | The MCP framework may convert an exception into a tool-error result before instrumentation sees it. |
Low-level servers should advertise stable schemas for each tool name and send tool-list change notifications when those schemas change. For caller-dependent schemas, use a resolver that returns the caller's original schema.
Trace an already instrumented server
Keep existing OpenTelemetry instrumentation when it already records each tool execution. Use attribute keys and mappers to identify those spans without recording each execution twice.
Next, add context to traces to record application sessions and customer identifiers.