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?

[ognis1205]

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.

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.

I agree that the handling of the _meta field should be clearly specified somewhere eventually, and your point makes a lot of sense.

At the same time, my understanding is that the changes in this PR do not introduce a breaking change to the existing conventions, but rather make the intended convention more explicit for the affected part.

Given that, I think it's reasonable to proceed with this PR as-is, and revisit the broader _meta discussion separately in a dedicated thread or follow-up proposal.

[ognis1205]

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).

I agree with that approach. Focusing on landing SEP-2127 first, while using the Registry docs as a reference and limiting changes to deliberate ones, seems like the most efficient way to move forward.

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

Thanks for sharing this! I'll take a look at it as well.

Generally on this PR: I had always just assumed "reverse DNS" essentially implied that subdomains were OK.

I share that understanding as well. What I wanted to highlight here is that "reverse DNS namespacing" isn't strictly defined by any RFC; it's a convention rather than a strictly mechanical transformation.

Because of that, it doesn't always feel obvious how a reverse DNS namespace should be derived from a given domain, and I worry that readers of the spec could reasonably be confused about what is expected.

For example, given api.example.project.com, a purely literal reversal would result in com.project.example.api.
However, a publisher might reasonably decide that only a subset of the domain hierarchy they control should carry semantic meaning for the namespace, and choose com.project.example instead. In practice, conventions like <tld>.<organization>.<project> are also quite common.

So my concern is that simply saying "use reverse DNS namespacing" doesn't make it clear whether this is meant to imply a strict, literal reversal, or whether including only selected subdomain levels is acceptable. The clarification is intended to make that flexibility explicit and reduce potential ambiguity for users reading the spec.

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.

That's fair and to clarify, the uniqueness I'm concerned with here is not the uniqueness of the full name value itself, but the uniqueness of the namespace boundary represented by the reverse DNS portion.

I don't mind adding some additional language, but curious what's motivating the change? Is it ambiguous somehow otherwise?

The motivation for this change comes from the example in the Registry docs:

https://github.com/modelcontextprotocol/registry/blob/main/docs/reference/server-json/generic-server-json.md#remote-server-example

As shown there, the reverse DNS namespacing derived from mcp-fs.anonymous.modelcontextprotocol.io is represented as io.modelcontextprotocol.anonymous rather than the fully literal io.modelcontextprotocol.anonymous.mcp-fs.

This made me feel it would be helpful to explicitly clarify that a strict, literal application of reverse DNS is not required to determine a unique namespace.

[ognis1205]

Thanks for the feedback, @Fannon and @tadasant .

I completely agree that prioritizing SEP-2127 is the most efficient path forward.

Since my point about reverse DNS is mainly to resolve the existing ambiguity in the docs, I'm happy to leave this as a reference or have it integrated into another PR later. If it helps reduce your review overhead, I can close this PR for now and revisit it once the core spec lands.