modelcontextprotocol/registry
Watch
1
0
Fork
You've already forked registry
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Split OpenAPI specs into base and official registry versions (#171)

Browse source 
Closes #149

As noted in the FAQ update here, this is a helpful starting point in
thinking about this:

```
### What is the difference between "Official MCP Registry", "MCP Registry", "MCP registry", "MCP Registry API", etc?

There are four underlying concepts:
- "MCP Server Registry API" (or "MCP Registry API"): The OpenAPI specification defined in [openapi.yaml](./server-registry-api/openapi.yaml). This is a reusable API specification that anyone building any sort of "MCP server registry" should consider adopting / aligning with.
- "Official MCP Registry" (or "MCP Registry"): The application that lives at `https://registry.modelcontextprotocol.io`. This registry currently only catalogs MCP servers, but may be extended in the future to also catalog MCP client/host apps and frameworks.
- "Official MCP Registry API": The REST API that lives at `https://registry.modelcontextprotocol.io/api`, with an OpenAPI specification defined at [official-registry-openapi.yaml](./server-registry-api/official-registry-openapi.yaml)
- "MCP server registry" (or "MCP registry"): A third party, likely commercial, implementation of the MCP Server Registry API or derivative specification.
```

Prior to this PR, we were just treating "MCP Server Registry API" and
"Official MCP Registry API" to be the same thing. They are not the same:
the latter is inherently a more constrained version of the former. A
private deployment of a similar registry need not have constraints like
"the only valid source code repositories are `github` and `gitlab`".

This PR separates out the definitions to match that path forward.

## Notable Changes

### Base OpenAPI spec (`openapi.yaml`)
- Removed official-registry-specific constraints:
  - No maximum limit on `/servers` endpoint
  - No enum constraint on `Repository.source`
  - No enum constraint on `Package.registry_name`
- Removed `/v0` prefix from paths (it's now just baked into the
`official` one's URL prefix)
- Added `$id` for proper schema identification

### Official Registry OpenAPI spec (`official-registry-openapi.yaml`)
- Created as a derivative of the base spec using `$ref`
- Re-adds official-registry-specific constraints:
  - `Repository.source` enum: `[github]`
  - `Package.registry_name` enum: `[npm, docker, pypi, nuget]`

### Documentation updates
- Added `server-registry-api/README.md` explaining the relationship
between specs
- Updated FAQ to clarify terminology
- Reorganized docs structure
This commit is contained in:
Tadas Antanavicius 2025-07-09 17:46:01 -07:00 • committed by GitHub
commit 05422afffb
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 70 additions and 19 deletions
Download patch file Download diff file Expand all files Collapse all files

8
docs/faq.md
View file

@ -13,6 +13,14 @@ The MCP Registry is the official centralized metadata repository for publicly-ac
- Standardized installation and configuration information
- Namespace management through DNS verification
### What is the difference between "Official MCP Registry", "MCP Registry", "MCP registry", "MCP Registry API", etc?
There are four underlying concepts:
- "MCP Server Registry API" (or "MCP Registry API"): The OpenAPI specification defined in [openapi.yaml](./server-registry-api/openapi.yaml). This is a reusable API specification that anyone building any sort of "MCP server registry" should consider adopting / aligning with.
- "Official MCP Registry" (or "MCP Registry"): The application that lives at `https://registry.modelcontextprotocol.io`. This registry currently only catalogs MCP servers, but may be extended in the future to also catalog MCP client/host apps and frameworks.
- "Official MCP Registry API": The REST API that lives at `https://registry.modelcontextprotocol.io/api`, with an OpenAPI specification defined at [official-registry-openapi.yaml](./server-registry-api/official-registry-openapi.yaml)
- "MCP server registry" (or "MCP registry"): A third party, likely commercial, implementation of the MCP Server Registry API or derivative specification.
### Is the MCP Registry a package registry?
No. The MCP Registry stores metadata about MCP servers and references to where they're hosted (npm, PyPI, NuGet, Docker Hub, etc.), but does not host the actual source code or packages.