Propagate W3C trace context via _meta per SEP-414

Inject traceparent/tracestate into request _meta on send, extract it
on the server side as the parent context for the handler span. This
enables cross-process trace propagation over stdio and HTTP transports.

Author: Kludex

src/mcp/server/lowlevel/server.py

@@ -65,7 +65,7 @@ async def main():
 from mcp.server.streamable_http import EventStore
 from mcp.server.streamable_http_manager import StreamableHTTPASGIApp, StreamableHTTPSessionManager
 from mcp.server.transport_security import TransportSecuritySettings
-from mcp.shared._otel import otel_span
+from mcp.shared._otel import extract_trace_context, otel_span
 from mcp.shared._stream_protocols import ReadStream, WriteStream
 from mcp.shared.exceptions import MCPError
 from mcp.shared.message import ServerMessageMetadata, SessionMessage
@@ -450,10 +450,15 @@ async def _handle_request(
         target = getattr(req.params, "name", None) if req.params else None
         span_name = f"MCP handle {req.method} {target}" if target else f"MCP handle {req.method}"
 
+        # Extract W3C trace context from _meta (SEP-414).
+        meta = getattr(req.params, "meta", None) if req.params else None
+        parent_context = extract_trace_context(meta) if isinstance(meta, dict) else None
+
         with otel_span(
             span_name,
             kind="SERVER",
             attributes={"mcp.method.name": req.method, "jsonrpc.request.id": message.request_id},
+            context=parent_context,
         ):
             if handler := self._request_handlers.get(req.method):
                 logger.debug("Dispatching request of type %s", type(req).__name__)
@@ -474,7 +479,7 @@ async def _handle_request(
                     task_support = self._experimental_handlers.task_support if self._experimental_handlers else None
                     # Get task metadata from request params if present
                     task_metadata = None
-                    if hasattr(req, "params") and req.params is not None:
+                    if hasattr(req, "params") and req.params is not None:  # pragma: no branch
                         task_metadata = getattr(req.params, "task", None)
                     ctx = ServerRequestContext(
                         request_id=message.request_id,

src/mcp/shared/_otel.py

@@ -6,6 +6,8 @@
 from contextlib import contextmanager
 from typing import Any
 
+from opentelemetry.context import Context
+from opentelemetry.propagate import extract, inject
 from opentelemetry.trace import SpanKind, get_tracer
 
 _tracer = get_tracer("mcp-python-sdk")
@@ -17,8 +19,19 @@ def otel_span(
     *,
     kind: str = "INTERNAL",
     attributes: dict[str, Any] | None = None,
+    context: Context | None = None,
 ) -> Iterator[Any]:
     """Create an OTel span."""
     span_kind = getattr(SpanKind, kind, SpanKind.INTERNAL)
-    with _tracer.start_as_current_span(name, kind=span_kind, attributes=attributes) as span:
+    with _tracer.start_as_current_span(name, kind=span_kind, attributes=attributes, context=context) as span:
         yield span
+
+
+def inject_trace_context(meta: Any) -> None:
+    """Inject W3C trace context (traceparent/tracestate) into a ``_meta`` dict."""
+    inject(meta)
+
+
+def extract_trace_context(meta: Any) -> Context:
+    """Extract W3C trace context from a ``_meta`` dict."""
+    return extract(meta)

src/mcp/shared/session.py

@@ -12,7 +12,7 @@
 from pydantic import BaseModel, TypeAdapter
 from typing_extensions import Self
 
-from mcp.shared._otel import otel_span
+from mcp.shared._otel import inject_trace_context, otel_span
 from mcp.shared._stream_protocols import ReadStream, WriteStream
 from mcp.shared.exceptions import MCPError
 from mcp.shared.message import MessageMetadata, ServerMessageMetadata, SessionMessage
@@ -269,8 +269,6 @@ async def send_request(
             self._progress_callbacks[request_id] = progress_callback
 
         try:
-            jsonrpc_request = JSONRPCRequest(jsonrpc="2.0", id=request_id, **request_data)
-
             target = request_data.get("params", {}).get("name")
             span_name = f"MCP send {request.method} {target}" if target else f"MCP send {request.method}"
 
@@ -279,6 +277,14 @@ async def send_request(
                 kind="CLIENT",
                 attributes={"mcp.method.name": request.method, "jsonrpc.request.id": request_id},
             ):
+                # Inject W3C trace context into _meta (SEP-414).
+                if "params" not in request_data:
+                    request_data["params"] = {}
+                if "_meta" not in request_data["params"]:
+                    request_data["params"]["_meta"] = {}
+                inject_trace_context(request_data["params"]["_meta"])
+
+                jsonrpc_request = JSONRPCRequest(jsonrpc="2.0", id=request_id, **request_data)
                 await self._write_stream.send(SessionMessage(message=jsonrpc_request, metadata=metadata))
 
                 # request read timeout takes precedence over session read timeout

tests/shared/test_otel.py

@@ -9,6 +9,7 @@
 pytestmark = pytest.mark.anyio
 
 
+@pytest.mark.filterwarnings("ignore::RuntimeWarning")
 async def test_client_and_server_spans(capfire: CaptureLogfire):
     """Verify that calling a tool produces client and server spans with correct attributes."""
     server = MCPServer("test")