MCP Registry

The MCP Registry provides MCP clients with a list of MCP servers, functioning like an app store for MCP servers. It enables discoverability and integration of Model Context Protocol servers across the ecosystem.

Key Features

Server Discovery - Find and integrate MCP servers
Multi-Platform Publishing - npm, PyPI, NuGet, Docker, MCPB support
Authentication Options - GitHub OAuth, OIDC, DNS, HTTP verification
Remote Servers - Streamable HTTP and SSE transport
Version Management - Semantic versioning with immutable publications
GitHub Actions - Automated CI/CD publishing workflows
Namespace Validation - Verified ownership of server identities

API Status

The Registry API is at v0.1 (API Freeze) - no breaking changes while validating real-world implementations. General availability planned after feedback period.

Live API Documentation: https://registry.modelcontextprotocol.io/docs

Quick Start

1. Install Publisher CLI

# macOS (Homebrew)
brew install modelcontextprotocol/tap/mcp-publisher

# Or download pre-built binaries from GitHub releases
# https://github.com/modelcontextprotocol/registry/releases

2. Initialize Server Configuration

# Generate server.json template
mcp-publisher init

# Validate without publishing
mcp-publisher validate

3. Authenticate

# GitHub OAuth (interactive)
mcp-publisher login github

# GitHub Actions OIDC (automated)
mcp-publisher login github-oidc

# DNS verification
mcp-publisher login dns --domain example.com --private-key-file key.pem

# HTTP verification
mcp-publisher login http --domain example.com --private-key-file key.pem

4. Publish

mcp-publisher publish

Publisher CLI Commands

| Command | Description | |---------|-------------| | init | Create server.json template (auto-detects project metadata) | | login | Authenticate with the registry | | logout | Clear saved authentication | | publish | Publish server.json to the registry | | validate | Validate server.json without publishing | | --version | Display version, commit hash, and build timestamp |

Server Configuration (server.json)

Basic Structure

{
  "$schema": "https://registry.modelcontextprotocol.io/schemas/server.json",
  "name": "io.github.username/server-name",
  "title": "My MCP Server",
  "description": "A useful MCP server for...",
  "version": "1.0.0",
  "repository": "https://github.com/username/server-name",
  "website": "https://example.com",
  "icon": "https://example.com/icon.png",
  "packages": [...],
  "remotes": [...]
}

Name Format Requirements

| Auth Method | Name Pattern | Example | |-------------|--------------|---------| | GitHub | io.github.username/* | io.github.alice/weather-server | | GitHub Org | io.github.orgname/* | io.github.anthropic/everything | | Domain | com.example.*/* | io.modelcontextprotocol/everything |

Constraints:

Pattern: ^[a-zA-Z0-9.-]+/[a-zA-Z0-9._-]+$
Length: 3-200 characters
Must contain exactly one forward slash

Description Limits

Length: 1-100 characters
Keep concise and descriptive

Package Types

npm Packages

{
  "packages": [{
    "registryType": "npm",
    "name": "@username/my-server",
    "version": "1.0.0",
    "runtime": "node",
    "runtimeArgs": ["--experimental-fetch"]
  }]
}

Verification: Add mcpName to package.json matching server name.

{
  "name": "@username/my-server",
  "mcpName": "io.github.username/my-server"
}

PyPI Packages

{
  "packages": [{
    "registryType": "pypi",
    "name": "my-mcp-server",
    "version": "1.0.0",
    "runtime": "python"
  }]
}

Verification: Add to README (can be hidden in comment):

mcp-name: io.github.username/my-server

NuGet Packages

{
  "packages": [{
    "registryType": "nuget",
    "name": "MyMcpServer",
    "version": "1.0.0",
    "runtime": "dotnet"
  }]
}

Verification: Same as PyPI - mcp-name in README.

Docker/OCI Images

{
  "packages": [{
    "registryType": "oci",
    "identifier": "ghcr.io/username/my-server:1.0.0"
  }]
}

Supported Registries:

Docker Hub
GitHub Container Registry (ghcr.io)
Google Artifact Registry
Azure Container Registry
Microsoft Container Registry

