SEP-1788: Clarify _meta Property Reserved Keys

Type: Standards Track
Author: Adam Jones (@domdomegg)
Sponsor: Tadas Antanavicius (@tadasant)
Status: Proposal

Abstract

This SEP clarifies which keys in the _meta property are reserved for MCP protocol use and which are available for arbitrary use by implementations. The specification currently uses ambiguous language around "reserved" keys. This proposal establishes clear rules: only progressToken (for backwards compatibility) and keys with prefix io.modelcontextprotocol are reserved; all other keys are available for implementation-specific metadata.

Motivation

The current spec states that _meta is "reserved by MCP" but has confusing language around which keys implementations can use today. As a result developers don't know if they can safely add custom keys without risking conflicts with future spec additions. For more details on the ambiguity see #264 and #1403.

Additionally, there's no clear namespace strategy to prevent collisions between custom keys and future protocol additions.

Specification

Changes to _meta Documentation

Replace the current preamble text:

The _meta property/parameter is reserved by MCP to allow clients and servers to attach additional metadata to their interactions.

With:

The _meta property/parameter allows clients and servers to attach additional metadata to their interactions.

Reserved Keys

Add a new "Reserved Keys" section to the _meta documentation:

Reserved for MCP protocol use:

1. progressToken (for backwards compatibility)
2. Any key with a prefix io.modelcontextprotocol

• Examples: io.modelcontextprotocol/auth, io.modelcontextprotocol.registry/version

All other keys are available for arbitrary use by implementations.

Implementations SHOULD use reverse DNS notation for custom keys (e.g., com.example/customData) to avoid collisions with other implementations. Future MCP protocol additions will only use the reserved patterns above.

(note that this restricts future MCP additions to only use io.modelcontextprotocol prefix, which is more strict than at the moment, but I think should be fine?)

Rationale

Reverse DNS for protocol keys: Uses io.modelcontextprotocol (not modelcontextprotocol.io) for consistency with the MCP Registry namespacing. This avoids URL coupling and provides better alphabetical sorting. Also see discussion about this at #1724 (comment).

Keep progressToken without namespace: Moving it would be a breaking change. We explicitly reserve it for backwards compatibility and use namespacing for all future additions.

Backward Compatibility

This change is purely clarifying and backwards compatible. I don't think any SDK changes are necessary.

Reference Implementation

Pull Request: #1403