modelcontextprotocol/registry
Watch
1
0
Fork
You've already forked registry
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: Clean up API documentation (#236)

Browse source 
- Move API examples from docs into swagger.yaml
- Align openapi.yaml docs with implementation
This commit is contained in:
adam jones 2025-08-09 18:44:53 +01:00 • committed by GitHub
commit 1821f68360
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
5 changed files with 327 additions and 566 deletions
Download patch file Download diff file Expand all files Collapse all files

2
docs/faq.md
View file

@ -18,7 +18,7 @@ The MCP Registry is the official centralized metadata repository for publicly-ac
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)
- "Official MCP Registry API": The REST API that lives at `https://registry.modelcontextprotocol.io/api`, with an OpenAPI specification defined at [swagger.yaml](../internal/docs/swagger.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?

3
docs/server-registry-api/README.md
View file

@ -10,5 +10,4 @@ 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.
- [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.
- [swagger.yaml](../../internal/docs/swagger.yaml) - The specification backing the Official MCP Registry; a derivative of the MCP Server Registry API specification.

293
docs/server-registry-api/examples.md
View file

@ -1,293 +0,0 @@
# Examples
## /v0/servers
### Request
```http
GET /v0/servers?limit=5000&offset=0
```
### Response
```json
{
"servers": [
{
"id": "a5e8a7f0-d4e4-4a1d-b12f-2896a23fd4f1",
"name": "io.modelcontextprotocol/filesystem",
"description": "Node.js server implementing Model Context Protocol (MCP) for filesystem operations.",
"status": "active",
"repository": {
"url": "https://github.com/modelcontextprotocol/servers",
"source": "github",
"id": "b94b5f7e-c7c6-d760-2c78-a5e9b8a5b8c9"
},
"version_detail": {
"version": "1.0.2",
"release_date": "2023-06-15T10:30:00Z",
"is_latest": true
}
}
],
"next": "https://registry.modelcontextprotocol.io/servers?offset=50",
"total_count": 1
}
```
## /v0/servers/:id
### Request
```http
GET /v0/servers/a5e8a7f0-d4e4-4a1d-b12f-2896a23fd4f1?version=0.0.3
```
### Response
```json
{
"id": "a5e8a7f0-d4e4-4a1d-b12f-2896a23fd4f1",
"name": "io.modelcontextprotocol/filesystem",
"description": "Node.js server implementing Model Context Protocol (MCP) for filesystem operations.",
"status": "active",
"repository": {
"url": "https://github.com/modelcontextprotocol/servers",
"source": "github",
"id": "b94b5f7e-c7c6-d760-2c78-a5e9b8a5b8c9"
},
"version_detail": {
"version": "1.0.2",
"release_date": "2023-06-15T10:30:00Z",
"is_latest": true
},
"packages": [
{
"registry_name": "npm",
"name": "@modelcontextprotocol/server-filesystem",
"version": "1.0.2",
"package_arguments": [
{
"type": "positional",
"value_hint": "target_dir",
"description": "Path to access",
"default": "/Users/username/Desktop",
"is_required": true,
"is_repeated": true
}
],
"environment_variables": [
{
"name": "LOG_LEVEL",
"description": "Logging level (debug, info, warn, error)",
"default": "info"
}
]
},
{
"registry_name": "docker",
"name": "mcp/filesystem",
"version": "1.0.2",
"runtime_arguments": [
{
"type": "named",
"description": "Mount a volume into the container",
"name": "--mount",
"value": "type=bind,src={source_path},dst={target_path}",
"is_required": true,
"is_repeated": true,
"variables": {
"source_path": {
"description": "Source path on host",
"format": "filepath",
"is_required": true
},
"target_path": {
"description": "Path to mount in the container. It should be rooted in `/project` directory.",
"is_required": true,
"default": "/project",
}
}
}
],
"package_arguments": [
{
"type": "positional",
"value_hint": "target_dir",
"value": "/project",
}
],
"environment_variables": [
{
"name": "LOG_LEVEL",
"description": "Logging level (debug, info, warn, error)",
"default": "info"
}
]
}
],
"remotes": [
{
"transport_type": "sse",
"url": "https://mcp-fs.example.com/sse"
}
]
}
```
### Server Configuration Examples
#### Local Server with npx
API Response:
```json
{
"id": "brave-search-12345",
"name": "io.modelcontextprotocol/brave-search",
"description": "MCP server for Brave Search API integration",
"status": "active",
"repository": {
"url": "https://github.com/modelcontextprotocol/servers",
"source": "github",
"id": "abc123de-f456-7890-ghij-klmnopqrstuv"
},
"version_detail": {
"version": "1.0.2",
"release_date": "2023-06-15T10:30:00Z",
"is_latest": true
},
"packages": [
{
"registry_name": "npm",
"name": "@modelcontextprotocol/server-brave-search",
"version": "1.0.2",
"environment_variables": [
{
"name": "BRAVE_API_KEY",
"description": "Brave Search API Key",
"is_required": true,
"is_secret": true
}
]
}
]
}
```
claude_desktop_config.json:
```json
{
"brave-search": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-brave-search"
],
"env": {
"BRAVE_API_KEY": "YOUR_API_KEY_HERE"
}
}
}
```
#### Local Server with Docker
API Response:
```json
{
"id": "filesystem-67890",
"name": "io.modelcontextprotocol/filesystem",
"description": "Node.js server implementing Model Context Protocol (MCP) for filesystem operations",
"status": "active",
"repository": {
"url": "https://github.com/modelcontextprotocol/servers",
"source": "github",
"id": "d94b5f7e-c7c6-d760-2c78-a5e9b8a5b8c9"
},
"version_detail": {
"version": "1.0.2",
"release_date": "2023-06-15T10:30:00Z",
"is_latest": true
},
"packages": [
{
"registry_name": "docker",
"name": "mcp/filesystem",
"version": "1.0.2",
"runtime_arguments": [
{
"type": "named",
"description": "Mount a volume into the container",
"name": "--mount",
"value": "type=bind,src={source_path},dst={target_path}",
"is_required": true,
"is_repeated": true,
"variables": {
"source_path": {
"description": "Source path on host",
"format": "filepath",
"is_required": true
},
"target_path": {
"description": "Path to mount in the container. It should be rooted in `/project` directory.",
"is_required": true,
"default": "/project",
}
}
}
],
"package_arguments": [
{
"type": "positional",
"value_hint": "target_dir",
"value": "/project",
}
]
}
]
}
```
claude_desktop_config.json:
```json
{
"filesystem": {
"server": "@modelcontextprotocol/servers/src/filesystem@1.0.2",
"package": "docker",
"settings": {
"--mount": [
{ "source_path": "/Users/username/Desktop", "target_path": "/project/desktop" },
{ "source_path": "/path/to/other/allowed/dir", "target_path": "/project/other/allowed/dir,ro" },
]
}
}
}
```
#### Remote Server
API Response:
```json
{
"id": "remote-fs-54321",
"name": "Remote Brave Search Server",
"description": "Cloud-hosted MCP Brave Search server",
"status": "active",
"repository": {
"url": "https://github.com/example/remote-fs",
"source": "github",
"id": "xyz789ab-cdef-0123-4567-890ghijklmno"
},
"version_detail": {
"version": "1.0.2",
"release_date": "2023-06-15T10:30:00Z",
"is_latest": true
},
"remotes": [
{
"transport_type": "sse",
"url": "https://mcp-fs.example.com/sse"
}
]
}
```

42
docs/server-registry-api/official-registry-openapi.yaml
View file

@ -1,42 +0,0 @@
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/~1servers'
/servers/{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]

49
docs/server-registry-api/openapi.yaml
View file

@ -16,19 +16,18 @@ paths:
summary: List MCP servers
description: Returns a list of all registered MCP servers
parameters:
- name: cursor
in: query
description: Pagination cursor for retrieving next set of results
required: false
schema:
type: string
- name: limit
in: query
description: Number of results per page
description: Maximum number of items to return
required: false
schema:
type: integer
minimum: 1
- name: offset
in: query
description: Number of results to skip for pagination
schema:
type: integer
default: 0
minimum: 0
responses:
'200':
description: A list of MCP servers
@ -93,7 +92,6 @@ components:
Server:
type: object
required:
- id
- name
- description
- version_detail
@ -101,13 +99,14 @@ components:
id:
type: string
format: uuid
example: "a5e8a7f0-d4e4-4a1d-b12f-2896a23fd4f1"
example: "123e4567-e89b-12d3-a456-426614174000"
name:
type: string
description: Human-readable description of the server's functionality
example: "io.modelcontextprotocol/filesystem"
description: "Reverse DNS name of the MCP server"
example: "io.github.modelcontextprotocol/filesystem"
description:
type: string
description: "Human-readable description of the server's functionality"
example: "Node.js server implementing Model Context Protocol (MCP) for filesystem operations."
status:
type: string
@ -119,6 +118,12 @@ components:
$ref: '#/components/schemas/Repository'
version_detail:
$ref: '#/components/schemas/VersionDetail'
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
VersionDetail:
type: object
@ -145,19 +150,21 @@ components:
type: object
required:
- servers
- total_count
properties:
servers:
type: array
items:
$ref: '#/components/schemas/Server'
next:
type: string
format: uri
example: "https://registry.modelcontextprotocol.io/servers?offset=50"
total_count:
type: integer
example: 1
metadata:
type: object
properties:
next_cursor:
type: string
description: Cursor for next page of results
count:
type: integer
description: Number of items in current page
example: 30
Package:
type: object