Verification: Add Dockerfile label:

LABEL io.modelcontextprotocol.server.name="io.github.username/my-server"

MCPB Packages (Binary Releases)

{
  "packages": [{
    "registryType": "mcpb",
    "identifier": "https://github.com/username/server/releases/download/v1.0.0/server-mcp-linux-amd64",
    "fileSha256": "abc123..."
  }]
}

Requirements:

URL must contain the string "mcp"
SHA256 checksum required for integrity

Remote Servers

Streamable HTTP (Recommended)

{
  "remotes": [{
    "type": "streamable-http",
    "url": "https://api.example.com/mcp"
  }]
}

Server-Sent Events (SSE)

{
  "remotes": [{
    "type": "sse",
    "url": "https://api.example.com/mcp/sse"
  }]
}

URL Template Variables

Support dynamic configuration for multi-tenant deployments:

{
  "remotes": [{
    "type": "streamable-http",
    "url": "https://api.example.com/{tenant_id}/mcp",
    "variables": {
      "tenant_id": {
        "description": "Your organization's tenant identifier",
        "isRequired": true
      }
    }
  }]
}

Variable Properties:

description - Explains the variable's purpose
isRequired - Marks mandatory fields
default - Provides fallback values
choices - Offers predefined options
isSecret - Indicates sensitive data

HTTP Headers

Configure authentication headers for clients:

{
  "remotes": [{
    "type": "streamable-http",
    "url": "https://api.example.com/mcp",
    "headers": [{
      "name": "Authorization",
      "description": "Bearer token for API access",
      "isRequired": true,
      "isSecret": true
    }]
  }]
}

Hybrid Deployment

Combine remote and local packages in same server.json:

{
  "packages": [{
    "registryType": "npm",
    "name": "@example/server"
  }],
  "remotes": [{
    "type": "streamable-http",
    "url": "https://api.example.com/mcp"
  }]
}

Authentication Methods

GitHub OAuth

Interactive browser-based authentication:

mcp-publisher login github
# Opens browser for GitHub authorization
# Enter device code when prompted

GitHub OIDC (CI/CD)

For automated publishing from GitHub Actions:

mcp-publisher login github-oidc

Requires id-token: write permission in workflow.

DNS Verification

Domain ownership via TXT record:

Generate Ed25519, ECDSA P-384, or cloud KMS key pair

Create TXT record:

_mcp-registry.example.com TXT "v=MCPv1; k=ed25519; p=${PUBLIC_KEY}"

mcp-publisher login dns --domain example.com --private-key-file key.pem

HTTP Verification

Domain ownership via well-known file:

Generate key pair
Host file at https://example.com/.well-known/mcp-registry-auth:
```
v=MCPv1; k=ed25519; p=${PUBLIC_KEY}
```

mcp-publisher login http --domain example.com --private-key-file key.pem

Versioning

Requirements

Version must be unique for each publication
Once published, version and metadata are immutable
Version range indicators are prohibited (^, ~, >=, *)

Recommended Formats

| Format | Example | |--------|---------| | Semantic | 1.0.0 | | Prerelease | 2.1.3-alpha, 1.0.0-beta.1 | | Date-based | 2025.11.25 | | Prefixed | v1.0 |

Best Practices

Align server version with underlying package versions
For remote APIs, match server version to API version
Use prerelease notation (1.2.3-1) for metadata-only updates

GitHub Actions Integration

OIDC Authentication (Recommended)

name: Publish MCP Server
on:
  push:
    tags:
      - 'v*'

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          registry-url: 'https://registry.npmjs.org'

      - name: Install dependencies
        run: npm ci

      - name: Build and test
        run: |
          npm run build
          npm test

      - name: Publish to npm
        run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

      - name: Install mcp-publisher
        run: |
          curl -L https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher-linux-amd64 -o mcp-publisher
          chmod +x mcp-publisher

      - name: Publish to MCP Registry
        run: |
          ./mcp-publisher login github-oidc
          ./mcp-publisher publish

GitHub PAT Authentication

- name: Publish to MCP Registry
  run: |
    ./mcp-publisher login github --token ${{ secrets.MCP_GITHUB_TOKEN }}
    ./mcp-publisher publish

