Implement SEP-414: Document OpenTelemetry Trace Context Propagation Conventions

[felixweinberger]

This is a tracking issue for implementation of SEP-414.

[mattzcarey]

Status — SEP-414 (OpenTelemetry Trace Context Propagation Conventions for _meta)

Track: C — independent, starts now. Convention-only; no RFC-2119 MUSTs.
Spec: seps/414-request-meta.md · merged

What's done

• Nothing in main. No traceparent / tracestate / baggage handling in packages/.
• @opentelemetry/api is already a transitive dependency (via vitest tooling), so no new third-party install needed.

Outstanding

SEP-414 has zero RFC-2119 keywords — it's pure convention. SDK work is a small propagation helper, not a normative requirement. Recommended scope:

1. Helper API (sketch):
   • Client side: an opt-in middleware/interceptor that reads the current @opentelemetry/api span context and writes _meta['traceparent'] / _meta['tracestate'] / optional _meta['baggage'] onto outgoing requests.
   • Server side: a corresponding helper that reads those keys off ctx.mcpReq._meta and attaches them to the active span (or starts one).
2. No hard dependency on @opentelemetry/api in the published packages — keep it as an optional peer dependency or a separate @modelcontextprotocol/otel middleware package.
3. Docs in the middleware package's README, plus a runnable example under examples/.

Note

• The convention keys live in _meta at the request-params level, not under any extension prefix. They're not gated by capability negotiation.
• Companion to SEP-2575's _meta['io.modelcontextprotocol/*'] envelope, but not a part of it — implementers should not move these keys into the io.modelcontextprotocol/ namespace.

Coordination

• Independent. Lives best in a separate @modelcontextprotocol/otel middleware package (matches the existing pattern of @modelcontextprotocol/{express, hono, node, fastify}).
• Worth pairing with Implement SEP-2577: Deprecate Roots, Sampling, and Logging #2195 (SEP-2577) since OpenTelemetry is the recommended replacement for the deprecated logging/setLevel feature.

[norika1207-lab]

This looks worth pinning down as a protocol-level regression rather than only an implementation bug.

For OpenTelemetry Trace Context Propagation Conventions, the acceptance test I would want is a minimal client/server fixture that records the exact JSON-RPC or HTTP exchange, then asserts both the wire result and the local lifecycle state after the failure path. In MCP deployments, the dangerous failures are often not just wrong return values; they are pending requests, dropped notifications, mismatched session state, or errors that get translated into a generic response and become impossible to diagnose.

A useful fix boundary would preserve three signals: the protocol error sent to the peer, the local exception or cancellation reason available to application code, and a trace/log field that ties the two together. That makes the behavior debuggable for agent hosts without requiring every host to special-case this SDK detail.