From fdcb38537fa08e3392630e38a3d59cac51407b04 Mon Sep 17 00:00:00 2001
From: Tadas Antanavicius <tadas@tadasant.com>
Date: Wed, 10 Dec 2025 13:58:01 -0800
Subject: [PATCH] Update OpenAPI spec to use v0.1 endpoints and make _meta
 optional (#811)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Prepared by Claude Code, reviewed by me.

## Summary
- Update all API endpoint paths from `/v0/` to `/v0.1/` in the OpenAPI
spec
- Bump OpenAPI spec version from `2025-10-17` to `2025-12-01` (in `$id`
and `info.version`)

## Rationale
This ensures sub-registries implementing the spec are adhering to the
stable v0.1 version rather than the unstable v0. The API freeze (v0.1)
provides stability guarantees that sub-registries need.

## Additional cleanup

### Make `_meta` optional in `ServerResponse`

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 registry-specific metadata fields, so
they should be optional.

### Move extensions docs to use /v0.1/ instead of /v0/

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude <noreply@anthropic.com>
---
 docs/reference/api/extensions.md | 14 +++++++-------
 docs/reference/api/openapi.yaml  | 13 ++++++-------
 2 files changed, 13 insertions(+), 14 deletions(-)

diff --git a/docs/reference/api/extensions.md b/docs/reference/api/extensions.md
index 9340a16..8f7bcbc 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/<namespace>/<extension>[/<path>]
+/v0.1/x/<namespace>/<extension>[/<path>]
 ```
 
 **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))
diff --git a/docs/reference/api/openapi.yaml b/docs/reference/api/openapi.yaml
index c85dc42..4794205 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)
@@ -741,7 +741,6 @@ components:
       type: object
       required:
         - server
-        - _meta
       properties:
         server:
           $ref: '#/components/schemas/ServerDetail'