modelcontextprotocol/registry

MCP Registry

A community driven registry service for Model Context Protocol (MCP) servers.

Development Status

This project is being built in the open and is currently in the early stages of development. Please see the overview discussion for the project scope and goals. If you would like to contribute, please check out the contributing guidelines.

Overview

The MCP Registry service provides a centralized repository for MCP server entries. It allows discovery and management of various MCP implementations with their associated metadata, configurations, and capabilities.

Features

RESTful API for managing MCP registry entries (list, get, create, update, delete)
Health check endpoint for service monitoring
Support for various environment configurations
Graceful shutdown handling
MongoDB and in-memory database support
Comprehensive API documentation
Pagination support for listing registry entries

Getting Started

Prerequisites

Go 1.18 or later
MongoDB
Docker (optional, but recommended for development)

Running

The easiest way to get the registry running is to use docker compose. This will setup the MCP Registry service, import the seed data and run MongoDB in a local Docker environment.

1
2
3
4
5


# Build the Docker image
docker build -t registry .

# Run the registry and MongoDB with docker compose
docker compose up

This will start the MCP Registry service and MongoDB with Docker, exposing it on port 8080.

Building

If you prefer to run the service locally without Docker, you can build and run it directly using Go.

1
2


# Build a registry executable
go build ./cmd/registry

This will create the registry binary in the current directory. You’ll need to have MongoDB running locally or with Docker.

By default, the service will run on http://localhost:8080.

Project Structure

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


├── api/           # OpenApi specification
├── cmd/           # Application entry points
├── config/        # Configuration files
├── internal/      # Private application code
│   ├── api/       # HTTP server and request handlers
│   ├── config/    # Configuration management
│   ├── model/     # Data models
│   └── service/   # Business logic
├── pkg/           # Public libraries
├── scripts/       # Utility scripts
└── tools/         # Command line tools
    └── publisher/ # Tool to publish MCP servers to the registry

API Documentation

The API is documented using Swagger/OpenAPI. You can access the interactive Swagger UI at:

1

/v0/swagger/index.html

This provides a complete reference of all endpoints with request/response schemas and allows you to test the API directly from your browser.

API Endpoints

Health Check

1

GET /v0/health

Returns the health status of the service:

1
2
3


{
  "status": "ok"
}

Registry Endpoints

List Registry Server Entries

1

GET /v0/servers

Lists MCP registry server entries with pagination support.

Query parameters:

limit: Maximum number of entries to return (default: 30, max: 100)
cursor: Pagination cursor for retrieving next set of results

Response example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


{
  "servers": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "Example MCP Server",
      "url": "https://example.com/mcp",
      "description": "An example MCP server",
      "created_at": "2025-05-17T17:34:22.912Z",
      "updated_at": "2025-05-17T17:34:22.912Z"
    }
  ],
  "metadata": {
    "next_cursor": "123e4567-e89b-12d3-a456-426614174000",
    "count": 30
  }
}

Get Server Details

1

GET /v0/servers/{id}

Retrieves detailed information about a specific MCP server entry.

Path parameters:

id: Unique identifier of the server entry

Response example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43


{
  "id": "01129bff-3d65-4e3d-8e82-6f2f269f818c",
  "name": "io.github.gongrzhe/redis-mcp-server",
  "description": "A Redis MCP server (pushed to https://github.com/modelcontextprotocol/servers/tree/main/src/redis) implementation for interacting with Redis databases. This server enables LLMs to interact with Redis key-value stores through a set of standardized tools.",
  "repository": {
    "url": "https://github.com/GongRzhe/REDIS-MCP-Server",
    "source": "github",
    "id": "907849235"
  },
  "version_detail": {
    "version": "0.0.1-seed",
    "release_date": "2025-05-16T19:13:21Z",
    "is_latest": true
  },
  "package_canonical": "docker",
  "packages": [
    {
      "registry_name": "docker",
      "name": "@gongrzhe/server-redis-mcp",
      "version": "1.0.0",
      "package_arguments": [
        {
          "description": "Docker image to run",
          "is_required": true,
          "format": "string",
          "value": "mcp/redis",
          "default": "mcp/redis",
          "type": "positional",
          "value_hint": "mcp/redis"
        },
        {
          "description": "Redis server connection string",
          "is_required": true,
          "format": "string",
          "value": "redis://host.docker.internal:6379",
          "default": "redis://host.docker.internal:6379",
          "type": "positional",
          "value_hint": "host.docker.internal:6379"
        }
      ]
    }
  ]
}

