Skip to content

docs: Better document _meta field type and usage #297

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
benbrandt merged 1 commit into from
Dec 5, 2025
+9 −1
Merged

docs: Better document _meta field type and usage #297

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 8 additions & 1 deletion docs/protocol/extensibility.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link

@cliffhall cliffhall Jan 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This elaboration is TypeScript-centric. I think we can make it more JSON-centric.

Suggested change
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.
All types in the protocol include a `_meta` field that implementations can use to attach custom information. It is an object whose keys are strings and values can be any other JSON value. This includes requests, responses, notifications, and even nested types like content blocks, tool calls, plan entries, and capability objects.


```json
{
Expand All @@ -23,12 +23,19 @@ All types in the protocol include a `_meta` field that implementations can use t
}
],
"_meta": {
"traceparent": "00-80e1afed08e019fc1110464cfa66635c-7a085853722dc6d2-01",
Copy link
Contributor Author

@codefromthecrypt codefromthecrypt Dec 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this wasn't in the RFD, but figured it can re-enforce below. happy to remove it though

Copy link

@cliffhall cliffhall Jan 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The existing example of zed.dev/debugMode illustrates an important part of using _meta, which is making the key unique to your server to avoid naming conflicts.

Even with the follow-on explanation, I fear the presence of the traceparent key in the example could be confusing, especially if someone only checks the example and doesn't read on to find out that this is the execption to the rule — that we're advocating a carve-out for an existing tech for compatibility.

"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:
Copy link

@cliffhall cliffhall Jan 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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:
A best practice for naming keys in the `_meta` object is to uniquify it with your domain or app name, e.g,, `"zed.dev/debugMode": true` in the example above. This helps to avoid naming conflicts.
In some cases, however, for compatibility with existing and related technologies, it may not be possible to uniquify the key. In those cases, a request to reserve their keys will be included in this spec.
### OpenTelemetry key reservations
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
Expand Down
1 change: 1 addition & 0 deletions docs/rfds/meta-propagation.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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