docs: clarify reverse DNS namespacing rules for server names and extension metadata

[ognis1205]

Clarifies how reverse DNS namespacing is used in server.json, explicitly documenting that subdomains may be included as necessary for uniqueness, and that there is no fixed limit on the number of domain segments.

Motivation and Context

The current specification and examples use reverse DNS identifiers, but do not explicitly state whether subdomains are allowed or how many domain segments are valid.

This has led to potential ambiguity, especially when examples appear to use a fixed number of segments, which can be interpreted as an implicit constraint rather than a convention.

This change adds a short clarification to make it explicit that:

• Subdomains may be included as necessary for uniqueness.
• There is no fixed limit on the number of reverse DNS components, as long as the namespace is derived from a domain controlled by the publisher.

This aligns the documentation with common reverse DNS usage and helps avoid accidental namespace collisions.

How Has This Been Tested?

This change is documentation-only.

Breaking Changes

None.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

modelcontextprotocol/modelcontextprotocol#2127

[Fannon]

Looks good, it's helpful to have this written out clearly.

From the MCP Protocol spec, it's less strict, more of a recommendation. Also not sure it mentiones the key name after the reverse domain: https://modelcontextprotocol.io/specification/2025-11-25/basic/index#_meta

"Implementations SHOULD use reverse DNS notation (e.g., com.example/ rather than example.com/)."

Will this be a consistency problem? We have a strictly defined _meta on the root level, but then we also have _meta on tool, prompt and resource level, where the MCP spec isn't as prescriptive.

How do you see this fitting together @ognis1205 ?

[ognis1205]

Thank you for the review @Fannon !

From the MCP Protocol spec, it's less strict, more of a recommendation. Also not sure it mentiones the key name after the reverse domain: https://modelcontextprotocol.io/specification/2025-11-25/basic/index#_meta

"Implementations SHOULD use reverse DNS notation (e.g., com.example/ rather than example.com/)."

Good catch, thanks for sharing the reference!

Will this be a consistency problem? We have a strictly defined _meta on the root level, but then we also have _meta on tool, prompt and resource level, where the MCP spec isn't as prescriptive.
How do you see this fitting together @ognis1205 ?

Regarding this point, I re-read the shared documents and the MCP core spec schema definitions.
If I understand them correctly, the way restrictions around the _meta field are described at the root, tool, prompt, and resource levels appears to be internally consistent in the current documentation.

On the other hand, as you pointed out, there is a potential concern about inconsistency specifically around how _meta is specified in server.json. This is just my personal view, but my current thinking is:

• With the current wording, I do see a potential consistency issue in how reverse-DNS namespacing is described between the MCP core specification and the registry specification.
• The registry server.json specification should generally align with and respect the MCP core specification.
• For fields in the registry spec that relates to conventions defined by the MCP core spec, such as _meta, it would make sense for the registry to follow those same conventions, rather than implicitly introducing stricter rules.

My impression is that, even if it isn't stated explicitly in the current server.json documentation, the community is already implicitly applying the MCP core spec conventions to the server.json conventions as well.

Given that assumption, it seems to me that the next step that best maintains both compatibility and consistency would be not to strengthen constraints at the OpenAPI description level, but instead to clearly document _meta as a SHOULD-level convention and expand generic-server-json.md to align any ambiguous field definitions with the MCP core specification.

At least for _meta, aligning the server.json constraints with the MCP core spec does not seem to introduce compatibility issues in practice. Are there any real-world or operational concerns that would make this problematic?

What do you think @Fannon ?

[Fannon]

In my understanding the server.json is more strict and I clearly prefer having this fully specified out. But this strictness may not be able to be enforced on all _meta object levels because the existing metadata extensions don't have to follow the conventions.

So would you on the root level _meta make the MUST requirement to follow the strict requirements? But what about existing root level meta extensions that would not be compatible - are they then dropped? (Not sure this can happen, just thinking out loud).

For _meta extensions on tool, resource, prompt level, I would state SHOULD with the same strict requirements of the root, but it can only be SHOULD and would lead to validation warnings, not errors / rejection.

[tadasant]

FWIW I have been focusing the iterations on modelcontextprotocol/modelcontextprotocol#2127 rather than updating Registry docs for now. There are other omissions that I think we will need to bring up to speed on the Registry side (for example $schema) after that SEP lands. And I think it'd be more efficient to just focus on landing that (while using Registry docs as reference and only making deliberate changes).

Also maybe relevant to this discussion (clarifying intent around core spec's _meta): modelcontextprotocol/modelcontextprotocol#1788

Generally on this PR: I had always just assumed "reverse DNS" essentially implied that subdomains were OK. I don't think this is the only way to ensure "uniqueness", in that the path after the prefix can also be used to make a name unique. I don't mind adding some additional language, but curious what's motivating the change? Is it ambiguous somehow otherwise?