You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
_meta Property on CallToolResult Use is Unclear #264
Describe the bug
The _meta property on CallToolResult has the description "This result property is reserved by the protocol to allow clients and servers to attach additional metadata to their responses." - "reserved" is generally used in specs to imply that the spec is reserving this for future definition, but I don't think that's actually correct here, I think this is meant as a free form field. The question would be - is that "reserved" in the traditional sense or is it fine to start using this today?
To Reproduce
N/A
Expected behavior
I would clarify the description to say "The result property is available for server to client communication of arbitrary data which falls outside the scope of this specification"
Similar to the above, I had a question if it was allowed by the spec to add additional metadata to the Tool object referenced in ListToolResults. In this case I wish to do annotate the tools with the required scopes in the backing APIs:
{
"name": "formManager",
"description": "A tool for managing form submissions and templates",
"inputSchema": {
"type": "object",
"properties": {
"formId": {
"type": "string",
"description": "The unique identifier for the form"
},
"action": {
"type": "string",
"description": "The action to perform on the form (create, read, update)"
},
"formData": {
"type": "object",
"description": "The data to be used when creating or updating a form"
}
},
"required": ["formId", "action"]
},
"_meta": {
"requiredScopes": [
"read:forms",
"create:forms",
"update:forms"
]
}
}
Since there is no additionalProperties on the root of Tool, it's unclear if this is allowed by the specification.
The documentation on _meta indicates that clients and servers may use it to "attach additional metadata to their interactions."
It says certain key names are reserved by the protocol but otherwise, valid _meta key names have two segments: an optional prefix, and a name then goes on to explain how those are constructed. This all seems pretty clear to me.
I agree with @cliffhall about the intent here, but I also agree with the issue at hand that reserved as a term is used differently in close proximity:
I think the first instance should be clarified with simpler language like The _meta property/parameter allows clients and servers to attach additional metadata to their interactions.
Maybe a broader question on how we use _meta going forward: I see the schema currently has progressToken as a reserved keyword with a specific type.
Lets say an MCP uses some new key like 'myCoolKey'. But then later the MCP spec defines something at 'myCoolKey'. Won't this cause issues? If this is the case I can't really see how MCP servers can safely use keys in this namespace.
I think I like the thing that the bit about the modelcontextprotocol/mcp prefix seems to be pointing at, which is official spec things will be namespaced, and everything else will be free for arbitrary metadata. And maybe that means we should move progressToken to something like modelcontextprotocol.io/progressToken?
Maybe a broader question on how we use _meta going forward: I see the schema currently has progressToken as a reserved keyword with a specific type.
Lets say an MCP uses some new key like 'myCoolKey'. But then later the MCP spec defines something at 'myCoolKey'. Won't this cause issues? If this is the case I can't really see how MCP servers can safely use keys in this namespace.
I think I like the thing that the bit about the modelcontextprotocol/mcp prefix seems to be pointing at, which is official spec things will be namespaced, and everything else will be free for arbitrary metadata. And maybe that means we should move progressToken to something like modelcontextprotocol.io/progressToken?
Good callout on the progressToken it should absolutely be something like mcp/progressToken based on the spec language. That can't happen without a breaking change, so it would be more straightforward to amend the spec to say something like "in addition the reserved key 'progressToken', all keys beginning with ... are reserved."
Closing as resolved by the 2026-07-28 release. The MetaObject rework defines _meta as a field "which clients and servers use to attach additional metadata to their interactions".
"Reserved" is no longer a blanket statement about the whole field: it now applies only to enumerated keys (e.g., progressToken) and the reserved key prefixes (io.modelcontextprotocol/, *.mcp/), which also resolves the progressToken collision concern raised in the thread. The _meta section of the 2026-07-28 basic spec matches.
If anything is still ambiguous against the released text, please open a fresh issue against the current spec.
Activity
btiernay commentedon Apr 10, 2025
Similar to the above, I had a question if it was allowed by the spec to add additional metadata to the
Toolobject referenced inListToolResults. In this case I wish to do annotate the tools with the required scopes in the backing APIs:{ "name": "formManager", "description": "A tool for managing form submissions and templates", "inputSchema": { "type": "object", "properties": { "formId": { "type": "string", "description": "The unique identifier for the form" }, "action": { "type": "string", "description": "The action to perform on the form (create, read, update)" }, "formData": { "type": "object", "description": "The data to be used when creating or updating a form" } }, "required": ["formId", "action"] }, "_meta": { "requiredScopes": [ "read:forms", "create:forms", "update:forms" ] } }Since there is no
additionalPropertieson the root ofTool, it's unclear if this is allowed by the specification.cliffhall commentedon Aug 19, 2025
The documentation on _meta indicates that clients and servers may use it to "attach additional metadata to their interactions."
It says certain key names are reserved by the protocol but otherwise, valid
_metakey names have two segments: an optional prefix, and a name then goes on to explain how those are constructed. This all seems pretty clear to me.tadasant commentedon Aug 19, 2025
I agree with @cliffhall about the intent here, but I also agree with the issue at hand that
reservedas a term is used differently in close proximity:I think the first instance should be clarified with simpler language like
The _meta property/parameter allows clients and servers to attach additional metadata to their interactions.domdomegg commentedon Aug 19, 2025
Maybe a broader question on how we use
_metagoing forward: I see the schema currently hasprogressTokenas a reserved keyword with a specific type.Lets say an MCP uses some new key like 'myCoolKey'. But then later the MCP spec defines something at 'myCoolKey'. Won't this cause issues? If this is the case I can't really see how MCP servers can safely use keys in this namespace.
I think I like the thing that the bit about the modelcontextprotocol/mcp prefix seems to be pointing at, which is official spec things will be namespaced, and everything else will be free for arbitrary metadata. And maybe that means we should move
progressTokento something likemodelcontextprotocol.io/progressToken?cliffhall commentedon Aug 19, 2025
Good callout on the
progressTokenit should absolutely be something likemcp/progressTokenbased on the spec language. That can't happen without a breaking change, so it would be more straightforward to amend the spec to say something like "in addition the reserved key 'progressToken', all keys beginning with ... are reserved."Clarify _meta property documentation
localden commentedon Aug 2, 2026
Closing as resolved by the
2026-07-28release. TheMetaObjectrework defines_metaas a field "which clients and servers use to attach additional metadata to their interactions"."Reserved" is no longer a blanket statement about the whole field: it now applies only to enumerated keys (e.g.,
progressToken) and the reserved key prefixes (io.modelcontextprotocol/,*.mcp/), which also resolves theprogressTokencollision concern raised in the thread. The_metasection of the2026-07-28basic spec matches.If anything is still ambiguous against the released text, please open a fresh issue against the current spec.