[SEP] Automatic _meta to HTTP Header Forwarding for Distributed Tracing #2029

monahk · 2025-12-29T21:56:46Z

monahk
Dec 29, 2025

Pre-submission Checklist

I have searched existing discussions and issues
This is a protocol-level proposal, not an implementation question
I have reviewed related work: Issue Include OpenTelemetry Trace identifiers as part of the MCP client -> server protocol #246, PR Add CSS section numbering for draft specification #666 (typescript-sdk), Discussion Proposal: Add Client-Level Request Identifiers for Distributed Tracing and Multi-Tenancy #801

Summary

Scope: Protocol Specification, SDK Implementation

I've submitted SEP PR #2028 proposing automatic forwarding of W3C Trace Context fields from _meta to downstream HTTP headers.

This discussion is to gather community feedback on the proposal.

The Problem

When an MCP client sends trace context via _meta:

{
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": { "location": "Dallas" },
    "_meta": {
      "traceparent": "00-e796ccb939d95b7c54d523095a9bd3b4-e515588135c1c901-01"
    }
  }
}

The MCP server receives _meta, but when it makes HTTP calls to external APIs, no trace headers are forwarded. This breaks distributed tracing at the MCP boundary.

Verification

I verified this gap by:

Sending _meta with traceparent from an MCP client
Using an unmodified MCP server (@timlukahorstmann/mcp-weather)
Intercepting outbound HTTP calls with a mock server
Result: No trace headers received

Proposed Solution

W3C Trace Context fields (traceparent, tracestate, baggage): Forwarded by default (opt-out)

These are standardized, non-sensitive, and designed for propagation
Matches OpenTelemetry auto-instrumentation behavior

Custom fields (correlation_id, tenant_id, etc.): Opt-in with whitelist

May contain sensitive data
Should not leak to third-party APIs without explicit configuration

Why Default-On for W3C Headers?

PR #666 (typescript-sdk) was rejected with rationale: "This PR introduces transport-specific concerns without protocol-level support."

This SEP provides that protocol-level foundation. But if adoption requires every server author to opt-in, adoption will be minimal and the distributed tracing problem remains unsolved.

Related Work

Issue Include OpenTelemetry Trace identifiers as part of the MCP client -> server protocol #246 - Established _meta convention (marked complete)
PR Add CSS section numbering for draft specification #666 (typescript-sdk) - Rejected, requested protocol support first
Discussion Proposal: Add Client-Level Request Identifiers for Distributed Tracing and Multi-Tenancy #801 - Client-level request identifiers (this SEP addresses the forwarding gap)

Discussion Questions

Should baggage be opt-in instead of default-on? (It can contain arbitrary key-value pairs)
Should forwarding be configurable per-tool?
Should there be capability negotiation so clients can discover server support?
Are there concerns with the default-on behavior for W3C headers?

SEP Document

Full specification: PR #2028

Looking for feedback and a potential sponsor for this SEP.

monahk · 2026-06-01T16:04:28Z

monahk
Jun 1, 2026
Author

Status update — SEP-2028 (for Discussion #2029)

Draft of a comment to post on #2029
Review before posting. Tone: factual status update + renewed sponsor ask.

📣 Status update: design matured, validated by a real client need, still seeking a sponsor

Quick update for folks following this thread since I opened it in December. The proposal in PR #2028 has evolved meaningfully, an open design question has been resolved, and there's now concrete evidence from the VS Code / Copilot team that this gap is real and worth closing.

1. The design moved from "forward by default" to a group-based policy system

The original proposal was a simple "forward W3C Trace Context headers automatically." Based on feedback, it's now a more robust group-based model where semantically related headers are treated as a unit, each governed by a single policy:

Policy	Behavior
`clear-and-use-meta`	If any header in the group is in `_meta`, replace the whole group with the `_meta` values
`prefer-meta`	Per-header: `_meta` overrides existing, otherwise preserve existing
`ignore-meta`	Never forward from `_meta` for this group

W3C Trace Context (traceparent, tracestate, baggage) is forwarded by default; everything else is opt-in. This keeps coupled headers like traceparent + tracestate from being mixed across sources, which would silently break traces.

2. Conflict resolution (raised by @michaelsafyan) is now resolved in the spec

Michael asked what should happen when trace context is present in both the inbound _meta and already-set outbound HTTP headers (e.g. from OpenTelemetry auto-instrumentation). That's now Section 6 — Conflict Resolution and Group Integrity in the SEP:

The per-group policy settles every combination (full behavior matrix in §1.2).
The SDK never mixes headers from different sources within a group ("group integrity").
Overriding an existing header is debug-logged, not an error — integrating with existing observability infra should "just work."

Thanks Michael — this made the proposal stronger.

3. Real-world validation: VS Code / Copilot hit exactly this gap

microsoft/vscode#302301 ("open telemetry support is not passing trace context to remote MCP server") — closed and shipped in VS Code 1.119.0 — is the same problem this SEP describes: HTTP calls to remote MCP servers weren't carrying traceparent, so distributed traces broke at the MCP boundary.

In that thread, the VS Code team (@digitarald) referenced this SEP by name, mapping the landscape:

SEP	Status	Covers
SEP-414	Final	`traceparent` in the JSON-RPC `_meta` field
SEP-2028	Open PR (seeking sponsor)	Automatic `_meta` → HTTP header forwarding

They shipped the SEP-414 half (_meta.traceparent) now because it's already final, and referenced SEP-2028 as the mechanism that would close the remaining HTTP-header gap for full interop on HTTP transports. To be clear this isn't a formal endorsement — but it's a concrete signal that a major MCP client has run into exactly the gap this SEP addresses.

4. Where it stands / what I need

✅ CI green, rebased on latest main (conflicts resolved).
✅ Open technical feedback addressed in the doc.
❌ Still no assigned sponsor — this is the only thing blocking the SEP from advancing per the SEP workflow.

If you're a maintainer working on transports, SDK behavior, or observability and this resonates — I'd love a sponsor. The VS Code issue above shows the demand is concrete and current. Happy to walk through the design, scope it down, or split it if that helps it land. 🙏

Feedback on the group-policy model is also very welcome here.

0 replies

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[SEP] Automatic _meta to HTTP Header Forwarding for Distributed Tracing #2029

Uh oh!

{{title}}

Uh oh!

Replies: 1 comment

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

[SEP] Automatic _meta to HTTP Header Forwarding for Distributed Tracing #2029

Uh oh!

monahk Dec 29, 2025

Pre-submission Checklist

Summary

The Problem

Verification

Proposed Solution

Why Default-On for W3C Headers?

Related Work

Discussion Questions

SEP Document

Replies: 1 comment

Uh oh!

monahk Jun 1, 2026 Author

Status update — SEP-2028 (for Discussion #2029)

📣 Status update: design matured, validated by a real client need, still seeking a sponsor

1. The design moved from "forward by default" to a group-based policy system

2. Conflict resolution (raised by @michaelsafyan) is now resolved in the spec

3. Real-world validation: VS Code / Copilot hit exactly this gap

4. Where it stands / what I need

monahk
Dec 29, 2025

monahk
Jun 1, 2026
Author