Required scopes: read:org, read:user

DNS Authentication

- name: Publish to MCP Registry
  run: |
    echo "${{ secrets.MCP_PRIVATE_KEY }}" > key.pem
    ./mcp-publisher login dns --domain example.com --private-key-file key.pem
    ./mcp-publisher publish
    rm key.pem

Triggering Deployment

git tag v1.0.0
git push origin v1.0.0

API Reference

List Servers

GET https://registry.modelcontextprotocol.io/api/v0/servers

Get Server

GET https://registry.modelcontextprotocol.io/api/v0/servers/{name}

Search Servers

GET https://registry.modelcontextprotocol.io/api/v0/servers?q=weather

Response Structure

{
  "servers": [{
    "name": "io.github.username/weather-server",
    "title": "Weather Server",
    "description": "Get weather data from any location",
    "version": "1.0.0",
    "packages": [...],
    "remotes": [...],
    "meta": {
      "io.modelcontextprotocol.registry": {
        "status": "published",
        "publishedAt": "2025-01-15T12:00:00Z",
        "updatedAt": "2025-01-15T12:00:00Z",
        "isLatest": true
      }
    }
  }],
  "meta": {
    "cursor": "abc123",
    "count": 100
  }
}

Development Setup

Prerequisites

Docker
Go 1.24.x
ko (container image builder)
golangci-lint v2.4.0

Running Locally

# Clone repository
git clone https://github.com/modelcontextprotocol/registry.git
cd registry

# Start development environment
make dev-compose
# Registry available at localhost:8080
# Database resets on restart

# Build publisher CLI
make publisher
./bin/mcp-publisher --help

Pre-built Container Images

Available at GitHub Container Registry:

Release tags
Continuous builds from main
Development builds

Publishing Workflow (npm Example)

Step 1: Add Verification Metadata

// package.json
{
  "name": "@username/my-mcp-server",
  "version": "1.0.0",
  "mcpName": "io.github.username/my-server"
}

Step 2: Publish to npm

npm run build
npm publish

Step 3: Create server.json

mcp-publisher init

Edit generated file:

{
  "$schema": "https://registry.modelcontextprotocol.io/schemas/server.json",
  "name": "io.github.username/my-server",
  "title": "My Server",
  "description": "Useful MCP server",
  "version": "1.0.0",
  "repository": "https://github.com/username/my-server",
  "packages": [{
    "registryType": "npm",
    "name": "@username/my-mcp-server",
    "version": "1.0.0",
    "runtime": "node"
  }]
}

Step 4: Authenticate and Publish

mcp-publisher login github
mcp-publisher publish

Step 5: Verify

curl "https://registry.modelcontextprotocol.io/api/v0/servers/io.github.username/my-server"

Troubleshooting

Authentication Errors

| Issue | Solution | |-------|----------| | Token expired | Re-run mcp-publisher login | | Namespace mismatch | Ensure server name matches your GitHub username/org | | OIDC permission denied | Add id-token: write to workflow |

Validation Failures

| Issue | Solution | |-------|----------| | Missing mcpName | Add mcpName to package.json matching server name | | Invalid version | Use semantic versioning without range indicators | | Name format error | Use reverse-DNS format with single slash |

Publishing Failures

| Issue | Solution | |-------|----------| | Package not found | Ensure npm/PyPI package is published first | | Verification failed | Check mcpName/mcp-name matches exactly | | Already published | Increment version number |

Community & Resources

Discord - Real-time discussion
GitHub Discussions - Product/technical requirements
GitHub Issues - Technical work tracking
API Docs - https://registry.modelcontextprotocol.io/docs

Maintainers

Adam Jones (Anthropic)
Tadas Antanavicius (PulseMCP)
Toby Padilla (GitHub)
Radoslav Dimitrov (Stacklok)

Resources

Registry: https://registry.modelcontextprotocol.io
GitHub: https://github.com/modelcontextprotocol/registry
MCP Specification: https://modelcontextprotocol.io
API Documentation: https://registry.modelcontextprotocol.io/docs