Skip to content

official-registry-api.md

Latest commit

 

History

History
115 lines (74 loc) · 5.06 KB

official-registry-api.md

File metadata and controls

115 lines (74 loc) · 5.06 KB
Raw

Official MCP Registry API

This document describes the API for the official MCP Registry hosted at registry.modelcontextprotocol.io.

This API is based on the generic registry API with additional endpoints and authentication. For publishing servers using the API, see the publishing guide.

Base URLs

  • Production: https://registry.modelcontextprotocol.io
  • Staging: https://staging.registry.modelcontextprotocol.io

Interactive Documentation

Extensions

The official registry implements the Generic Registry API with the following specific configurations and extensions:

Authentication

Publishing requires namespace-based authentication:

  • GitHub OAuth - For io.github.* namespaces
  • GitHub OIDC - For publishing from GitHub Actions
  • DNS verification - For domain-based namespaces (com.example.*)
  • HTTP verification - For domain-based namespaces (com.example.*)

See Publisher Commands for authentication setup.

Package Validation

The official registry enforces additional package validation requirements when publishing.

Server List Filtering

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)
    • This is intentionally simple. For more advanced searching and filtering, use a subregistry.
  • version - Filter by version (currently supports latest for latest versions only)
  • include_deleted - Include deleted servers in results (default: false, but automatically true when updated_since is provided for incremental sync)

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.1/servers?search=filesystem&updated_since=2025-08-01T00:00:00Z&version=latest

Server Detail

The GET /v0.1/servers/{serverName}/versions/{version} endpoint returns detailed information about a specific server version.

Path parameters:

  • serverName - URL-encoded server name (e.g., io.github.user%2Fmy-server)
  • version - Server version or latest for the most recent version

Query parameters:

  • include_deleted - Include deleted servers in results (default: false)

Server Version History

The GET /v0.1/servers/{serverName}/versions endpoint returns all versions of a server.

Path parameters:

  • serverName - URL-encoded server name (e.g., io.github.user%2Fmy-server)

Query parameters:

  • include_deleted - Include deleted servers in results (default: false)

Additional endpoints

Auth endpoints

  • 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)

Status endpoints

Update Single Version Status

PATCH /v0.1/servers/{serverName}/versions/{version}/status - Update status of a specific server version.

Path parameters:

  • serverName - URL-encoded server name (e.g., io.github.user%2Fmy-server)
  • version - Server version to update

Request body:

  • status (required) - New status: active, deprecated, or deleted
  • statusMessage (optional) - Message explaining the status change (max 500 characters, not allowed when status is active)
Update All Versions Status

PATCH /v0.1/servers/{serverName}/status - Update status of all versions of a server in a single transaction.

Path parameters:

  • serverName - URL-encoded server name (e.g., io.github.user%2Fmy-server)

Request body:

  • status (required) - New status: active, deprecated, or deleted
  • statusMessage (optional) - Message explaining the status change (max 500 characters, not allowed when status is active)

Status values:

  • active - Server is active and visible in default listings
  • deprecated - Server is deprecated but still visible with a warning message
  • deleted - Server is hidden from default listings (use include_deleted=true to show)

Authentication: Requires publish or edit permission for the server namespace.

Admin endpoints

  • GET /metrics - Prometheus metrics endpoint
  • GET /v0.1/health - Basic health check endpoint
  • PUT /v0.1/servers/{serverName}/versions/{version} - Edit specific server version