Repository navigation
Plan for schema version changes in the ServerDetail model #139
Description
Activity
Idea: do we want to add a
$schemaproperty, which has a value likehttps://registry.modelcontextprotocol.io/schemas/2025-08-20/server.json. Then if we do make breaking changes, we can have a new valuehttps://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.
v0andv1, 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)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.jsonthat is included in the template for NuGet MCP servers includes the$schemaURI matching the$idin the schema:
https://github.com/dotnet/extensions/blob/77859cb87c33bcda7187871a683c5779557cb2ef/src/ProjectTemplates/Microsoft.Extensions.AI.Templates/src/McpServer/McpServer-CSharp/.mcp/server.json#L2registry/docs/server-json/schema.json
Line 3 in 12ab632
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!Ah nice, I hadn't seen that thread. Seems like we're aligned on using JSON schema and maybe adding
$schemato 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 athttps://modelcontextprotocol.io/schemas/draft/2025-07-09/server.jsonis 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.iopoints 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.iopoints at a GKE cluster that is fully controlled by this (the registry) repo, in thedeployfolder. 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
deployfolder, 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.
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
Reacted by Joel Verhagen, adam jones and Jonathan HefnerFor 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.iois 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.ioso 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.
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).
I think I could get this spun up easily if we're happy with this?
Or an even more generic domain like
static.modelcontextprotocol.iowhere the MVP is just just GitHub Pages serving a GitHub repo we can put files in.@tadasant @joelverhagen would you be happy to vote on:
- registry.modelcontextprotocol.io
- schema.modelcontextprotocol.io
- static.modelcontextprotocol.io
- put the effort in to get it on root modelcontextprotocol.io
- other proposed domain
(personally my preference would be for 3, then 2. mainly because I imagine there might be other random static assets we want to host, and having a general static files host seems useful so maybe we should name it that way from the start.)
To experiment a bit more, I tried uploading some static files to mintlify and it seems like it does process at least .txt files. It does seem to apply transforms/do weird things to HTML and CSS though, so don't know if it'll do the same for JSON.
This makes me a bit more optimistic for hosting on the root domain. Although I'm still maybe leaning to just having a simple static assets host that we put these schema files on.
I think
static.modelcontextprotocol.iomakes sense, though I might run that by the wider contributor Discord community to gather some opinions before making the jump.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 think pre-go-live, we should keep them separate. However when we propose a SEP to enshrine server.json as the thing being used in a lot of places (including, for example, InitializeResult), we may have strong incentive to keep everything aligned and keep it in lockstep with the core MCP spec. Hopefully by then server.json is relatively stable and that's not really a problem.
I might run that by the wider contributor Discord community
Sounds like a good idea! Have posted in https://discord.com/channels/1358869848138059966/1358869848138059969/1408161807549333790
Based on the discussion in this issue so far, and the chat we had in the maintainers meeting today we are agreed on the approach above. Moving to tech requirements work to figure out which domain exactly we host the schema on (likely will agree on this in next 24 hours), then should be good to head on to implementation work soon :)
From Discord:
Adam Jones (Anthropic) — 8/21/25, 7:52 PM
Static Hosting Domain for MCP AssetsOn the registry project, we're keen to set up a domain to host static files for the MCP ecosystem, starting with the server.json JSON schema. This came up in registry issue #139.
Why we want public hosting:
JSON schemas use a $schema property that points to a URL - when this URL is actually accessible, IDEs automatically provide type hinting, validation, and autocomplete
Makes server.json files self-describing - anyone finding one immediately knows what spec it follows
Enables tooling to discover and validate MCP server definitions across the internetCurrent proposal:
Host at static.modelcontextprotocol.io as a general-purpose static asset host for MCP:
Start with the server.json schema at something like /schemas/2025-08-20/server.json
Available for other MCP static assets the community might need
Initially start by just creating a GitHub repo, that is served via GitHub pagesLooking for input:
Do you have preferences on the subdomain? E.g.: static., cdn., schemas., registry.
We considered just putting it on registry, but prefer a generic name so this can be used for other things. We imagine a static file serving domain is probably generally useful.
Are there other static files/assets the MCP ecosystem needs hosted?
Any concerns about this approach?
Jonathan Hefner — 8/21/25, 8:49 PM
At first glance, I liked the simple generality of static.. But, for $schema values that might be replicated across tens or hundreds of thousands of user's files, I think I would prefer a URL that looks more dedicated to the purpose, so schemas. (or schema.) would be my choice.I think cdn. is worse than static. in that regard. I think registry. would be okay, but might preclude other use cases.
David Soria Parra (Anthropic) — 8/22/25, 7:29 AM
static. is fine unless it's specifically only for the registry, in which case it probably should live under registry.
Jonathan Hefner — 8/22/25, 4:22 PM
I don't feel strongly about it, but if we are looking for precedents, here are some search results from GitHub:/"$schema": "https?://static/: 546 files
/"$schema": "https?://schema/: 408k files
/"$schema": "https?://schemas?.[^m]/ (excludes schema.management.azure.com): 86.5k filesI think I am leaning towards just using
static: I can really imagine wanting basic file hosting for other MCP stuff in the future.I think it's mostly ~fine that
statichas less use thanschemaon GitHub for JSON schemas specifically, and also obvious enough that$schemais the schema property withoutschemabeing the beginning of the URL as well.I will get a repository and the DNS set up for this.
- added a commit that references this issue
on Aug 26, 2025 - added a commit that references this issue
on Aug 27, 2025
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.jsonrequest body provided to the/v0/publishendpoint 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.1in theContent-Type(many options).Given this is
v0of 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/publishshape 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.jsonschema 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 :)