From 192fbc092b1f1ef4222e86c7e34acfec407b25cf Mon Sep 17 00:00:00 2001 From: tadasant <3900899+tadasant@users.noreply.github.com> Date: Wed, 9 Jul 2025 11:17:01 -0700 Subject: [PATCH 1/4] Restructure docs --- docs/faq.md | 8 ++++++++ docs/server-registry-api/README.md | 14 ++++++++++++++ docs/{ => server-registry-api}/api_examples.md | 0 .../official-registry-openapi.yaml | 0 docs/{ => server-registry-api}/openapi.yaml | 0 5 files changed, 22 insertions(+) create mode 100644 docs/server-registry-api/README.md rename docs/{ => server-registry-api}/api_examples.md (100%) create mode 100644 docs/server-registry-api/official-registry-openapi.yaml rename docs/{ => server-registry-api}/openapi.yaml (100%) diff --git a/docs/faq.md b/docs/faq.md index 8f44e06bb..0fd6cc429 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -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. diff --git a/docs/server-registry-api/README.md b/docs/server-registry-api/README.md new file mode 100644 index 000000000..7e8285ba6 --- /dev/null +++ b/docs/server-registry-api/README.md @@ -0,0 +1,14 @@ +# Registry API + +There are a variety of use cases where an MCP Server Registry API is useful to the MCP ecosystem. At least the following: +- Implementation of a centralized, publicly available catalog of all publicly accessible MCP server implementations +- Implementation of a private catalog of MCP server implementations exclusively accessible by a specific group of people (e.g. a single enterprise) + +These scenarios would benefit from a standard "MCP server registry API" specification that they could potentially compose, as well as share resources (like SDK implementations). + +The centralized, publicly available catalog ("Official MCP Registry") needs additional constraints that need not apply to the broader "MCP server registry API" + +References: +- [openapi.yaml](./openapi.yaml) - A reusable API specification (MCP Server Registry API) that anyone building any sort of "MCP server registry" should consider adopting / aligning with. +- [api_examples.md](./api_examples.md) - Example manifestations of the OpenAPI specification +- [official-registry-openapi.ayml](./official-registry-openapi.yaml) - The specification backing the Official MCP Registry; a derivative of the MCP Server Registry API specification. \ No newline at end of file diff --git a/docs/api_examples.md b/docs/server-registry-api/api_examples.md similarity index 100% rename from docs/api_examples.md rename to docs/server-registry-api/api_examples.md diff --git a/docs/server-registry-api/official-registry-openapi.yaml b/docs/server-registry-api/official-registry-openapi.yaml new file mode 100644 index 000000000..e69de29bb diff --git a/docs/openapi.yaml b/docs/server-registry-api/openapi.yaml similarity index 100% rename from docs/openapi.yaml rename to docs/server-registry-api/openapi.yaml From cdd5edf932e3a981948b6a69ae25341bf79a7018 Mon Sep 17 00:00:00 2001 From: tadasant <3900899+tadasant@users.noreply.github.com> Date: Wed, 9 Jul 2025 11:36:28 -0700 Subject: [PATCH 2/4] Naming relationships --- docs/server-registry-api/README.md | 2 +- .../{api_examples.md => examples.md} | 0 .../official-registry-openapi.yaml | 34 +++++++++++++++++++ docs/server-registry-api/openapi.yaml | 16 ++------- 4 files changed, 38 insertions(+), 14 deletions(-) rename docs/server-registry-api/{api_examples.md => examples.md} (100%) diff --git a/docs/server-registry-api/README.md b/docs/server-registry-api/README.md index 7e8285ba6..f95135120 100644 --- a/docs/server-registry-api/README.md +++ b/docs/server-registry-api/README.md @@ -10,5 +10,5 @@ The centralized, publicly available catalog ("Official MCP Registry") needs addi References: - [openapi.yaml](./openapi.yaml) - A reusable API specification (MCP Server Registry API) that anyone building any sort of "MCP server registry" should consider adopting / aligning with. -- [api_examples.md](./api_examples.md) - Example manifestations of the OpenAPI specification +- [examples.md](./api_examples.md) - Example manifestations of the OpenAPI specification - [official-registry-openapi.ayml](./official-registry-openapi.yaml) - The specification backing the Official MCP Registry; a derivative of the MCP Server Registry API specification. \ No newline at end of file diff --git a/docs/server-registry-api/api_examples.md b/docs/server-registry-api/examples.md similarity index 100% rename from docs/server-registry-api/api_examples.md rename to docs/server-registry-api/examples.md diff --git a/docs/server-registry-api/official-registry-openapi.yaml b/docs/server-registry-api/official-registry-openapi.yaml index e69de29bb..5fb4da2eb 100644 --- a/docs/server-registry-api/official-registry-openapi.yaml +++ b/docs/server-registry-api/official-registry-openapi.yaml @@ -0,0 +1,34 @@ +openapi: 3.1.0 +jsonSchemaDialect: "https://json-schema.org/draft/2020-12/schema" +info: + title: Official MCP Registry API + summary: Official API for discovering and accessing MCP servers metadata with registry constraints + description: | + Extends the base MCP Server Registry API with additional constraints for the official registry and adding additional functionality. + The Official Registry allows server creators to publish and maintain metadata about their servers in a standardized format. + The read side of the API enables MCP client applications and "server aggregator" type consumers to discover and install MCP servers. + version: 0.0.1 + contact: + name: MCP Community Working Group + license: + name: MIT + identifier: MIT +servers: + - url: https://registry.modelcontextprotocol.io/api/v0 + description: Official MCP Registry + +paths: + /servers: + $ref: 'https://modelcontextprotocol.io/schemas/draft/2025-07-09/server-registry-openapi#/paths/~1v0~1servers' + /servers/{id}: + $ref: 'https://modelcontextprotocol.io/schemas/draft/2025-07-09/server-registry-openapi#/paths/~1v0~1servers~1{id}' + +components: + schemas: + Package: + allOf: + - $ref: 'https://modelcontextprotocol.io/schemas/draft/2025-07-09/server-registry-openapi#/components/schemas/Package' + - type: object + properties: + registry_name: + enum: [npm, docker, pypi, nuget] \ No newline at end of file diff --git a/docs/server-registry-api/openapi.yaml b/docs/server-registry-api/openapi.yaml index 0507114a7..351868b31 100644 --- a/docs/server-registry-api/openapi.yaml +++ b/docs/server-registry-api/openapi.yaml @@ -1,23 +1,14 @@ openapi: 3.1.0 jsonSchemaDialect: "https://json-schema.org/draft/2020-12/schema" +$id: https://modelcontextprotocol.io/schemas/draft/2025-07-09/server-registry-openapi info: title: MCP Server Registry API - summary: API for discovering and accessing MCP servers metadata + summary: API for discovering and accessing MCP server metadata description: | - REST API that centralizes metadata about publicly available MCP servers by allowing server creators to submit - and maintain metadata about their servers in a standardized format. This API enables MCP client - applications and "server aggregator" type consumers to discover and install MCP servers. - version: 0.0.1 - contact: - name: MCP Community Working Group + Specification for a theoretical REST API that serves up metadata about MCP servers. license: name: MIT identifier: MIT -servers: - # TODO: Still think a unique name would be better; maybe we open a public discussion on the topic and let people submit ideas? - - url: https://registry.modelcontextprotocol.io - description: MCP Server Registry -# TODO: Webhooks here would be interesting, but out of scope for MVP paths: /v0/servers: @@ -174,7 +165,6 @@ components: properties: registry_name: type: string - enum: [npm, docker, pypi, homebrew, nuget] description: Package registry type example: "npm" name: From 3e3882c7b86ab06ca774b24dcd330c7e1ab80b3b Mon Sep 17 00:00:00 2001 From: tadasant <3900899+tadasant@users.noreply.github.com> Date: Wed, 9 Jul 2025 11:51:09 -0700 Subject: [PATCH 3/4] Final spec --- .../official-registry-openapi.yaml | 32 +++++++++++++++++-- docs/server-registry-api/openapi.yaml | 20 ++---------- 2 files changed, 32 insertions(+), 20 deletions(-) diff --git a/docs/server-registry-api/official-registry-openapi.yaml b/docs/server-registry-api/official-registry-openapi.yaml index 5fb4da2eb..63d60da53 100644 --- a/docs/server-registry-api/official-registry-openapi.yaml +++ b/docs/server-registry-api/official-registry-openapi.yaml @@ -19,16 +19,42 @@ servers: paths: /servers: - $ref: 'https://modelcontextprotocol.io/schemas/draft/2025-07-09/server-registry-openapi#/paths/~1v0~1servers' + $ref: 'https://modelcontextprotocol.io/schemas/draft/2025-07-09/server-registry-openapi#/paths/~1servers' /servers/{id}: - $ref: 'https://modelcontextprotocol.io/schemas/draft/2025-07-09/server-registry-openapi#/paths/~1v0~1servers~1{id}' + $ref: 'https://modelcontextprotocol.io/schemas/draft/2025-07-09/server-registry-openapi#/paths/~1servers~1{id}' components: schemas: + Repository: + allOf: + - $ref: 'https://modelcontextprotocol.io/schemas/draft/2025-07-09/server-registry-openapi#/components/schemas/Repository' + - type: object + properties: + source: + enum: [github] + Package: allOf: - $ref: 'https://modelcontextprotocol.io/schemas/draft/2025-07-09/server-registry-openapi#/components/schemas/Package' - type: object properties: registry_name: - enum: [npm, docker, pypi, nuget] \ No newline at end of file + enum: [npm, docker, pypi, nuget] + + VersionDetail: + allOf: + - $ref: 'https://modelcontextprotocol.io/schemas/draft/2025-07-09/server-registry-openapi#/components/schemas/VersionDetail' + - type: object + required: + - release_date + - is_latest + properties: + release_date: + type: string + format: date-time + example: "2023-06-15T10:30:00Z" + description: Datetime that the MCP server version was published to the registry. + is_latest: + type: boolean + example: true + description: Whether the MCP server version is the latest version available in the registry. \ No newline at end of file diff --git a/docs/server-registry-api/openapi.yaml b/docs/server-registry-api/openapi.yaml index 351868b31..ff0206379 100644 --- a/docs/server-registry-api/openapi.yaml +++ b/docs/server-registry-api/openapi.yaml @@ -11,18 +11,16 @@ info: identifier: MIT paths: - /v0/servers: + /servers: get: summary: List MCP servers description: Returns a list of all registered MCP servers parameters: - name: limit in: query - description: Number of results per page (maximum 5000) + description: Number of results per page schema: type: integer - default: 5000 - maximum: 5000 minimum: 1 - name: offset in: query @@ -38,7 +36,7 @@ paths: application/json: schema: $ref: '#/components/schemas/ServerList' - /v0/servers/{id}: + /servers/{id}: get: summary: Get MCP server details description: Returns detailed information about a specific MCP server @@ -87,7 +85,6 @@ components: example: "https://github.com/modelcontextprotocol/servers" source: type: string - enum: [github, gitlab] # TODO: Add all supported sources as a whitelist example: "github" id: type: string @@ -121,22 +118,11 @@ components: type: object required: - version - - release_date - - is_latest properties: version: type: string example: "1.0.2" description: Equivalent of Implementation.version in MCP specification. - release_date: - type: string - format: date-time - example: "2023-06-15T10:30:00Z" - description: Datetime that the MCP server version was published to the registry. - is_latest: - type: boolean - example: true - description: Whether the MCP server version is the latest version available in the registry. ServerList: type: object From c8d98e9dd5d40b84b651ef2d634a00636fc5f049 Mon Sep 17 00:00:00 2001 From: tadasant <3900899+tadasant@users.noreply.github.com> Date: Wed, 9 Jul 2025 15:56:53 -0700 Subject: [PATCH 4/4] Unwind VersionDetail --- .../official-registry-openapi.yaml | 18 ------------------ docs/server-registry-api/openapi.yaml | 11 +++++++++++ 2 files changed, 11 insertions(+), 18 deletions(-) diff --git a/docs/server-registry-api/official-registry-openapi.yaml b/docs/server-registry-api/official-registry-openapi.yaml index 63d60da53..bb08974a5 100644 --- a/docs/server-registry-api/official-registry-openapi.yaml +++ b/docs/server-registry-api/official-registry-openapi.yaml @@ -40,21 +40,3 @@ components: properties: registry_name: enum: [npm, docker, pypi, nuget] - - VersionDetail: - allOf: - - $ref: 'https://modelcontextprotocol.io/schemas/draft/2025-07-09/server-registry-openapi#/components/schemas/VersionDetail' - - type: object - required: - - release_date - - is_latest - properties: - release_date: - type: string - format: date-time - example: "2023-06-15T10:30:00Z" - description: Datetime that the MCP server version was published to the registry. - is_latest: - type: boolean - example: true - description: Whether the MCP server version is the latest version available in the registry. \ No newline at end of file diff --git a/docs/server-registry-api/openapi.yaml b/docs/server-registry-api/openapi.yaml index ff0206379..46dc5ebbc 100644 --- a/docs/server-registry-api/openapi.yaml +++ b/docs/server-registry-api/openapi.yaml @@ -118,11 +118,22 @@ components: type: object required: - version + - release_date + - is_latest properties: version: type: string example: "1.0.2" description: Equivalent of Implementation.version in MCP specification. + release_date: + type: string + format: date-time + example: "2023-06-15T10:30:00Z" + description: Datetime that the MCP server version was published to the registry. + is_latest: + type: boolean + example: true + description: Whether the MCP server version is the latest version available in the registry. ServerList: type: object