Skip to content

Comments

docs: Clarify _meta property#1403

Open
domdomegg wants to merge 6 commits intomainfrom
adamj/clarify-meta-documentation
Open

docs: Clarify _meta property#1403
domdomegg wants to merge 6 commits intomainfrom
adamj/clarify-meta-documentation

Conversation

@domdomegg
Copy link
Member

Summary

  • Remove confusing "reserved by MCP" language from _meta property documentation
  • Clearly specify what keys are actually reserved: progressToken (backwards compatibility) and keys with modelcontextprotocol.* or mcp.* prefixes
  • Explicitly state that all other keys are available for arbitrary use by implementations
  • Update both draft and 2025-06-18 specification versions

This resolves the documentation ambiguity raised in the issue where "reserved" was used in conflicting ways.

Fixes #264

Remove confusing "reserved by MCP" language and clearly specify what keys are actually reserved:
- progressToken (for backwards compatibility)
- Keys with modelcontextprotocol.* or mcp.* prefixes

All other keys are available for arbitrary use by implementations.

Fixes #264
@domdomegg domdomegg requested a review from a team August 29, 2025 12:29
@domdomegg domdomegg changed the title Clarify _meta property documentation docs: Clarify _meta property Aug 29, 2025
@domdomegg
Copy link
Member Author

I think this is minor enough to not require a SEP? But happy to raise one if needed.

@domdomegg domdomegg force-pushed the adamj/clarify-meta-documentation branch from eb8a185 to 3edbc67 Compare August 29, 2025 12:33
@domdomegg domdomegg removed request for a team August 29, 2025 12:34
@localden
Copy link
Contributor

This feels like it materially changes the interpretation of _meta so typically would need a SEP, but also I'd be curious if this actually impacts any servers or clients directly with the change (i.e., are there any constructs where _meta is treated as reservered today where this can introduce potential ambiguities)?

@dend dend added the documentation Improvements or additions to documentation label Sep 8, 2025
…elcontextprotocol prefix

- Use reverse DNS notation (io.modelcontextprotocol instead of modelcontextprotocol.io)
- Only reserve io.modelcontextprotocol prefix (removed mcp.* reservation)
- Add SHOULD recommendation for implementations to use reverse DNS
- Update examples to demonstrate reverse DNS pattern
- Only modify draft specification (revert 2025-06-18 changes)

Aligns with SEP proposal for _meta clarification.
Resolved conflicts by:
- Keeping both _meta Reserved Keys documentation and icons documentation in index.mdx
- Using origin/main's progressToken comment in schema.ts
- Regenerating schema.json and schema.mdx from the corrected schema.ts
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

_meta Property on CallToolResult Use is Unclear

3 participants