First cut at server.json

[tadasant]

This is a first cut at properly defining the server.json file. We have been working out details of the shape for a while, but to-date it has only been implicitly documented as the OpenAPI response to /servers/:id, which is not an exact definition due to some registry-specific details (like id and is_latest).

Edit: as-written in this PR, this is a more constrained version of server.json that the Registry intends to support at-launch. The broader server.json may have looser constraints, for example no enum constraint on source=github,gitlab. See #155

---

Motivation

There are a variety of use cases where a static representation of an MCP server is necessary:

• Discoverability on a centralized registry (i.e. our official Registry work)
• Discoverability on a decentralized .well-known endpoint
• As a response to an initialization call, so the client knows information about the MCP server to which it is connecting
• As an input into crafting a DXT file
• Packaged in with the source code of an MCP server, so as to have a structured way context

All of these scenarios (and more) would benefit from an agreed-upon, standardized format that makes it easy to port around and maintain a consistent experience for consumers and developers working with the data. At the end of the day, it's all the same data (or a subset of it). MCP server maintainers should have to manage one copy of this file, and all these use cases can serve that file (or a programmatic derivative/subset of it).

Please note: this is different from the file commonly referred to as mcp.json, which is an MCP client's configuration file for running a specific set of MCP servers. See this issue.

In this PR

There is a JSON schema for the file (schema.json) and a set of examples for how some servers might look (examples.md).

This PR does not add any new features/changes that weren't in the codebase already. There are a handful of improvements we can make quickly, but given a bunch of conversations flying about this concept I wanted to get something in place to point to that isn't an OpenAPI spec. I think eventually this spec might do better to live in modelcontextprotocol/modelcontextprotol instead of modelcontextprotocol/registry, but the registry is probably the most heavily dependent piece of work related to it, so may as well keep it here for now.

Relevant Issues

Issue: #90

Fast follows next up:

• Separate out Registry-specific server.json out from generic server.json #155
• Plan for schema version changes in the ServerDetail model #139
• Add a validation script that ensures OpenAPI, example, server.json, examples are all in sync with each other #159

There are definitely some pending in the registry backlog that could impact the shape further. Notably at least:

• OAuth Config (Optional) for Remotes #25
• Automated test suite that covers publication of a range of server formats #105
• Support streamable HTTP via packages #143
• Decide & document server versioning approach for server.json #158

And some later issues that are not blockers for the registry work but maybe other folks will be interested in seeing them incorporated into this shape:

• Include ServerCapabilities in server.json #84
• "Sorting signals" functionality in the API spec #94
• Support an array of commands (multiple commands) to start an MCP server instead of just one #124
• Allow engine or runtime version to be expressed for local MCP servers #125

[tadasant]

cc @joelverhagen @felixrieseberg

[atrawog]

That's quite a sophistication list that's covering almost everything. But the one thing that could be still useful to add is some info about the supported OAuth Identify Provider(s).

Because we are likely going to see a rise of MCP Server with some form of OAuth authentication. Who either require the user to create a user account on a certain website. Or require an OAuth callback configuration from an Identify provider for user identification.

[tadasant]

@atrawog yes, that is in:

And there are definitely some pending in the registry backlog that could impact the shape further. Notably at least:
OAuth Config (Optional) for Remotes #25

I think that would cover what you are describing?

[connor4312]

Can we have a script that auto-gens the overlapping portion of this from the openapi spec or vise versa? The schema is a little involved and I would not want them to accidentally diverge

[tadasant]

Definitely feel that pain: I think I'd rather we have a script that's in CI validating that they are consistent though (e.g. that the OpenAPI spec's /servers/:id returns a shape that is compliant with server.json), rather than literally autogenerate one or the other. Let me know if you feel strongly otherwise

Will add that validation as a third fast follow here

[connor4312]

If we make changes to one or the other, I would prefer not to have to update both YAML and JSON schema to do so. I think a nice autogen story could be good, but we could also go with a validation step and then add that later on if it's a pain point.

[toby]

I think we should be able to use go generate for this, link.

[connor4312]

I think this looks good overall, one comment :)

[jonathanhefner]

🚀

[tadasant]

Addressed feedback and made some simplifications in 8041f5f. Thanks all for taking a look!

[joelverhagen]

Could we add an $id to this JSON schema, ideally pointing to where the this schema hosted (URL & URI), and maybe including a version, such as the date of release (maybe today). This could be included optionally at publish time for improved error experience (other than complaining of some missing property).

[tadasant]

Yes, that's the intent of this fast follow:

Add a version to the scheme of server.json itself (#139)

[joelverhagen]

Is this a description of what the main public registry will support? Or what any MCP registry can support including private ones? It seems to me like this should just be a string and the set of allowed values is enforced by a specific registry implementation.

Asked another way, do you expect this JSON schema to be used by other deployments or just the main one?

[tadasant]

Good question. I guess we're going to need two schemas here, similar to how I was thinking we need to separate out the official vs. broader OpenAPI schemas. As-written, this is moreso the public registry one (e.g. constraints like enum on source don't make sense for the generic server.json).

Added ticket: #155

[tadasant]

@toby or @connor4312 when you get a chance to 👍 we can move this in and then I'll move onto:

• Separate out Registry-specific server.json out from generic server.json #155
• Add a validation script that ensures OpenAPI, example, server.json, examples are all in sync with each other #159