What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
To find out why MCP tools fail, trace the MCP tools/call operation itself—not just the network request around it. Capture the method, tool name, MCP-level error status, and trace context across the client/server boundary, then correlate the server span with downstream API or database spans. A transport request can succeed even when the tool returns an error.
Why generic APM can miss an MCP tool failure
Many application performance monitoring (APM) views make network spans, broad exceptions, or downstream service activity visible without making the MCP operation that caused them easy to identify. A useful trace should show that the request was an MCP tools/call, which tool was invoked, and whether the tool reported an MCP-level error. Without those details, “Why are my MCP tool calls failing?” can be difficult to answer from a trace that shows only a successful HTTP exchange or an exception several steps later.
As an Amazon Associate I earn from qualifying purchases.
The official MCP Python SDK OpenTelemetry documentation describes a server span for each handled message: “Every server you create emits an OpenTelemetry span for every message it handles.” That span is a starting point, but the instrumentation must also represent the semantics of the tool result. The SDK documentation says a handler exception or a tool result with is_error=True marks the span as an error. See the MCP Python SDK OpenTelemetry documentation for version-specific behavior.
What an MCP tool-call trace should contain
For a call to tools/call, the MCP Python SDK documentation uses the GenAI operation name execute_tool and the gen_ai.tool.name attribute. Together with the method, these make it clearer which protocol action and tool the span represents. The OpenTelemetry GenAI conventions also describe request metadata for context propagation; their definitions are evolving, so verify the current keys rather than relying on older registry entries.
#1 Best Overall
- Operation: identify the MCP method, especially
tools/call, and use the applicable GenAI operation name where supported. - Tool: record the tool name, such as
gen_ai.tool.namewhen following the SDK’s documented convention. - Outcome: distinguish a handler exception or
is_error=Truetool result from a successful tool result. Do not infer tool success from transport success alone. - Correlation: retain trace and request identifiers, plus protocol or session context when relevant and safe, so client, server, and dependency activity can be connected.
- Dependencies: instrument downstream HTTP, API, or database work so the tool’s own span can be followed into the operation that may have failed.
The MCP semantic-conventions guidance describes passing trace context in MCP request metadata at params._meta. The Python SDK documents automatic W3C trace-context propagation when both sides use its SDK. For the evolving conventions and the legacy-attribute notice, consult the OpenTelemetry GenAI semantic conventions and the OpenTelemetry MCP attribute registry.
How to trace a call across the client and server
- Locate where the flow stops. Determine whether the problem occurs before initialization, while listing tools, in the
tools/callrequest, in the server handler, or in a downstream dependency. This keeps protocol and application failures from being conflated. - Instrument the MCP client and server. Ensure the relevant spans expose the method and tool name, and that tool errors—including results marked
is_error=True—are represented as errors. Check your SDK and instrumentation versions because coverage and attribute conventions vary. - Propagate trace context across the boundary. If both endpoints use the MCP Python SDK, its documentation describes automatic W3C trace-context propagation. Otherwise, check whether your client and server use the MCP request metadata mechanism described by the GenAI conventions; merely instrumenting each process independently does not guarantee one end-to-end trace.
- Instrument the work performed by the tool. Add supported instrumentation for the server’s outbound HTTP, API, and database operations. OpenTelemetry’s demo pairs MCP server instrumentation with HTTPX client instrumentation, allowing the tool span and outbound request to appear in the same trace. See the OpenTelemetry demo documentation.
- Inspect the trace and related logs. Follow the trace from client request to server handler and then into dependency spans. Match logs using trace or request identifiers where available; the demo notes that its standard-library logs go to stdout and are not correlated with traces by default.
Check instrumentation coverage before choosing a setup
“MCP instrumentation” does not guarantee the same coverage in every language, SDK, transport, or backend. Compare implementations against the specific diagnostic requirements you have:
Rank #2
- Which language and MCP SDK versions are supported, and are both client and server covered?
- Which transports work, and how is trace context propagated between processes?
- Does the instrumentation recognize MCP tool-result errors, including
is_error=True, or only exceptions and transport failures? - Can you see downstream dependency spans in the same trace?
- Are metrics emitted, and what payload or log capture is enabled by default?
- Can your tracing backend query and visualize the attributes you need?
For example, telemetry.dev’s MCP integration page says it requires the official TypeScript SDK v2 packages and does not support MCP v1. It does not emit metrics, and it does not capture arguments or successful tool results by default. Optional payload capture remains subject to SDK controls such as masking and maximum attribute length; enabling it is a data-handling choice, not a prerequisite for tracing. Check the telemetry.dev MCP integration documentation for its stated scope and controls.
Keep evolving conventions and payload risks in view
The older OpenTelemetry MCP attribute registry says MCP attributes moved to the GenAI semantic-conventions repository. Because those conventions and integrations can change, validate attribute names against the current documentation for the SDK and exporter you deploy. Avoid treating a legacy key as a durable standard simply because it appears in an older trace or dashboard.
Tool arguments and successful results may contain credentials, personal information, or other sensitive data. Start with operation, tool, status, and correlation metadata; capture payloads only when necessary and after considering access, retention, masking, and length limits. Payload visibility can help diagnose input-specific behavior, but it also increases the amount of sensitive data in telemetry.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Use a tracing backend to follow the spans
Tracing instrumentation and the backend serve different roles: the SDKs produce spans and propagate context, while the backend ingests, stores, and presents them. Google Cloud’s documentation describes a Cloud Trace workflow for remote MCP server calls and OTLP export; Elastic’s walkthrough shows MCP tool-call instrumentation flowing into Elastic APM, including trace waterfalls, latency percentiles, error tracking, and service maps. These are vendor descriptions of their own workflows, not a neutral comparative benchmark. See Google Cloud Trace: Trace remote MCP server calls and Elastic Observability Labs’ MCP and OpenTelemetry walkthrough.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
