Skip to main content

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.

The server provides two types of registry endpoints to support different use cases:

Endpoint Types​

1. Aggregated Registry Endpoints (Read-Only)

These endpoints provide a unified view across all configured registries. Ideal for enterprise-wide discovery where you want to query all available MCP servers from all sources (Git, API, File, Managed, Kubernetes).

  • Pattern: /registry/v0.1/...
  • Example: GET /registry/v0.1/servers
  • Use case: Enterprise UI showing complete catalog from all registries

2. Per-Registry Endpoints (Standards-Compliant)

These endpoints access a specific registry by name. Fully compatible with the upstream MCP Registry API specification and support both read and write operations (for managed registries).

  • Pattern: /registry/{registryName}/v0.1/...
  • Example: GET /registry/toolhive/v0.1/servers
  • Use case: Direct access to a specific registry (e.g., only upstream verified MCPs)
tip
  • Use aggregated endpoints (/registry/v0.1/...) when you want to discover servers from all configured registries
  • Use per-registry endpoints (/registry/{registryName}/v0.1/...) when you need to:
    • Query a specific registry
    • Publish or delete servers (only supported for managed registries)
    • Maintain compatibility with upstream MCP Registry API clients

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​