docs(rfd): Draft: Meta Field Propagation Conventions

[codefromthecrypt]

Document params._meta as the convention for propagating metadata from clients to agents, such as trace identifiers or correlation IDs.

This aligns with MCP, enabling shared instrumentation since both protocols use stdio JSON-RPC transports.

[ignatov]

Thanks, it makes lots of sense for better traces

[yordis]

Should those "reserved" keys under meta be part of the actual spec payload (it does not have to be at the root).

In most message-passing system I worked on the need for metadata + system metadata is inevitable to avoid these issues. The infra/platform engineers agree on the system level metadata, while the domain/product engineers are free to do what they want under the metadata.
Other times, they pick a prefix $ for things, eg: Nats, KurrentDB. So it would be just one metadata field, but the keys prefixed is reserved.

Otherwise, too much disciplined and keep up with things is required. Or future considerations needs that weren't cover, and now people did it their way and the spec can not simply break so many users without backslash.

[codefromthecrypt]

@yordis yeah your point about prefixes or dedicated namespace is totally reasonable. many systems do it that way even if otel norms typically use whatever the core metadata carrier is (e.g. inject directly into kafka headers).

Some reasons to highlight from this change is that it is following a soft agreement that exists today, vs creating a new one. This is central to the otel propagation and maybe I wrote things in a way that triggered into thinking this must be applied for all future decisions.. that wasn't my intent. Mainly, I want to help carve out propagation notes that align with today.

Here are the salient points on that:

• MCP already uses them flat today (the C# SDK has tests asserting the exact wire format {"traceparent":"00-..."})
• every otel sdk's TextMapPropagator expects keys at root - nesting would break the whole propagation ecosystem
• keeping compatibility means instrumentation libraries can support both protocols with a single code path

One note: There's no practical way to enforce these reserved keys beyond documentation. The SDKs all type _meta as open dictionaries with no validation. Schema enforcement would require changing the JSON Schema to explicitly forbid these keys for user data, which would be a breaking change and isn't how MCP works today either.

In other words, I'm hoping for a pragmatic evolution of _meta practice here, and if we need to break into separate meta categories and diverge from MCP norms, it might be out of scope. I'm not even sure if LSP breaks into different categories of meta, but again that would be a bigger discussion than this one I think.

How about this change to the RFD.. would it help to "soft reserve" the keys by documenting the core ones?

e.g. revise Change 2 to explicitly reserve these keys:

-**Change 2**: After the JSON example, before "Implementations **MUST NOT**", add this paragraph:
-
-> Clients may propagate fields to the agent for correlation purposes, such as `requestId`. [OpenTelemetry
SDKs](https://opentelemetry.io/docs/languages/sdk-configuration/general/#otel_propagators) default to propagating W3C `traceparent`, `tracestate`, and
`baggage` fields as root keys in `_meta`.
+**Change 2**: After the JSON example, before "Implementations **MUST NOT**", add:
+
+> Clients may propagate fields to the agent for correlation purposes, such as `requestId`. The following root-level keys in `_meta` are reserved for [W3C
trace context](https://www.w3.org/TR/trace-context/) to guarantee interop with existing MCP implementations and OpenTelemetry tooling:
+>
+> - `traceparent`
+> - `tracestate`
+> - `baggage`

this doesn't prevent anyone from using namespaced prefixes for their own metadata if they prefer that pattern: it mainly protects the three keys that existing tooling already depends on.

let me know if this works for you and i'll update the PR.

[benbrandt]

At this point, the best we can do is a SHOULD in the spec anyway without necessitating a new version of the protocol.

Obviously, as we get ready for v2, we should revisit all of the SHOULDs and see which should become MUSTs, but I also see some value today in providing some top-level telemetry/observability/pick your title guide for the protocol that if you want traces, this is how you can add them to your _meta fields.

This will also allow us as an ecosystem to start implementing this and see what we might still be missing.

We could add some top-level dedicated field for telemetry, outside of _meta, but I think starting by following the example from other protocols seems like a good first step to me.

It also seems low-risk that these three keys happen to be used in any context outside of OTEL anyway... (maybe baggage... but again, that is usually for OTEL and kind of a grab bag of data already)

[codefromthecrypt]

agree @benbrandt I'll switch the wording to SHOULD. Also, when we make the otel guide, this should link out to it for elaboration. agree on that, too

[codefromthecrypt]

ok rebased and I think this covers it. lemme know

[benbrandt]

Looks great! I'm sure there will be some discussion about the final wording, but I've already updated the schema in #290 to match where this is going.

I guess part of the implementation may also be sketching some of this out in the SDKs as well to automate certain properties for the users, but we can figure this out as we go.

Merging to Draft stage 🎉

[codefromthecrypt]

#297 to actually make the doc edit. I decided to leave the code comments and schema alone, unless you believe otherwise is needed.