API reference

The Registry API server implements the official MCP Registry API v0.1 specification, along with extension endpoints for registry management.

Base URL

All API endpoints are prefixed with the server's base URL. By default, the server runs on port 8080:

http://localhost:8080

Registry API (v0.1)

The core MCP Registry API endpoints for discovering and accessing MCP servers.

List all servers

List all available MCP servers in the registry.

GET /registry/v0.1/servers
GET /registry/{registryName}/v0.1/servers

Query parameters:

• cursor (optional, string): Pagination cursor for retrieving the next set of results
• limit (optional, integer): Maximum number of items to return
• search (optional, string): Search servers by name (substring match)
• updated_since (optional, string): Filter servers updated since timestamp (RFC3339 datetime format, e.g., 2025-08-07T13:15:04.280Z)
• version (optional, string): Filter by version (latest for latest version, or an exact version like 1.2.3)

Response:

{
  "servers": [
    {
      "name": "example/filesystem",
      "description": "Example filesystem MCP server",
      "version": "1.0.0"
    }
  ],
  "metadata": {
    "nextCursor": "",
    "count": 1
  }
}

List server versions

List all versions of a specific server.

GET /registry/v0.1/servers/{name}/versions
GET /registry/{registryName}/v0.1/servers/{name}/versions

Parameters:

• name (path, required): Server name (URL-encoded)
• registryName (path, optional): Registry name (only for registry-specific endpoint)

Response:

{
  "servers": [
    {
      "name": "example/filesystem",
      "version": "1.0.0",
      "description": "Example filesystem MCP server"
    },
    {
      "name": "example/filesystem",
      "version": "0.9.0",
      "description": "Example filesystem MCP server"
    }
  ],
  "metadata": {
    "nextCursor": "",
    "count": 2
  }
}

Get server version

Get details for a specific server version.

GET /registry/v0.1/servers/{name}/versions/{version}
GET /registry/{registryName}/v0.1/servers/{name}/versions/{version}

Parameters:

• name (path, required): Server name (URL-encoded)
• version (path, required): Version identifier (use latest for the latest version)
• registryName (path, optional): Registry name (only for registry-specific endpoint)

Response:

{
  "server": {
    "name": "example/filesystem",
    "version": "1.0.0",
    "description": "Example filesystem MCP server",
    "transport": "stdio",
    "command": ["node", "server.js"],
    "env": {
      "NODE_ENV": "production"
    }
  },
  "meta": {}
}

Delete server version

Delete a server version from a managed registry.

DELETE /registry/{registryName}/v0.1/servers/{name}/versions/{version}

Parameters:

• registryName (path, required): Registry name
• name (path, required): Server name (URL-encoded)
• version (path, required): Version identifier

Response:

• 204 No Content on success

Error responses:

• 400 Bad Request - Invalid request parameters
• 401 Unauthorized - Invalid or no credentials provided
• 403 Forbidden - Registry is not a managed registry (cannot delete from read-only registries)
• 404 Not Found - Registry or server version not found
• 500 Internal Server Error - Server error

Publish server

Publish a new server version to the registry.

POST /{registryName}/v0.1/publish

Parameters:

• registryName (path, required): Registry name

Request body:

{
  "name": "example/filesystem",
  "version": "1.0.0",
  "description": "Example filesystem MCP server",
  "transport": "stdio",
  "command": ["node", "server.js"],
  "env": {
    "NODE_ENV": "production"
  }
}

Response:

• 201 Created - Server version published successfully

Error responses:

• 400 Bad Request - Invalid request body or missing required fields
• 401 Unauthorized - Invalid or no credentials provided
• 403 Forbidden - Registry is not a managed registry (cannot publish to read-only registries)
• 404 Not Found - Registry not found
• 409 Conflict - Version already exists
• 500 Internal Server Error - Server error

Legacy endpoint

The endpoint POST /registry/v0.1/publish returns 501 Not Implemented. Use the registry-specific endpoint POST /{registryName}/v0.1/publish instead.

Operational endpoints

Endpoints for monitoring and operational purposes.

Health check

Check if the server is running.

GET /health

Response:

• 200 OK if the server is running

Readiness check

Check if the server is ready to serve requests.

GET /readiness

Response:

• 200 OK if the server is ready
• 503 Service Unavailable if the server is not ready

Version information

Get version information about the server.

GET /version

Response:

{
  "version": "0.1.0",
  "commit": "abc123",
  "buildDate": "2024-01-01T00:00:00Z"
}

Error responses

All endpoints may return standard HTTP error responses:

• 400 Bad Request - Invalid request parameters or request body
• 401 Unauthorized - Invalid or no credentials provided
• 403 Forbidden - Operation not allowed (e.g., attempting to delete or publish to a read-only registry)
• 404 Not Found - Resource not found (registry, server, or version)
• 409 Conflict - Resource conflict (e.g., version already exists)
• 500 Internal Server Error - Server error
• 501 Not Implemented - Endpoint not supported
• 503 Service Unavailable - Service temporarily unavailable

Error responses include a JSON body with error details:

{
  "error": "Server not found"
}

API specification

For the complete API specification, see the MCP Registry API specification.

Next steps

• Configure the server to set up your data sources
• Deploy the server in your environment