Repository navigation
Adding Opentelemetry to MCP SDK #421
Description
Activity
related Issue for feature request in traceloop/openllmetry to enable observability for MCP Server, traceloop/openllmetry#2662
I'm now trying to inject a tracer for each request by defining the SofaTracerMiddleware（which inherits BaseHTTPMiddleware) and accessing the above plugin for the mcp server application via add_middleware.
class SofaTracerMiddleware(BaseHTTPMiddleware): def __init__(self, app): super().__init__(app) @property def tracer(self): return opentracing.tracer async def dispatch(self, request, call_next): headers = request.headers # Extract the OpenTracing context from the incoming request headers try: input_context = self.tracer.extract(format=Format.HTTP_HEADERS, carrier=headers) except opentracing.InvalidCarrierException: input_context = None # Start a new span for the incoming request with self.tracer.start_active_server_span(SPAN_CODE_HTTP_SERVER, context=input_context) as scope: span = scope.span span.url = str(request.url) span.method = request.method.upper() span.request_size = request.headers.get("content-length", 0) response = await call_next(request) span.result_code = str(response.status_code) span.response_size = response.headers.get("content-length", 0) current_context = _SCOPE.get() if current_context: print(f"Current tracer in worker: {current_context}") else: print("No active tracer in this context.") return response app = FastMCP() app.sse_app().add_middleware(SofaTracerMiddleware)
But I found that the requests about message used the same tracer from the initialise method with url messages, and the subsequent initialize and tools methods didn't use the new tracer
It is also clear from the logs that the ContextVarsScope used for opentracing each time a request is processed is that of the first request, even though handle_post_message and SofaTracerMiddleware use the latest ContextVarsScope for each request.
So now do I have a way to get my own async ContextVarsScope for each request?
Hi @wenxuwan,
I tried your approach and I don't think it will work because if you choose http header to propagate trace context, only the initialize request has http header. That's why you see the same parent for all subsequent requests as well.I was tinkering with the traceloop way of passing context by intercepting and wrapping over
_handle_requestfunction inmcp.server.lowlevel.server.pyfor server side andsend_requestfunction inmcp.shared.session.pyfor client side tracing. I am trying to passtraceparentinparams.meta.traceparentof theRequestParamsfromtypes.py.
I am able to map correct parent - child span relationship.Screenshot shows how the context is propagated from Agent application to MCP servers back and forth. Here parent - child span ID is correct.
Hi @wenxuwan, I tried your approach and I don't think it will work because if you choose http header to propagate trace context, only the initialize request has http header. That's why you see the same parent for all subsequent requests as well.
I was tinkering with the traceloop way of passing context by intercepting and wrapping over
_handle_requestfunction inmcp.server.lowlevel.server.pyfor server side andsend_requestfunction inmcp.shared.session.pyfor client side tracing. I am trying to passtraceparentinparams.meta.traceparentof theRequestParamsfromtypes.py. I am able to map correct parent - child span relationship.Screenshot shows how the context is propagated from Agent application to MCP servers back and forth. Here parent - child span ID is correct.
You are right, but not quite the same as my problem. Right now I'm not passing the tracer inside my http request. every time I make a request
with self.tracer.start_active_server_span(SPAN_CODE_HTTP_SERVER, context=input_context) as scopeThe new contextVar is generated inside the current async, but now only one async has been processing the user's request, so the tracer is the Contextvar of the first request. That's why handle_post_message gets the newest tracer every time, but when processing the request is using the tracer of the first request.
Adding some links:
modelcontextprotocol/modelcontextprotocol#246 - request to add tracing to MCP spec
modelcontextprotocol/modelcontextprotocol#414 - fix for the spec to useparams._metafor trace context propagation such asparams._meta.traceparent
open-telemetry/semantic-conventions#2083 - semantic convention proposal for MCP traces and metrics.Reacted by Dan Millerfor the context propagation part, you can have a look at @anuraaga's code in openinference or if such a change is welcome maybe he can help raise it. I don't know the SDK specific policies about an otel dependency, but as python is flexible with imports maybe it is fine to just add it directly?
Workaround for the problem of ContextVars being lost in the async streams preventing other forms of context propagation from working: pydantic/logfire#1459
5 remaining items
Noticed this since happen to be mentioned here a long time ago but not a maintainer. But as a general instrumenter, want to note that API can't work unless
- instrument-start returns a value that is passed to instrument_end
- it's one instrument function accepting a next type of function
Generally I'd recommend the latter. Langchain was stuck for going with the former with no return value. Now I can't open this link for whatever reason.
- added a commit that references this issue
on Nov 28, 2025 OTel python uses a
ContextVarto propagate the trace/span context. AContextVaris supposed to be a per-thread and per-task variable.. Is the issue that the MCP library just uses 1 task per-connection instead of per-request, so we get the ContextVars from when the connection started ?Or is it possibly due to where the task is getting it's context from ? According to this a
anyio.Taskgets it's context from theanyio.Taskthat call's it'sstartmethod..With
asyncio.Taskyou can explicitly pass aContext..I have a pretty minimal fix to propagate contextvars through the anyio streams by attaching a
contextvars.ContexttoSessionMessageand restoring it in the worker tasks main...aabmass:mcp-python-sdk:propagate-contextvars.I'm happy to add more tests send a full PR if maintainers are onboard with this approach. The change is completely independent of OTel and would also benefit other users of contextvars.
Hi — I opened PR #1693 a while back with a pluggable instrumentation interface (token-based API) to address this issue. That PR is now stale due to significant refactoring in the codebase (
_handle_request,ServerRequestContext, task support, etc.).I noticed this issue is assigned to @Kludex — are you already planning or working on an approach for this? I'm happy to:
- Rewrite my PR against the current codebase if the contribution is welcome
- Step aside if you have a different design in mind
- Collaborate on a shared approach
Just want to avoid duplicating work. Let me know how you'd like to proceed.
- added a commit that references this issue
on Apr 5, 2026 Strong agree on baking OTel in. The minimum useful spans are server-side request_handler (with tool/prompt/resource type as an attribute), client-side outgoing tool_call, and a transport-layer parent that links sessions to spans across the SSE/streamable-http boundary.
Worth using the gen_ai semantic conventions for tool spans (gen_ai.tool.name, gen_ai.tool.call.id) so existing OTel collectors can correlate MCP traffic with the LLM call that triggered it. OpenInference's semconv overlaps but isn't the standardized one.
Happy to draft a proposal if there's appetite.
I’m interested in taking a narrow, non-overlapping slice of #421.
I noticed #2093 is already working on trace-context propagation through
_meta, so I would avoid duplicating that work.A smaller first PR I can take:
- add or document a lightweight request/tool lifecycle instrumentation surface;
- avoid adding OpenTelemetry as a hard SDK dependency;
- include tests using a fake recorder rather than a real exporter;
- add an example showing how users can map MCP request/tool lifecycle events to OpenTelemetry spans externally.
Would maintainers prefer this as:
- a small code-level hook surface on
main/ v2, or - a docs/examples-only PR first?
I’m happy to keep the first PR minimal and aligned with the existing v2 direction.
Reacted by Dan MillerThe minimum stable API should make OTel mapping possible without making OTel the dependency.
I would expose request/tool/resource lifecycle events with a fake-recorder test suite: send_request, handle_request, tool_call, resource_read, prompt_get, success, and error. Each event should carry session id, request id, method, tool/resource name, and traceparent metadata when present.
Separately, context propagation through anyio/contextvars needs a regression test. If context disappears across the task boundary, every higher-level span design becomes hard to reason about.
Generated with ax.
This is close to the direction I was exploring in #1693.
One detail I’d keep explicit in the API shape: lifecycle hooks need either to return a token/state from
startand receive it again onend/error, or be modeled as a wrapper around the handled operation. Otherwise OTel span lifetime has to be tracked through side storage, which gets fragile once async/task boundaries are involved.I also agree that a fake-recorder test suite is the right first layer. It lets the SDK define stable lifecycle semantics without committing to OpenTelemetry as a hard dependency, while a separate adapter can map those events to OTel spans/metrics.
And +1 on the contextvars/anyio regression test being a prerequisite. If context disappears across the stream/task boundary, every higher-level instrumenter becomes harder to reason about.
I added a public synthetic fixture for the lifecycle-hook shape discussed here, mainly to make the fake-recorder requirement concrete without forcing OpenTelemetry as a hard dependency.
The case is mcp_lifecycle_fake_recorder: send_request -> handle_request -> tool_call -> tool_result -> span_end, all joined by the same request id. The tool result explicitly carries mcp_is_error: true and
esult_state: failed, so an implementation can prove that a failed MCP result does not become a successful span or persisted result by accident. The fixture also asserts that span lifetime needs a token/state that can survive async boundaries.Fixture: https://github.com/HarperZ9/telos/blob/e12425b/demo/integrations/agent-boundary-fixtures.json
Verifier: https://github.com/HarperZ9/telos/blob/e12425b/demo/agent-boundary-fixtures.test.mjsThis is not a conformance claim against the SDK; it is just a small receipt-shaped test corpus that might help keep the first instrumentation API narrow and fake-recorder-testable.
Hey everyone! As this issue has gotten quite long and open telemetry has been added into the v2 beta version of
mcpI think it'd be best to go ahead and close this issue for now.I'd super appreciate if people go ahead and test the open telemetry integration we currently have, and then make new issues for feedback/suggestions/issues you run into going forward.
More info here: https://py.sdk.modelcontextprotocol.io/v2/run/opentelemetry/
Reacted by Tom Plant and Zain Dana Harper
Is your feature request related to a problem? Please describe.
I would like to see Opentelemetry traces and Metrics baked into SDK.
E.g.
Describe the solution you'd like
I am trying to use Opentelemetry sdk to add traces and metrics features.
Steps
BaseSession(src/mcp/shared/session.py).traceparent) to_metaofRequestParams.Metabefore sending request from client (send_requestinsrc/mcp/shared/session.py)traceparentfrom received request to create new span with incoming span as parent span.Describe alternatives you've considered
I tried to implement the same via traceloop. I was not able to get correct parent - child relationship between spans while doing so.
Additional context
I am able to achieve distributed tracing across my Agentic application and MCP server.