From ca6912cded5dc293cf292c20183f75e1f282b323 Mon Sep 17 00:00:00 2001
From: adam jones <adamj+git@anthropic.com>
Date: Fri, 5 Dec 2025 15:38:51 +0000
Subject: [PATCH] Add registry extensions specification (#777)

Introduces a standardized way for registries to provide experimental or
community-driven features without committing them to the core API
specification.

## Summary

- Extensions live under `/v0/x/<namespace>/<extension>` URL structure
- Simple conventions: REST, JSON responses, cursor pagination, optional
auth
- Composable design building on core APIs where possible

This enables experimentation with features like search (#389) and MCP
server integration (#24) 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 0000000..9340a16
--- /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))