Skip to content

docs: update API endpoint documentation from /v0/ to /v0.1/ #802

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+25 −25
Open

docs: update API endpoint documentation from /v0/ to /v0.1/ #802

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions docs/design/tech-architecture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -177,7 +177,7 @@ sequenceDiagram
Admin->>CLI: Request admin token
CLI->>GCP: gcloud auth print-identity-token --audiences=mcp-registry
GCP-->>CLI: ID Token (with hd: "modelcontextprotocol.io")
CLI->>API: POST /v0/auth/oidc {"oidc_token": "eyJ..."}
CLI->>API: POST /v0.1/auth/oidc {"oidc_token": "eyJ..."}
API->>GCP: Verify token signature (JWKS)
API->>API: Validate claims (issuer, audience, hd)
API->>API: Grant admin permissions (edit: *, publish: *)
Expand All @@ -193,10 +193,10 @@ sequenceDiagram
ID_TOKEN=$(gcloud auth print-identity-token)

# Exchange for Registry JWT token
REGISTRY_TOKEN=$(curl -X POST /v0/auth/oidc \
REGISTRY_TOKEN=$(curl -X POST /v0.1/auth/oidc \
-H "Content-Type: application/json" \
-d '{"oidc_token": "'$ID_TOKEN'"}' | jq -r .registry_token)

# Use for admin operations
curl -H "Authorization: Bearer $REGISTRY_TOKEN" /v0/...
curl -H "Authorization: Bearer $REGISTRY_TOKEN" /v0.1/...
```
4 changes: 2 additions & 2 deletions docs/modelcontextprotocol-io/registry-aggregators.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ The `GET /v0.1/servers` endpoint supports cursor-based pagination.
For example, the first page can be fetched using a `limit` query parameter:

```bash
curl "https://registry.modelcontextprotocol.io/v0/servers?limit=100"
curl "https://registry.modelcontextprotocol.io/v0.1/servers?limit=100"
```

```jsonc Output highlight={5}
Expand All @@ -48,7 +48,7 @@ curl "https://registry.modelcontextprotocol.io/v0/servers?limit=100"
Then subsequent pages can be fetched by passing the `nextCursor` value as the `cursor` query parameter:

```bash
curl "https://registry.modelcontextprotocol.io/v0/servers?limit=100&cursor=com.example/my-server:1.0.0"
curl "https://registry.modelcontextprotocol.io/v0.1/servers?limit=100&cursor=com.example/my-server:1.0.0"
```

### Filtering Since
Expand Down
12 changes: 6 additions & 6 deletions docs/reference/api/generic-registry-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,11 +14,11 @@ The official registry has some more endpoints and restrictions on top of this. S
## Quick Reference

### Core Endpoints
- **`GET /v0/servers`** - List all servers with pagination
- **`GET /v0/servers/{serverName}/versions`** - List all versions of a server
- **`GET /v0/servers/{serverName}/versions/{version}`** - Get specific version of server. Use the special version `latest` to get the latest version.
- **`POST /v0/publish`** - Publish new server (optional, registry-specific authentication)
- **`DELETE /v0/servers/{serverName}/versions/{version}`** - Delete specific server version (optional, not implemented by official registry)
- **`GET /v0.1/servers`** - List all servers with pagination
- **`GET /v0.1/servers/{serverName}/versions`** - List all versions of a server
- **`GET /v0.1/servers/{serverName}/versions/{version}`** - Get specific version of server. Use the special version `latest` to get the latest version.
- **`POST /v0.1/publish`** - Publish new server (optional, registry-specific authentication)
- **`DELETE /v0.1/servers/{serverName}/versions/{version}`** - Delete specific server version (optional, not implemented by official registry)

Server names and version strings should be URL-encoded in paths.

Expand All @@ -42,7 +42,7 @@ List endpoints use cursor-based pagination for efficient, stable results.
### Basic Example: List Servers

```bash
curl https://registry.example.com/v0/servers?limit=10
curl https://registry.example.com/v0.1/servers?limit=10
```

```json
Expand Down
18 changes: 9 additions & 9 deletions docs/reference/api/official-registry-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ The official registry enforces additional [package validation requirements](../s

### Server List Filtering

The official registry extends the `GET /v0/servers` endpoint with additional query parameters for improved discovery and synchronization:
The official registry extends the `GET /v0.1/servers` endpoint with additional query parameters for improved discovery and synchronization:

- `updated_since` - Filter servers updated after RFC3339 timestamp (e.g., `2025-08-07T13:15:04.280Z`)
- `search` - Case-insensitive substring search on server names (e.g., `filesystem`)
Expand All @@ -44,18 +44,18 @@ The official registry extends the `GET /v0/servers` endpoint with additional que

These extensions enable efficient incremental synchronization for downstream registries and improved server discovery. Parameters can be combined and work with standard cursor-based pagination.

Example: `GET /v0/servers?search=filesystem&updated_since=2025-08-01T00:00:00Z&version=latest`
Example: `GET /v0.1/servers?search=filesystem&updated_since=2025-08-01T00:00:00Z&version=latest`

### Additional endpoints

#### Auth endpoints
- POST `/v0/auth/dns` - Exchange signed DNS challenge for auth token
- POST `/v0/auth/http` - Exchange signed HTTP challenge for auth token
- POST `/v0/auth/github-at` - Exchange GitHub access token for auth token
- POST `/v0/auth/github-oidc` - Exchange GitHub OIDC token for auth token
- POST `/v0/auth/oidc` - Exchange Google OIDC token for auth token (for admins)
- POST `/v0.1/auth/dns` - Exchange signed DNS challenge for auth token
- POST `/v0.1/auth/http` - Exchange signed HTTP challenge for auth token
- POST `/v0.1/auth/github-at` - Exchange GitHub access token for auth token
- POST `/v0.1/auth/github-oidc` - Exchange GitHub OIDC token for auth token
- POST `/v0.1/auth/oidc` - Exchange Google OIDC token for auth token (for admins)

#### Admin endpoints
- GET `/metrics` - Prometheus metrics endpoint
- GET `/v0/health` - Basic health check endpoint
- PUT `/v0/servers/{serverName}/versions/{version}` - Edit specific server version
- GET `/v0.1/health` - Basic health check endpoint
- PUT `/v0.1/servers/{serverName}/versions/{version}` - Edit specific server version
8 changes: 4 additions & 4 deletions docs/reference/api/openapi.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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)
Expand Down
2 changes: 1 addition & 1 deletion scripts/mirror_data/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ go run scripts/mirror_data/fetch_production_data.go
```

This will:
- Fetch all servers from https://registry.modelcontextprotocol.io/v0/servers
- Fetch all servers from https://registry.modelcontextprotocol.io/v0.1/servers
- Handle pagination automatically
- Save data to `scripts/mirror_data/production_servers.json`
- Be respectful to the API with rate limiting
Expand Down
Loading