MCP Registry API Documentation

The MCP Registry API provides a centralized service for discovering and managing Model Context Protocol (MCP) servers. This API is available at https://registry.plugged.inand offers enhanced features including filtering, sorting, and search capabilities.

RESTful API

GitHub Auth

Real-time Updates

Base URL

https://registry.plugged.in

GET

/v0/health

Check the health status of the registry service

Response:

{
  "status": "ok",
  "github_client_configured": true
}

GET

/v0/servers

Retrieve a paginated list of MCP servers with optional filtering, sorting, and search

Query Parameters:

Parameter	Type	Description	Default
`limit`	integer	Number of results per page (max: 500)	50
`offset`	integer	Number of results to skip	0
`registry_name`	string	Filter by package registry (npm, pip, docker, etc.)	-
`sort`	string	Sort order (see options below)	newest
`search`	string	Search in name and description	-

Sort Options:

newest or release_date_desc - Latest releases first (default)
release_date_asc - Oldest releases first
alphabetical or name_asc - Alphabetical by name (A-Z)
name_desc - Reverse alphabetical (Z-A)

Example Request:

curl "https://registry.plugged.in/v0/servers?registry_name=npm&sort=newest&limit=10"

Response:

{
  "servers": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "io.github.username/mcp-server-example",
      "description": "An example MCP server",
      "repository": {
        "url": "https://github.com/username/mcp-server-example",
        "source": "github",
        "id": "123456789"
      },
      "version_detail": {
        "version": "1.2.3",
        "release_date": "2025-01-11T12:00:00Z",
        "is_latest": true
      },
      "packages": [
        {
          "registry_name": "npm",
          "name": "@username/mcp-server-example",
          "version": "1.2.3"
        }
      ]
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 125
  }
}

GET

/v0/servers/{id}

Retrieve detailed information about a specific MCP server

Path Parameters:

id - The UUID of the server

Example Request:

curl "https://registry.plugged.in/v0/servers/550e8400-e29b-41d4-a716-446655440000"

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "io.github.username/mcp-server-example",
  "description": "An example MCP server with extended features",
  "repository": {
    "url": "https://github.com/username/mcp-server-example",
    "source": "github",
    "id": "123456789"
  },
  "version_detail": {
    "version": "1.2.3",
    "release_date": "2025-01-11T12:00:00Z",
    "is_latest": true
  },
  "packages": [
    {
      "registry_name": "npm",
      "name": "@username/mcp-server-example",
      "version": "1.2.3"
    }
  ],
  "capabilities": {
    "tools": ["calculate", "search", "translate"],
    "prompts": ["math_helper", "code_assistant"],
    "resources": ["file_access", "web_fetch"]
  },
  "transports": ["stdio", "http"],
  "license": "MIT",
  "author": {
    "name": "John Doe",
    "email": "john@example.com"
  }
}

POST

/v0/publish

Publish a new MCP server or update an existing one. Requires GitHub authentication.

Headers:

Authorization: Bearer YOUR_GITHUB_TOKEN
Content-Type: application/json

Request Body:

{
  "url": "https://github.com/username/mcp-server-name"
}

Requirements:

Valid GitHub personal access token
Token owner must have admin access to the repository
Repository must contain a valid MCP server configuration

Example Request:

curl -X POST "https://registry.plugged.in/v0/publish" \
  -H "Authorization: Bearer ghp_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://github.com/username/mcp-server-example"}'

Success Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Server published successfully"
}

POST

/v0/cache/refresh

Manually refresh the proxy cache (useful after publishing)

Example Request:

curl -X POST "https://registry.plugged.in/v0/cache/refresh"

Response:

{
  "message": "Cache refreshed successfully",
  "updated_at": "2025-01-11T12:00:00Z"
}

Support & Contributing

GitHub Issues: registry-proxy/issues

Email: support@plugged.in

Last Updated: January 2025