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

Changes on the server.json format and the API (#562)

Browse source
This commit is contained in:
Radoslav Dimitrov 2025-09-29 23:30:35 +03:00 • committed by GitHub
commit b21c6f564d
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
10 changed files with 4056 additions and 5608 deletions
Download patch file Download diff file Expand all files Collapse all files

94
docs/guides/administration/admin-operations.md
View file

@ -23,14 +23,17 @@ Use this when you need to modify details of a specific version (e.g., fix descri
### Step 1: Download Specific Version
```bash
export SERVER_ID="<server-uuid>" # This is the server ID (consistent across versions)
export VERSION="<version-string>" # e.g., "1.0.0" (optional, defaults to latest)
export SERVER_NAME="<server-name>" # e.g., "com.example/my-server"
export VERSION="<version-string>" # e.g., "1.0.0" (optional, defaults to latest)
# URL encode the server name (replace / with %2F)
ENCODED_SERVER_NAME=$(echo "$SERVER_NAME" | sed 's|/|%2F|g')
# Get specific version
curl -s "https://registry.modelcontextprotocol.io/v0/servers/${SERVER_ID}?version=${VERSION}" > server.json
curl -s "https://registry.modelcontextprotocol.io/v0/servers/${ENCODED_SERVER_NAME}/versions/${VERSION}" > server.json
# Or get latest version (omit version parameter)
curl -s "https://registry.modelcontextprotocol.io/v0/servers/${SERVER_ID}" > server.json
# Or get latest version (omit /versions/VERSION)
curl -s "https://registry.modelcontextprotocol.io/v0/servers/${ENCODED_SERVER_NAME}" > server.json
```
### Step 2: Make Changes
@ -41,7 +44,7 @@ Open `server.json` and edit the specific version details. You cannot change the
```bash
# Update specific version
curl -X PUT "https://registry.modelcontextprotocol.io/v0/servers/${SERVER_ID}?version=${VERSION}" \
curl -X PUT "https://registry.modelcontextprotocol.io/v0/servers/${ENCODED_SERVER_NAME}/versions/${VERSION}" \
-H "Authorization: Bearer ${REGISTRY_TOKEN}" \
-H "Content-Type: application/json" \
-d "$(cat server.json)"
@ -55,36 +58,35 @@ Use this when you need to apply changes across all versions of a server (e.g., m
### Step 1: List All Versions
```bash
export SERVER_ID="<server-uuid>" # This is the server ID (consistent across versions)
curl -s "https://registry.modelcontextprotocol.io/v0/servers/${SERVER_ID}/versions" > all_versions.json
export SERVER_NAME="<server-name>" # e.g., "com.example/my-server"
ENCODED_SERVER_NAME=$(echo "$SERVER_NAME" | sed 's|/|%2F|g')
curl -s "https://registry.modelcontextprotocol.io/v0/servers/${ENCODED_SERVER_NAME}/versions" > all_versions.json
```
### Step 2: Extract Version IDs
### Step 2: Extract Versions
```bash
# Extract all version IDs from the server
jq -r '.servers[]._meta."io.modelcontextprotocol.registry/official".version_id' all_versions.json > version_ids.txt
# Extract all versions from the server
jq -r '.servers[].server.version' all_versions.json > versions.txt
```
### Step 3: Apply Changes to All Versions
```bash
# For each version, download, modify, and update
while read VERSION_ID; do
echo "Processing version: $VERSION_ID"
curl -s "https://registry.modelcontextprotocol.io/v0/servers/${VERSION_ID}" > temp_version.json
# For each version, apply changes using the edit endpoint
while read VERSION; do
echo "Processing version: $VERSION"
# Apply your changes here (e.g., set status to "deleted")
jq '.status = "deleted"' temp_version.json > modified_version.json
curl -X PUT "https://registry.modelcontextprotocol.io/v0/servers/${VERSION_ID}" \
curl -X PUT "https://registry.modelcontextprotocol.io/v0/servers/${ENCODED_SERVER_NAME}/versions/${VERSION}?status=deleted" \
-H "Authorization: Bearer ${REGISTRY_TOKEN}" \
-H "Content-Type: application/json" \
-d "{\"server\": $(cat modified_version.json)}"
done < version_ids.txt
-H "Content-Type: application/json"
done < versions.txt
# Clean up temporary files
rm temp_version.json modified_version.json version_ids.txt all_versions.json
rm versions.txt all_versions.json
```
## Quick Operations
@ -92,29 +94,47 @@ rm temp_version.json modified_version.json version_ids.txt all_versions.json
### Get Latest Version of a Server
```bash
export SERVER_ID="<server-uuid>"
curl -s "https://registry.modelcontextprotocol.io/v0/servers/${SERVER_ID}" > latest_version.json
export VERSION_ID=$(jq -r '._meta."io.modelcontextprotocol.registry/official".version_id' latest_version.json)
echo "Latest version ID: $VERSION_ID"
export SERVER_NAME="<server-name>" # e.g., "com.example/my-server"
ENCODED_SERVER_NAME=$(echo "$SERVER_NAME" | sed 's|/|%2F|g')
curl -s "https://registry.modelcontextprotocol.io/v0/servers/${ENCODED_SERVER_NAME}" > latest_version.json
export VERSION=$(jq -r '.server.version' latest_version.json)
echo "Latest version: $VERSION"
```
### Takedown a Specific Version
```bash
export VERSION_ID="<version-uuid>"
./tools/admin/takedown.sh
export SERVER_NAME="<server-name>" # e.g., "com.example/my-server"
export VERSION="<version-string>" # e.g., "1.0.0"
export REGISTRY_TOKEN="<your-token>"
REGISTRY_TOKEN="$REGISTRY_TOKEN" SERVER_NAME="$SERVER_NAME" VERSION="$VERSION" ./tools/admin/takedown.sh
```
### Takedown an Entire Server (All Versions)
### Takedown Latest Version (Entire Server)
```bash
export SERVER_ID="<server-uuid>"
# Get all version IDs and takedown each one
curl -s "https://registry.modelcontextprotocol.io/v0/servers/${SERVER_ID}/versions" | \
jq -r '.servers[]._meta."io.modelcontextprotocol.registry/official".version_id' | \
while read VERSION_ID; do
echo "Taking down version: $VERSION_ID"
./tools/admin/takedown.sh "$VERSION_ID"
export SERVER_NAME="<server-name>" # e.g., "com.example/my-server"
export REGISTRY_TOKEN="<your-token>"
# This marks the latest version as deleted
REGISTRY_TOKEN="$REGISTRY_TOKEN" SERVER_NAME="$SERVER_NAME" ./tools/admin/takedown.sh
```
### Takedown All Versions of a Server
```bash
export SERVER_NAME="<server-name>" # e.g., "com.example/my-server"
export REGISTRY_TOKEN="<your-token>"
ENCODED_SERVER_NAME=$(echo "$SERVER_NAME" | sed 's|/|%2F|g')
# Get all versions and takedown each one
curl -s "https://registry.modelcontextprotocol.io/v0/servers/${ENCODED_SERVER_NAME}/versions" | \
jq -r '.servers[].server.version' | \
while read VERSION; do
echo "Taking down version: $VERSION"
REGISTRY_TOKEN="$REGISTRY_TOKEN" SERVER_NAME="$SERVER_NAME" VERSION="$VERSION" ./tools/admin/takedown.sh
done
```

34
docs/guides/consuming/use-rest-api.md
View file

@ -9,9 +9,9 @@ Integration patterns and best practices for building applications that consume M
**Authentication**: Not required for read-only access
- **`GET /v0/servers`** - List all servers with pagination
- **`GET /v0/servers/{server_id}`** - Get latest version of server by server ID
- **`GET /v0/servers/{server_id}?version=X.X.X`** - Get specific version of server
- **`GET /v0/servers/{server_id}/versions`** - List all versions of a server
- **`GET /v0/servers/{serverName}`** - Get latest version of server by server name (URL-encoded)
- **`GET /v0/servers/{serverName}/versions/{version}`** - Get specific version of server
- **`GET /v0/servers/{serverName}/versions`** - List all versions of a server
See the [interactive API documentation](https://registry.modelcontextprotocol.io/docs) for complete request/response schemas.
@ -22,6 +22,32 @@ See the [interactive API documentation](https://registry.modelcontextprotocol.io
For now we recommend scraping the `GET /v0/servers` endpoint on some regular basis. In the future we might provide a filter for updatedAt ([#291](https://github.com/modelcontextprotocol/registry/issues/291)) to get only recently changed servers.
### Pagination Example
The API uses cursor-based pagination. Here's how to fetch all servers:
```bash
# Initial request
curl "https://registry.modelcontextprotocol.io/v0/servers?limit=100"
```
```json
{
"servers": [...],
"metadata": {
"count": 100,
"nextCursor": "com.example/my-server:1.0.0"
}
}
```
```bash
# Next page using cursor
curl "https://registry.modelcontextprotocol.io/v0/servers?limit=100&cursor=com.example%2Fmy-server%3A1.0.0"
```
**Important**: Always URL-encode cursor values when using them in query parameters.
Servers are generally immutable, except for the `status` field which can be updated to `deleted` (among other states). For these packages, we recommend you also update the status field to `deleted` or remove the package from your registry quickly. This is because this status generally indicates it has violated our permissive [moderation guidelines](../administration/moderation-guidelines.md), suggesting it is illegal, malware or spam.
### Filtering & Enhancement
@ -32,7 +58,7 @@ You can also add custom metadata to servers using the `_meta` field. For example
```json
{
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-16/server.schema.json",
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
"name": "io.github.yourname/weather-server",
"description": "MCP server for weather data access",
"status": "active",

16
docs/guides/publishing/publish-server.md
View file

@ -92,7 +92,7 @@ This creates a `server.json` with auto-detected values. You'll see something lik
```json
{
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-16/server.schema.json",
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
"name": "io.github.yourname/your-server",
"description": "A description of your MCP server",
"version": "1.0.0",
@ -151,7 +151,7 @@ Add an `mcpName` field to your `package.json`:
### Example server.json
```json
{
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-16/server.schema.json",
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
"name": "io.github.username/server-name",
"description": "A server that provides npm package functionality",
"version": "1.0.0",
@ -189,7 +189,7 @@ Add it to your README.md file (which becomes the package description on PyPI). T
### Example server.json
```json
{
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-16/server.schema.json",
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
"name": "io.github.username/server-name",
"description": "A server that provides PyPI package functionality",
"version": "1.0.0",
@ -227,7 +227,7 @@ Add a README file to your NuGet package that includes the server name. This can
### Example server.json
```json
{
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-16/server.schema.json",
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
"name": "io.github.username/server-name",
"description": "A server that provides NuGet package functionality",
"version": "1.0.0",
@ -269,7 +269,7 @@ LABEL io.modelcontextprotocol.server.name="io.github.username/server-name"
### Example server.json (Docker Hub)
```json
{
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-16/server.schema.json",
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
"name": "io.github.username/server-name",
"description": "A server that provides Docker container functionality",
"version": "1.0.0",
@ -290,7 +290,7 @@ LABEL io.modelcontextprotocol.server.name="io.github.username/server-name"
### Example server.json (GitHub Container Registry)
```json
{
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-16/server.schema.json",
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
"name": "io.github.username/server-name",
"description": "A server that provides GitHub container functionality",
"version": "1.0.0",
@ -332,7 +332,7 @@ openssl dgst -sha256 server.mcpb
### Example server.json
```json
{
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-16/server.schema.json",
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
"name": "io.github.username/server-name",
"description": "A server that provides MCPB package functionality",
"version": "1.0.0",
@ -377,7 +377,7 @@ Add the `remotes` field to your `server.json` (can coexist with `packages`):
```json
{
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-16/server.schema.json",
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
"name": "com.yourcompany/api-server",
"description": "Cloud-hosted MCP server for API operations",
"version": "2.0.0",

24
docs/reference/api/CHANGELOG.md
View file

@ -2,6 +2,30 @@
Changes to the REST API endpoints and responses.
## 2025-09-29
### ⚠️ BREAKING CHANGES
#### API Endpoint Restructuring
API endpoints updated to use server names instead of server IDs for better usability.
**Changed endpoints:**
- `GET /v0/servers/{server_id}` → `GET /v0/servers/{serverName}`
- `GET /v0/servers/{server_id}/versions` → `GET /v0/servers/{serverName}/versions`
**New endpoints:**
- `GET /v0/servers/{serverName}/versions/{version}` - Get specific server version
- `PUT /v0/servers/{serverName}/versions/{version}` - Edit server version (admin only)
**Response format changes:**
- Introduced `ServerResponse` schema separating server data from registry metadata
- Moved `status` field from server data to `_meta.io.modelcontextprotocol.registry/official`
- Removed `io.modelcontextprotocol.registry/official` metadata from `ServerDetail` schema
### Changed
- OpenAPI spec version: `2025-09-16` → `2025-09-29`
## 2025-09-16
### ⚠️ BREAKING CHANGES

34
docs/reference/api/generic-registry-api.md
View file

@ -15,9 +15,9 @@ The official registry has some more endpoints and restrictions on top of this. S
### Core Endpoints
- **`GET /v0/servers`** - List all servers with pagination
- **`GET /v0/servers/{server_id}`** - Get latest version of server by server ID
- **`GET /v0/servers/{server_id}?version=X.X.X`** - Get specific version of server
- **`GET /v0/servers/{server_id}/versions`** - List all versions of a server
- **`GET /v0/servers/{serverName}`** - Get latest version of server by server name (URL-encoded)
- **`GET /v0/servers/{serverName}/versions/{version}`** - Get specific version of server (both parameters should be URL-encoded)
- **`GET /v0/servers/{serverName}/versions`** - List all versions of a server
- **`POST /v0/publish`** - Publish new server (optional, registry-specific authentication)
### Authentication
@ -27,6 +27,16 @@ The official registry has some more endpoints and restrictions on top of this. S
### Content Type
All requests and responses use `application/json`
### Pagination
List endpoints use cursor-based pagination for efficient, stable results.
#### Usage
1. **Initial request**: Omit the `cursor` parameter
2. **Subsequent requests**: Use the `nextCursor` value from the previous response
3. **End of results**: When `nextCursor` is null or empty, there are no more results
**Important**: Always treat cursors as opaque strings. Never manually construct or modify cursor values.
### Basic Example: List Servers
```bash
@ -37,15 +47,23 @@ curl https://registry.example.com/v0/servers?limit=10
{
"servers": [
{
"name": "io.modelcontextprotocol/filesystem",
"description": "Filesystem operations server",
"status": "active",
"version": "1.0.2"
"server": {
"name": "io.modelcontextprotocol/filesystem",
"description": "Filesystem operations server",
"version": "1.0.2"
},
"_meta": {
"io.modelcontextprotocol.registry/official": {
"status": "active",
"publishedAt": "2025-01-01T10:30:00Z",
"isLatest": true
}
}
}
],
"metadata": {
"count": 10,
"next_cursor": "eyJ..."
"nextCursor": "com.example/my-server:1.0.0"
}
}
```

2
docs/reference/api/official-registry-api.md
View file

@ -58,4 +58,4 @@ Example: `GET /v0/servers?search=filesystem&updated_since=2025-08-01T00:00:00Z&v
#### Admin endpoints
- GET `/metrics` - Prometheus metrics endpoint
- GET `/v0/health` - Basic health check endpoint
- PUT `/v0/servers/{server_id}?version=X.X.X` - Edit specific server version (version parameter required)
- PUT `/v0/servers/{serverName}/versions/{version}` - Edit specific server version

181
docs/reference/api/openapi.yaml
View file

@ -1,9 +1,9 @@
openapi: 3.1.0
jsonSchemaDialect: "https://json-schema.org/draft/2020-12/schema"
$id: https://modelcontextprotocol.io/schemas/draft/2025-09-16/server-registry-openapi
$id: https://modelcontextprotocol.io/schemas/draft/2025-09-29/server-registry-openapi
info:
title: MCP Server Registry API
version: "2025-09-16"
version: "2025-09-29"
summary: API for discovering and accessing MCP server metadata
description: |
Specification for a theoretical REST API that serves up metadata about MCP servers.
@ -19,7 +19,10 @@ paths:
parameters:
- name: cursor
in: query
description: Pagination cursor for retrieving next set of results
description: |
Pagination cursor for retrieving next set of results.
Cursors are opaque strings returned in the `metadata.nextCursor` field of paginated responses. Always use the exact cursor value returned by the API.
required: false
schema:
type: string
@ -36,30 +39,25 @@ paths:
application/json:
schema:
$ref: '#/components/schemas/ServerList'
/v0/servers/{server_id}:
/v0/servers/{serverName}:
get:
summary: Get MCP server details
description: Returns detailed information about a specific MCP server. Returns latest version by default, or specific version if version query parameter is provided.
description: Returns detailed information about the latest version of a specific MCP server.
parameters:
- name: server_id
- name: serverName
in: path
required: true
description: Unique server ID (consistent across all versions)
schema:
type: string
format: uuid
- name: version
in: query
description: Specific version to retrieve (e.g., "1.0.0"). If not provided, returns latest version.
description: URL-encoded server name (e.g., "com.example%2Fmy-server")
schema:
type: string
example: "com.example%2Fmy-server"
responses:
'200':
description: Detailed server information
content:
application/json:
schema:
$ref: '#/components/schemas/ServerDetail'
$ref: '#/components/schemas/ServerResponse'
'404':
description: Server not found
content:
@ -70,18 +68,18 @@ paths:
error:
type: string
example: "Server not found"
/v0/servers/{server_id}/versions:
/v0/servers/{serverName}/versions:
get:
summary: List all versions of an MCP server
description: Returns all available versions for a specific MCP server, ordered by publication date (newest first)
parameters:
- name: server_id
- name: serverName
in: path
required: true
description: Unique server ID (consistent across all versions)
description: URL-encoded server name (e.g., "com.example%2Fmy-server")
schema:
type: string
format: uuid
example: "com.example%2Fmy-server"
responses:
'200':
description: A list of all versions for the server
@ -99,6 +97,42 @@ paths:
error:
type: string
example: "Server not found"
/v0/servers/{serverName}/versions/{version}:
get:
summary: Get specific MCP server version
description: Returns detailed information about a specific version of an MCP server.
parameters:
- name: serverName
in: path
required: true
description: URL-encoded server name (e.g., "com.example%2Fmy-server")
schema:
type: string
example: "com.example%2Fmy-server"
- name: version
in: path
required: true
description: URL-encoded version to retrieve (e.g., "1.0.0" or "1.0.0%2B20130313144700" for versions with build metadata)
schema:
type: string
example: "1.0.0"
responses:
'200':
description: Detailed server information
content:
application/json:
schema:
$ref: '#/components/schemas/ServerResponse'
'404':
description: Server or version not found
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: "Server not found"
/v0/publish:
post:
summary: Publish MCP server (Optional)
@ -122,7 +156,6 @@ paths:
value:
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"
@ -136,7 +169,7 @@ paths:
io.modelcontextprotocol.registry/publisher-provided:
tool: "publisher-cli"
version: "1.2.3"
build_info:
buildInfo:
commit: "abc123def456"
timestamp: "2023-12-01T10:30:00Z"
example_org_server:
@ -144,7 +177,6 @@ paths:
value:
name: "com.example/demo-server"
description: "Example MCP server demonstrating publisher extensions."
status: "active"
repository:
url: "https://github.com/example/mcp-demo"
source: "github"
@ -156,22 +188,22 @@ paths:
version: "1.0.0"
_meta:
io.modelcontextprotocol.registry/publisher-provided:
contact_email: "maintainer@example.com"
build_metadata:
contactEmail: "maintainer@example.com"
buildMetadata:
commit: "abc123"
timestamp: "2024-01-15T10:30:00Z"
com.example:
marketplace_icon: "https://example.com/icon.png"
marketplaceIcon: "https://example.com/icon.png"
category: ["software_development"]
documentation_url: "https://docs.example.org"
verified_publisher: true
documentationUrl: "https://docs.example.org"
verifiedPublisher: true
responses:
'200':
description: Successfully published server
content:
application/json:
schema:
$ref: '#/components/schemas/ServerDetail'
$ref: '#/components/schemas/ServerResponse'
'401':
description: Unauthorized - Invalid or missing authentication token
content:
@ -250,12 +282,6 @@ components:
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
enum: [active, deprecated]
default: active
description: "Server lifecycle status. 'deprecated' indicates the server is no longer recommended for new usage."
example: "active"
repository:
$ref: '#/components/schemas/Repository'
version:
@ -277,13 +303,15 @@ components:
servers:
type: array
items:
$ref: '#/components/schemas/ServerDetail'
$ref: '#/components/schemas/ServerResponse'
metadata:
type: object
properties:
next_cursor:
nextCursor:
type: string
description: Cursor for next page of results
description: |
Pagination cursor for retrieving the next page of results.
Use this exact value in the `cursor` query parameter of your next request. If null or empty, there are no more results.
count:
type: integer
description: Number of items in current page
@ -491,7 +519,7 @@ components:
type: string
format: uri
description: JSON Schema URI for this server.json format
example: "https://static.modelcontextprotocol.io/schemas/2025-09-16/server.schema.json"
example: "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json"
packages:
type: array
items:
@ -511,43 +539,46 @@ components:
example:
tool: "publisher-cli"
version: "1.2.3"
build_info:
buildInfo:
commit: "abc123def456"
timestamp: "2023-12-01T10:30:00Z"
pipeline_id: "build-789"
io.modelcontextprotocol.registry/official:
type: object
description: Registry-specific metadata managed by the MCP registry system
required:
- serverId
- versionId
- publishedAt
- updatedAt
- isLatest
properties:
serverId:
type: string
format: uuid
description: Consistent ID across all versions of a server
example: "550e8400-e29b-41d4-a716-446655440000"
versionId:
type: string
format: uuid
description: Unique ID for this specific version
example: "773f9b2e-1a47-4c8d-b5e6-2f8d9c4a7b3e"
publishedAt:
type: string
format: date-time
description: Timestamp when the server was first published to the registry
example: "2023-12-01T10:30:00Z"
updatedAt:
type: string
format: date-time
description: Timestamp when the server entry was last updated
example: "2023-12-01T11:00:00Z"
isLatest:
type: boolean
description: Whether this is the latest version of the server
example: true
additionalProperties: false
additionalProperties: true
pipelineId: "build-789"
ServerResponse:
description: API response format with separated server data and registry metadata
type: object
required:
- server
- _meta
properties:
server:
$ref: '#/components/schemas/ServerDetail'
_meta:
type: object
description: Registry-managed metadata
properties:
io.modelcontextprotocol.registry/official:
type: object
description: Official MCP registry metadata
properties:
status:
type: string
enum: ["active", "deprecated", "deleted"]
description: Server lifecycle status
example: "active"
publishedAt:
type: string
format: date-time
description: Timestamp when the server was first published to the registry
example: "2023-12-01T10:30:00Z"
updatedAt:
type: string
format: date-time
description: Timestamp when the server entry was last updated
example: "2023-12-01T11:00:00Z"
isLatest:
type: boolean
description: Whether this is the latest version of the server
example: true
additionalProperties: false
additionalProperties: true

20
docs/reference/server-json/CHANGELOG.md
View file

@ -2,6 +2,24 @@
Changes to the server.json schema and format.
## 2025-09-29
### ⚠️ BREAKING CHANGES
#### Schema Simplification
Removed registry-managed fields from publisher-controlled server.json schema.
**Removed fields:**
- `status` field from Server object (now managed by registry in API responses)
- `io.modelcontextprotocol.registry/official` from `_meta` (read-only, added by registry)
**Migration:**
Publishers should remove these fields from their `server.json` files. The registry will manage server status and official metadata separately.
### Changed
- Schema version: `2025-09-16` → `2025-09-29`
## 2025-09-16
### ⚠️ BREAKING CHANGES
@ -116,7 +134,7 @@ All JSON field names standardized to camelCase. **All existing `server.json` fil
#### Updated Schema Reference
🔗 **Current schema**: https://static.modelcontextprotocol.io/schemas/2025-09-16/server.schema.json
🔗 **Current schema**: https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json
### Changed
- Schema version: `2025-07-09` → `2025-09-16`

14
docs/reference/server-json/generic-server-json.md
View file

@ -8,7 +8,7 @@ Also see:
## Browse the Complete Schema
**📋 View the full specification interactively**: Open [server.schema.json](./server.schema.json) in a schema viewer like [json-schema.app](https://json-schema.app/view/%23?url=https%3A%2F%2Fstatic.modelcontextprotocol.io%2Fschemas%2F2025-09-16%2Fserver.schema.json).
**📋 View the full specification interactively**: Open [server.schema.json](./server.schema.json) in a schema viewer like [json-schema.app](https://json-schema.app/view/%23?url=https%3A%2F%2Fstatic.modelcontextprotocol.io%2Fschemas%2F2025-09-29%2Fserver.schema.json).
The schema contains all field definitions, validation rules, examples, and detailed descriptions.
@ -22,7 +22,7 @@ The official registry has some more restrictions on top of this. See the [offici
```json
{
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-16/server.schema.json",
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
"name": "io.modelcontextprotocol.anonymous/brave-search",
"description": "MCP server for Brave Search API integration",
"status": "active",
@ -69,7 +69,7 @@ For MCP servers located within a subdirectory of a larger repository (monorepo s
```json
{
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-16/server.schema.json",
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
"name": "io.modelcontextprotocol/everything",
"description": "MCP server that exercises all the features of the MCP protocol",
"status": "active",
@ -151,7 +151,7 @@ This will essentially instruct the MCP client to execute `dnx Knapcode.SampleMcp
```json
{
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-16/server.schema.json",
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
"name": "io.github.modelcontextprotocol/filesystem",
"description": "Node.js server implementing Model Context Protocol (MCP) for filesystem operations.",
"status": "active",
@ -498,7 +498,7 @@ The `dnx` tool ships with the .NET 10 SDK, starting with Preview 6.
```json
{
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-16/server.schema.json",
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
"name": "io.modelcontextprotocol.anonymous/hybrid-mcp",
"description": "MCP server available as both local package and remote service",
"repository": {
@ -626,7 +626,7 @@ Some CLI tools bundle an MCP server, without a standalone MCP package or a publi
```json
{
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-16/server.schema.json",
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
"name": "io.snyk/cli-mcp",
"description": "MCP server provided by the Snyk CLI",
"status": "active",
@ -661,7 +661,7 @@ For MCP servers that follow a custom installation path or are embedded in applic
```json
{
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-16/server.schema.json",
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
"name": "io.modelcontextprotocol.anonymous/embedded-mcp",
"description": "MCP server embedded in a Desktop app",
"status": "active",

15
docs/reference/server-json/server.schema.json
View file

@ -1,6 +1,6 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://static.modelcontextprotocol.io/schemas/2025-09-16/server.schema.json",
"$id": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
"title": "MCP Server Detail",
"$ref": "#/definitions/ServerDetail",
"definitions": {
@ -58,12 +58,6 @@
"minLength": 1,
"maxLength": 100
},
"status": {
"type": "string",
"enum": ["active", "deprecated", "deleted"],
"default": "active",
"description": "Server lifecycle status. 'deprecated' indicates the server is no longer recommended for new usage. 'deleted' indicates the server should never be installed and existing installations should be uninstalled - this is rare, and usually indicates malware or a legal takedown."
},
"repository": {
"$ref": "#/definitions/Repository",
"description": "Optional repository metadata for the MCP server source code. Recommended for transparency and security inspection."
@ -432,7 +426,7 @@
"type": "string",
"format": "uri",
"description": "JSON Schema URI for this server.json format",
"example": "https://static.modelcontextprotocol.io/schemas/2025-09-16/server.schema.json"
"example": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json"
},
"packages": {
"type": "array",
@ -462,11 +456,6 @@
"type": "object",
"description": "Publisher-provided metadata for downstream registries",
"additionalProperties": true
},
"io.modelcontextprotocol.registry/official": {
"type": "object",
"description": "Official MCP registry metadata (read-only, added by registry)",
"additionalProperties": true
}
}
}