From e5659f1a19993ebf990c237bd0825c5466305959 Mon Sep 17 00:00:00 2001 From: tadasant <3900899+tadasant@users.noreply.github.com> Date: Mon, 1 Dec 2025 15:49:07 -0800 Subject: [PATCH 1/5] Update OpenAPI spec to use v0.1 endpoints and bump version to 2025-12-01 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Update all API endpoint paths from /v0/ to /v0.1/ - Bump schema version from 2025-10-17 to 2025-12-01 - Regenerate server.schema.json with updated version This ensures sub-registries implementing the spec are adhering to the stable v0.1 version rather than the unstable v0. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- docs/reference/api/openapi.yaml | 14 +++++++------- docs/reference/server-json/server.schema.json | 4 ++-- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/reference/api/openapi.yaml b/docs/reference/api/openapi.yaml index 1e8a842a..ff9cd6aa 100644 --- a/docs/reference/api/openapi.yaml +++ b/docs/reference/api/openapi.yaml @@ -1,9 +1,9 @@ openapi: 3.1.0 jsonSchemaDialect: "https://json-schema.org/draft/2020-12/schema" -$id: https://modelcontextprotocol.io/schemas/draft/2025-10-17/server-registry-openapi +$id: https://modelcontextprotocol.io/schemas/draft/2025-12-01/server-registry-openapi info: title: MCP Server Registry API - version: "2025-10-17" + version: "2025-12-01" summary: API for discovering and accessing MCP server metadata description: | Specification for a theoretical REST API that serves up metadata about MCP servers. @@ -18,7 +18,7 @@ tags: description: Operations for publishing MCP servers to the registry paths: - /v0/servers: + /v0.1/servers: get: tags: [servers] summary: List MCP servers @@ -68,7 +68,7 @@ paths: application/json: schema: $ref: '#/components/schemas/ServerList' - /v0/servers/{serverName}/versions: + /v0.1/servers/{serverName}/versions: get: tags: [servers] summary: List all versions of an MCP server @@ -98,7 +98,7 @@ paths: error: type: string example: "Server not found" - /v0/servers/{serverName}/versions/{version}: + /v0.1/servers/{serverName}/versions/{version}: get: tags: [servers] summary: Get specific MCP server version @@ -218,7 +218,7 @@ paths: error: type: string example: "Deletion is not supported by this registry" - /v0/publish: + /v0.1/publish: post: tags: [publish] summary: Publish MCP server (Optional) @@ -709,7 +709,7 @@ components: type: string format: uri description: JSON Schema URI for this server.json format - example: "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json" + example: "https://static.modelcontextprotocol.io/schemas/2025-12-01/server.schema.json" packages: type: array items: diff --git a/docs/reference/server-json/server.schema.json b/docs/reference/server-json/server.schema.json index 59967b5a..73a248f6 100644 --- a/docs/reference/server-json/server.schema.json +++ b/docs/reference/server-json/server.schema.json @@ -1,6 +1,6 @@ { "$comment": "This file is auto-generated from docs/reference/api/openapi.yaml. Do not edit manually. Run 'make generate-schema' to update.", - "$id": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json", + "$id": "https://static.modelcontextprotocol.io/schemas/2025-12-01/server.schema.json", "$ref": "#/definitions/ServerDetail", "$schema": "http://json-schema.org/draft-07/schema#", "definitions": { @@ -373,7 +373,7 @@ "properties": { "$schema": { "description": "JSON Schema URI for this server.json format", - "example": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json", + "example": "https://static.modelcontextprotocol.io/schemas/2025-12-01/server.schema.json", "format": "uri", "type": "string" }, From 8dd7807577b77ae724ba4f57eda41f35cb3d4b47 Mon Sep 17 00:00:00 2001 From: tadasant <3900899+tadasant@users.noreply.github.com> Date: Mon, 1 Dec 2025 15:56:17 -0800 Subject: [PATCH 2/5] Keep $schema example pointing to current supported version (2025-10-17) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The OpenAPI spec version (2025-12-01) is separate from the server.json $schema version that the backend validates. The example should continue to point to 2025-10-17 which is the currently supported schema version. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- docs/reference/api/openapi.yaml | 2 +- docs/reference/server-json/server.schema.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/api/openapi.yaml b/docs/reference/api/openapi.yaml index ff9cd6aa..7267a4e1 100644 --- a/docs/reference/api/openapi.yaml +++ b/docs/reference/api/openapi.yaml @@ -709,7 +709,7 @@ components: type: string format: uri description: JSON Schema URI for this server.json format - example: "https://static.modelcontextprotocol.io/schemas/2025-12-01/server.schema.json" + example: "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json" packages: type: array items: diff --git a/docs/reference/server-json/server.schema.json b/docs/reference/server-json/server.schema.json index 73a248f6..4d8b1379 100644 --- a/docs/reference/server-json/server.schema.json +++ b/docs/reference/server-json/server.schema.json @@ -373,7 +373,7 @@ "properties": { "$schema": { "description": "JSON Schema URI for this server.json format", - "example": "https://static.modelcontextprotocol.io/schemas/2025-12-01/server.schema.json", + "example": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json", "format": "uri", "type": "string" }, From ea03e8576014480c307fd968839ddd4c12073474 Mon Sep 17 00:00:00 2001 From: tadasant <3900899+tadasant@users.noreply.github.com> Date: Mon, 1 Dec 2025 16:22:51 -0800 Subject: [PATCH 3/5] Revert server.schema.json changes - let PR #803 handle schema versioning MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PR #803 decouples server.schema.json versioning from openapi.yaml by using a draft URL scheme. This PR should only update the OpenAPI spec endpoints and version, not the server.schema.json. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- docs/reference/server-json/server.schema.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/server-json/server.schema.json b/docs/reference/server-json/server.schema.json index 4d8b1379..59967b5a 100644 --- a/docs/reference/server-json/server.schema.json +++ b/docs/reference/server-json/server.schema.json @@ -1,6 +1,6 @@ { "$comment": "This file is auto-generated from docs/reference/api/openapi.yaml. Do not edit manually. Run 'make generate-schema' to update.", - "$id": "https://static.modelcontextprotocol.io/schemas/2025-12-01/server.schema.json", + "$id": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json", "$ref": "#/definitions/ServerDetail", "$schema": "http://json-schema.org/draft-07/schema#", "definitions": { From 6f0a238be55c6a83c031b08d4dfe21618b55f960 Mon Sep 17 00:00:00 2001 From: tadasant <3900899+tadasant@users.noreply.github.com> Date: Tue, 2 Dec 2025 20:16:22 -0800 Subject: [PATCH 4/5] Make _meta field optional in ServerResponse MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The _meta field and its io.modelcontextprotocol.registry/official extension were never intended to be required parts of the spec. Sub-registries may not use these fields, so they should be optional. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- docs/reference/api/openapi.yaml | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/reference/api/openapi.yaml b/docs/reference/api/openapi.yaml index 7267a4e1..a76bf77f 100644 --- a/docs/reference/api/openapi.yaml +++ b/docs/reference/api/openapi.yaml @@ -741,7 +741,6 @@ components: type: object required: - server - - _meta properties: server: $ref: '#/components/schemas/ServerDetail' From 902dfb5617f58f88c4b35b55f77d3772d53f645c Mon Sep 17 00:00:00 2001 From: tadasant <3900899+tadasant@users.noreply.github.com> Date: Fri, 5 Dec 2025 14:15:52 -0800 Subject: [PATCH 5/5] Update extensions.md to use /v0.1/ endpoints MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Update all API endpoint paths from /v0/ to /v0.1/ in the extensions specification, consistent with the rest of the API documentation. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- docs/reference/api/extensions.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/reference/api/extensions.md b/docs/reference/api/extensions.md index 9340a16d..8f7bcbce 100644 --- a/docs/reference/api/extensions.md +++ b/docs/reference/api/extensions.md @@ -13,10 +13,10 @@ A standardized way for registries to provide experimental or community-driven fe ## URL Structure -Extensions live under the `/v0/x/` prefix: +Extensions live under the `/v0.1/x/` prefix: ``` -/v0/x//[/] +/v0.1/x//[/] ``` **Components:** @@ -26,9 +26,9 @@ Extensions live under the `/v0/x/` prefix: **Examples:** ``` -/v0/x/com.example/search?q=database -/v0/x/com.example/stats -/v0/x/io.github.username/custom-feature +/v0.1/x/com.example/search?q=database +/v0.1/x/com.example/stats +/v0.1/x/io.github.username/custom-feature ``` ## Conventions @@ -50,7 +50,7 @@ Clients consuming extensions **MUST** gracefully handle missing extensions. A simple server stats extension: ```bash -GET /v0/x/com.example/stats +GET /v0.1/x/com.example/stats ``` ```json @@ -63,7 +63,7 @@ GET /v0/x/com.example/stats ## Future Considerations -- **Extension discovery**: A potential `/v0/x` endpoint to list available extensions +- **Extension discovery**: A potential `/v0.1/x` endpoint to list available extensions - **Extension metadata**: Standardized metadata format for extension capabilities - **Defining common extensions**: Like semantic conventions from OpenTelemetry, develop common extensions that registries can adopt (possibly under an experimental namespace) - Search extension for free-text search across server metadata ([#389](https://github.com/modelcontextprotocol/registry/issues/389))