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

bash

# 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

bash

# Generate server.json template
mcp-publisher init

# Validate without publishing
mcp-publisher validate

3. Authenticate

bash

# 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

bash

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

json

{
  "$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

json

{
  "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.

json

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

PyPI Packages

json

{
  "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

json

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

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

Docker/OCI Images

json

{
  "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:

dockerfile

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

MCPB Packages (Binary Releases)

json

{
  "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)

json

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

Server-Sent Events (SSE)

json

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

URL Template Variables

Support dynamic configuration for multi-tenant deployments:

json

{
  "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:

json

{
  "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:

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:

bash

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

GitHub OIDC (CI/CD)

For automated publishing from GitHub Actions:

bash

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}"

bash

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}
```

bash

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)

yaml

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

yaml

- 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

yaml

- 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

bash

git tag v1.0.0
git push origin v1.0.0

API Reference

List Servers

bash

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

Get Server

bash

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

Search Servers

bash

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

Response Structure

json

{
  "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

bash

# 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

json

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

Step 2: Publish to npm

bash

npm run build
npm publish

Step 3: Create server.json

bash

mcp-publisher init

Edit generated file:

json

{
  "$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

bash

mcp-publisher login github
mcp-publisher publish

Step 5: Verify

bash

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

Search AI Tools

Install this agent skill to your Project

SKILL.md

MCP Registry

Key Features

API Status

Quick Start

1. Install Publisher CLI

2. Initialize Server Configuration

3. Authenticate

4. Publish

Publisher CLI Commands

Server Configuration (server.json)

Basic Structure

Name Format Requirements

Description Limits

Package Types

npm Packages

PyPI Packages

NuGet Packages

Docker/OCI Images

MCPB Packages (Binary Releases)

Remote Servers

Streamable HTTP (Recommended)

Server-Sent Events (SSE)

URL Template Variables

HTTP Headers

Hybrid Deployment

Authentication Methods

GitHub OAuth

GitHub OIDC (CI/CD)

DNS Verification

HTTP Verification

Versioning

Requirements

Recommended Formats

Best Practices

GitHub Actions Integration

OIDC Authentication (Recommended)

GitHub PAT Authentication

DNS Authentication

Triggering Deployment

API Reference

List Servers

Get Server

Search Servers

Response Structure

Development Setup

Prerequisites

Running Locally

Pre-built Container Images

Publishing Workflow (npm Example)

Step 1: Add Verification Metadata

Step 2: Publish to npm

Step 3: Create server.json

Step 4: Authenticate and Publish

Step 5: Verify

Troubleshooting

Authentication Errors

Validation Failures

Publishing Failures

Community & Resources

Maintainers

Resources