Plan for schema version changes in the ServerDetail model

[joelverhagen]

Is your feature request related to a problem? Please describe.

If I am missing a bigger vision here, feel free to close the issue.

The server.json request body provided to the /v0/publish endpoint is minimally versioned. The shape of the JSON appears to the follow the ServerDetail model and the related model in the OpenAPI YAML.

There appears to be a coupling between the "input" (publish), "output" (get-by-ID), and DB models in the code (ServerDetail).

After the initial launch, I wonder how schema changes will be handled, whether breaking (e.g. property rename) or non-breaking (e.g. new optional property).

Suppose someone publishes a JSON to the registry at the very beginning, then we later introduce a new, required property. The existing JSON in MongoDB will not have the new property but will be returned as-is to the end user (or perhaps break on unmarshal). This could lead to variety on the schema returned to reads of the API.

If the intent is to flow the original schema (as the MCP extension author provided it) to the consumer, then I the current code will work as long as we don't introduce breaking changes.

But what about a property rename? Will a data fix-up/backfill be performed?

Describe the solution you'd like

Without trying to fix the whole schema versioning thing at once I propose a schema version be provided at publish time so the publish code/scripts can express concretely "I am giving you a server detail of version X". The server could reject or map the input if the version differs from what is expected. Or this could be included in MongoDB and used for smarter unmarshal at query/read time.

This schema version could be a root JSON property, a query parameter, or an api-version=0.1 in the Content-Type (many options).

Given this is v0 of the API I think we could allow ourselves to have breaking changes but accept a schema version as input and reject/map old schema versions that could come in to the publish endpoint.

Describe alternatives you've considered

Declare /v0/publish shape will never change (or never have breaking changes) and describe what "non-breaking changes" might look like.

Additional context

I want to describe the current server.json schema version in my NuGet + MCP authoring docs so that it's easy for authors to see that they are using an old docs/template version and to check MCP registry docs for what they need to fix up in their server.json.

In other words, I'm planning for potential schema changes :)

[tadasant]

Yes, we should definitely version this schema. Thanks for flagging and writing this up.

I'm going to close this but reference it here #90 - let's make sure to incorporate as we push that.

[tadasant]

Re-opening as a separate issue since it was more than we needed to squeeze into #90

[domdomegg]

Idea: do we want to add a $schema property, which has a value like https://registry.modelcontextprotocol.io/schemas/2025-08-20/server.json. Then if we do make breaking changes, we can have a new value https://registry.modelcontextprotocol.io/schemas/2028-09-01/server.json.

This would have multiple benefits:

• Makes it very explicit what schema version they are following, in a way that still allows us to add non-breaking changes
• File is now self-describing, so it's easier to crawl on the internet to detect server.json definitions, or in a code repository it's a lot more obvious to contributors what that file is supposed to be / what spec it follows
• Common IDEs get great type hinting, validation, etc. automatically for free
• Over other versioning methods, I think this feels 'nice' that we're using an open standard that is well known and supported by many tools

(the exact versioning could be whatever, e.g. v0 and v1, if people prefer that to date based versioning. I was going date based because I've seen it elsewhere e.g. GitHub and AWS but don't know what's best practice here and don't have a strong opinion)

[joelverhagen]

Tadas and I spoke a bit about versioning here: #167 (comment)
I think date based versioning is good. The JSON schema metaschema uses dates most recently (month, not day, but day seems good to me just in case we have multiple in a month).

Currently, the .mcp/server.json that is included in the template for NuGet MCP servers includes the $schema URI matching the $id in the schema:
https://github.com/dotnet/extensions/blob/77859cb87c33bcda7187871a683c5779557cb2ef/src/ProjectTemplates/Microsoft.Extensions.AI.Templates/src/McpServer/McpServer-CSharp/.mcp/server.json#L2

registry/docs/server-json/schema.json

Line 3 in 12ab632

"$id": "https://modelcontextprotocol.io/schemas/draft/2025-07-09/server.json",

It would be great if this URI was actually a URL so we have the benefit you suggest (hinting from IDEs).

I am not sure who controls modelcontextprotocol.io, but if we could upload the current schema to that location (or change it to a place we can upload) it would light up!

