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
3 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",