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

---

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: https://github.com/modelcontextprotocol/registry/issues/90

Fast follows I intend to do before closing that issue:

• Propose a specific versioning scheme (https://github.com/modelcontextprotocol/registry/pull/134/files#r2145287494)
• Add a version to the scheme of server.json itself (https://github.com/modelcontextprotocol/registry/issues/139)

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

• https://github.com/modelcontextprotocol/registry/issues/25
• https://github.com/modelcontextprotocol/registry/issues/105
• https://github.com/modelcontextprotocol/registry/issues/143

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:

• https://github.com/modelcontextprotocol/registry/issues/84
• https://github.com/modelcontextprotocol/registry/issues/94
• https://github.com/modelcontextprotocol/registry/issues/124
• https://github.com/modelcontextprotocol/registry/issues/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]

I think this looks good overall, one comment :)

[tadasant]

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

[tadasant]

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

• https://github.com/modelcontextprotocol/registry/issues/155
• https://github.com/modelcontextprotocol/registry/issues/159