From b18bd782bae4354f3d92a7f2fa3dc354d98d0dde Mon Sep 17 00:00:00 2001 From: Adrian Cole Date: Thu, 4 Dec 2025 19:28:08 +0800 Subject: [PATCH] Document _meta propagation conventions Update extensibility documentation with: - Type annotation for _meta field: { [key: string]: unknown } - W3C trace context propagation conventions (traceparent, tracestate, baggage) - Example showing traceparent in _meta --- docs/protocol/extensibility.mdx | 9 ++++++++- docs/rfds/meta-propagation.mdx | 1 + 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/protocol/extensibility.mdx b/docs/protocol/extensibility.mdx index 60aa0b73..31441013 100644 --- a/docs/protocol/extensibility.mdx +++ b/docs/protocol/extensibility.mdx @@ -7,7 +7,7 @@ The Agent Client Protocol provides built-in extension mechanisms that allow impl ## The `_meta` Field -All types in the protocol include a `_meta` field that implementations can use to attach custom information. This includes requests, responses, notifications, and even nested types like content blocks, tool calls, plan entries, and capability objects. +All types in the protocol include a `_meta` field with type `{ [key: string]: unknown }` that implementations can use to attach custom information. This includes requests, responses, notifications, and even nested types like content blocks, tool calls, plan entries, and capability objects. ```json { @@ -23,12 +23,19 @@ All types in the protocol include a `_meta` field that implementations can use t } ], "_meta": { + "traceparent": "00-80e1afed08e019fc1110464cfa66635c-7a085853722dc6d2-01", "zed.dev/debugMode": true } } } ``` +Clients may propagate fields to the agent for correlation purposes, such as `requestId`. The following root-level keys in `_meta` **SHOULD** be 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` + Implementations **MUST NOT** add any custom fields at the root of a type that's part of the specification. All possible names are reserved for future protocol versions. ## Extension Methods diff --git a/docs/rfds/meta-propagation.mdx b/docs/rfds/meta-propagation.mdx index f21e8626..714a9cd6 100644 --- a/docs/rfds/meta-propagation.mdx +++ b/docs/rfds/meta-propagation.mdx @@ -62,4 +62,5 @@ Here are several MCP SDKs that propagate W3C trace-context in `_meta`: ## Revision history +- 2025-12-04: Implementation in extensibility docs - 2025-11-28: Initial draft