Publish a Server Entry

1

POST /v0/publish

Publishes a new MCP server entry to the registry. Authentication is required via Bearer token in the Authorization header.

Headers:

Authorization: Bearer token for authentication (e.g., Bearer your_token_here)
Content-Type: application/json

Request body example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58


{
    "description": "<your description here>",
    "name": "io.github.<owner>/<server-name>",
    "package_canonical": "<package_registry",
    "packages": [
        {
            "registry_name": "npm",
            "name": "@<owner>/<server-name>",
            "version": "0.2.23",
            "package_arguments": [
                {
                    "description": "Specify services and permissions.",
                    "is_required": true,
                    "format": "string",
                    "value": "-s",
                    "default": "-s",
                    "type": "positional",
                    "value_hint": "-s"
                }
            ],
            "environment_variables": [
                {
                    "description": "API Key to access the server",
                    "name": "API_KEY"
                }
            ]
        },{
            "registry_name": "docker",
            "name": "@<owner>/<server-name>-cli",
            "version": "0.123.223",
            "runtime_hint": "docker",
            "runtime_arguments": [
                {
                    "description": "Specify services and permissions.",
                    "is_required": true,
                    "format": "string",
                    "value": "--mount",
                    "default": "--mount",
                    "type": "positional",
                    "value_hint": "--mount"
                }
            ],
            "environment_variables": [
                {
                    "description": "API Key to access the server",
                    "name": "API_KEY"
                }
            ]
        }
    ],
    "repository": {
        "url": "https://github.com//<owner>/<server-name>",
        "source": "github"
    },
    "version_detail": {
        "version": "0.0.1-<publisher_version>"
    }
}

Response example:

1
2
3
4


{
  "message": "Server publication successful",
  "id": "1234567890abcdef12345678"
}

Ping Endpoint

1

GET /v0/ping

Simple ping endpoint that returns environment configuration information:

1
2
3
4


{
  "environment": "dev",
  "version": "registry-<sha>"
}

Configuration

The service can be configured using environment variables:

Variable	Description	Default
`MCP_REGISTRY_APP_VERSION`	Application version	`dev`
`MCP_REGISTRY_COLLECTION_NAME`	MongoDB collection name	`servers_v2`
`MCP_REGISTRY_DATABASE_NAME`	MongoDB database name	`mcp-registry`
`MCP_REGISTRY_DATABASE_URL`	MongoDB connection string	`mongodb://localhost:27017`
`MCP_REGISTRY_GITHUB_CLIENT_ID`	GitHub App Client ID
`MCP_REGISTRY_GITHUB_CLIENT_SECRET`	GitHub App Client Secret
`MCP_REGISTRY_LOG_LEVEL`	Log level	`info`
`MCP_REGISTRY_SEED_FILE_PATH`	Path to import seed file	`data/seed.json`
`MCP_REGISTRY_SEED_IMPORT`	Import `seed.json` on first run	`true`
`MCP_REGISTRY_SERVER_ADDRESS`	Listen address for the server	`:8080`

Testing

Run the test script to validate API endpoints:

1

./scripts/test_endpoints.sh

You can specify specific endpoints to test:

1
2


./scripts/test_endpoints.sh --endpoint health
./scripts/test_endpoints.sh --endpoint servers

License

See the LICENSE file for details.

Contributing

See the CONTRIBUTING file for details.