From c106e691ad3246a73001479aeb1e65249ee5af11 Mon Sep 17 00:00:00 2001
From: Adam Jones <adamj+git@anthropic.com>
Date: Mon, 17 Nov 2025 17:11:50 +0000
Subject: [PATCH] Add registry extensions specification

Introduces a standardized way for registries to provide experimental or
community-driven features without committing them to the core API. Extensions
live under /v0/x/<namespace>/<extension> and follow simple conventions around
REST, JSON responses, pagination, and auth.

This enables experimentation with features like search and MCP server
integration while keeping the core API minimal and stable.

Fixes #776
---
 docs/reference/api/extensions.md | 70 ++++++++++++++++++++++++++++++++
 1 file changed, 70 insertions(+)
 create mode 100644 docs/reference/api/extensions.md

diff --git a/docs/reference/api/extensions.md b/docs/reference/api/extensions.md
new file mode 100644
index 00000000..9340a16d
--- /dev/null
+++ b/docs/reference/api/extensions.md
@@ -0,0 +1,70 @@
+# Registry Extensions Specification
+
+A standardized way for registries to provide experimental or community-driven features without committing them to the core API specification.
+
+## Motivation
+
+[The core generic registry API](./generic-registry-api.md) intentionally stays minimal to ensure stability and broad adoption. Extensions provide a path for:
+
+- **Experimentation**: Try new features without core API changes
+- **Community innovation**: Anyone can implement custom extensions
+- **Gradual adoption**: Popular extensions may inform future core API features
+- **Avoiding breaking changes**: Failed experiments can be deprecated without API versioning churn
+
+## URL Structure
+
+Extensions live under the `/v0/x/` prefix:
+
+```
+/v0/x/<namespace>/<extension>[/<path>]
+```
+
+**Components:**
+- `<namespace>`: Reverse domain ownership (e.g., `com.example`, `io.github.username`)
+- `<extension>`: Extension name (lowercase, hyphens for word separation)
+- `<path>`: Extension-specific path structure (optional)
+
+**Examples:**
+```
+/v0/x/com.example/search?q=database
+/v0/x/com.example/stats
+/v0/x/io.github.username/custom-feature
+```
+
+## Conventions
+
+Where possible:
+- Follow standard REST conventions, return simple JSON responses, and avoid special headers
+- For list endpoints, use cursor-based pagination matching the core API
+- Extensions requiring authentication **SHOULD** follow the [Registry Authorization Specification](./registry-authorization.md)
+- Build open-source implementations in a composable way on top of the core APIs (e.g. as opposed to via custom database integration)
+
+## Implementation Requirements
+
+Registries implementing extensions **SHOULD** namespace extensions properly to avoid conflicts.
+
+Clients consuming extensions **MUST** gracefully handle missing extensions.
+
+## Example
+
+A simple server stats extension:
+
+```bash
+GET /v0/x/com.example/stats
+```
+
+```json
+{
+  "totalServers": 1234,
+  "totalVersions": 5678,
+  "recentPublishes": 42
+}
+```
+
+## Future Considerations
+
+- **Extension discovery**: A potential `/v0/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))
+  - MCP server extension to expose the registry itself as an MCP server for programmatic access ([#24](https://github.com/modelcontextprotocol/registry/issues/24))