[domdomegg]

Ah nice, I hadn't seen that thread. Seems like we're aligned on using JSON schema and maybe adding $schema to to server.json :)

For what it's worth, I think it might be better to keep the versioning of schema.json separate to the MCP spec? Because I think the MCP version will evolve much more rapidly than we'll make breaking changes in schema.json, and I think the fewer versions clients have to worry about / deal with the better.

I am not sure who controls modelcontextprotocol.io, but if we could upload the current schema to that location (or change it to a place we can upload) it would light up!

tldr: I think hosting it at registry.modelcontextprotocol.io/... might be quite easy. Hosting it at https://modelcontextprotocol.io/schemas/draft/2025-07-09/server.json is probably possible, but more hassle. Not sure which is semantically nicer.

At the moment the domains are owned by Anthropic, but I'm working on the site to transition them to community-based governance. modelcontextprotocol.io points at a Mintlify site that hosts the docs, so it might be a bit painful to host something at a specific path there (but dooable if we setup a reverse proxy with something like nginx etc.).

Currently registry.modelcontextprotocol.io points at a GKE cluster that is fully controlled by this (the registry) repo, in the deploy folder. At the moment just hosts the go registry binary. I see two fairly easy ways to host the spec:

• Add a route to registry to server the json schema. This I think should be a fairly small easy change.
• Add a route in our k8s config in the deploy folder, probably to point to some new container that just hosts schemas using a pathprefix. This can be a single self-contained change that we own in this repo, but is a little more complex.

Semantically I don't know if server.json is a 'part' of registry. At the moment I think it is mainly owned by the registry maintainers and we're developing it in this repo, so maybe yes? But maybe we should be preparing for it to be wider.

Another alternative to all of the above is to host it at something like https://www.schemastore.org/, which Anthropic already hosts some things in like the claude code settings schema, and several other open source projects kinda rely on e.g. tsconfig schema. They can provide codeowners permissions so we could have the MCP maintainers own changes to the file, although it does mean it's slightly more outside the control of the MCP community.

[tadasant]

Just jumping in on this specific note:

Semantically I don't know if server.json is a 'part' of registry. At the moment I think it is mainly owned by the registry maintainers and we're developing it in this repo, so maybe yes? But maybe we should be preparing for it to be wider.

The vision for server.json is up-to-date here: https://github.com/modelcontextprotocol/registry/tree/main/docs/server-json

tl;dr is that yes, Registry is the first use case, but it has several more use cases (some of which I expect to eventually be significantly more important than Registry for the ecosystem). After we feel good about MVP of the shape for the registry, we should submit it as a SEP w/ the registry as an implementation example, and I expect that will bring together a lot of different stakeholders with many opinions, but hopefully by then we'll have kicked the tires enough that we won't need significant changes to get it formalized

[joelverhagen]

For what it's worth, I think it might be better to keep the versioning of schema.json separate to the MCP spec?

Seems reasonable to me. If there is confusion about how the two versions relate, perhaps we could provide a mapping/relationship doc in this repo if the question comes up. My 2c.

Semantically I don't know if server.json is a 'part' of registry. At the moment I think it is mainly owned by the registry maintainers and we're developing it in this repo, so maybe yes? But maybe we should be preparing for it to be wider.

Good question, I don't know. I think one consideration is that the schema is a static asset, universal to all deployments of the MCP registry (private or community) and that it probably should be CDN fronted, perhaps blob store backed. My mental model is the registry.modelcontextprotocol.io is the community instance and less about universal assets for the registry protocol.

I don't know much about schemastore, but I have heard of it and perhaps used it unknowingly in my IDE. It appears one of the main contributors (Mads) is in my org. I'll run this by him.

Switching to another domain makes sense. Perhaps schema.modelcontextprotocol.io so that it can be decoupled from the running community instance (and availability issues therein).

Generally I think it's very nice when schema URIs are also URLs. I have had to explain so many times to teammates why that XML XSD they are looking at has a "broken link it in" (when in reality it is a URI not a URL). It's just highly convenient to have the schema located publicly and followable in any server.json you might be looking at.

If the URI/URL changes I will update the stuff on the NuGet/.NET side.