modelcontextprotocol/registry
Watch
1
0
Fork
You've already forked registry
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Prepare docs for modelcontextprotocol.io (#728)

Browse source 
This PR reorganizes and extends the existing documentation in
preparation for publishing on https://modelcontextprotocol.io/.

The current plan is for docs to remain in this repo, and be synced to
the `modelcontextprotocol/modelcontextprotocol` whenever necessary
(e.g., accompanying a release of the registry). I have included a script
in
https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1725
(`bin/pull-registry-docs.sh`) that can be run manually to perform the
sync.

If we later decide to permanently move the docs to the
`modelcontextprotocol/modelcontextprotocol` repo, that also works.

This PR puts all https://modelcontextprotocol.io/ docs into
`docs/modelcontextprotocol-io/`. Docs outside that subdirectory, such as
`docs/administration/admin-operations.md`, are intended to be accessible
solely via this repo. One major exception is the
`docs/reference/server-json/` subdirectory, which will depend on the
resolution of
https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1649.
However, I think we could address that in a follow-up PR.

---------

Co-authored-by: Adam Jones <adamj+git@anthropic.com>
Co-authored-by: Claude <noreply@anthropic.com>
This commit is contained in:
Jonathan Hefner 2025-11-18 11:22:31 -06:00 • committed by GitHub
commit 43d41a242e
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
34 changed files with 1606 additions and 1397 deletions
Download patch file Download diff file Expand all files Collapse all files

146
docs/administration/admin-operations.md Normal file
View file

@ -0,0 +1,146 @@
# Admin Operations
This is a brief guide for admins and moderators managing content on the registry. All actions should be taken in line with the [moderation guidelines](moderation-guidelines.md).
## Prerequisites
- Admin account with @modelcontextprotocol.io email
- If you are a maintainer and would like an account, ask in the Discord
- `gcloud` CLI installed and configured
- `curl` and `jq` installed
## Authentication
```bash
# Run this, then run the export command it outputs
./tools/admin/auth.sh
```
## Edit a Specific Server Version
Use this when you need to modify details of a specific version (e.g., fix description, update status, modify packages).
### Step 1: Download Specific Version
```bash
export SERVER_NAME="<server-name>" # e.g., "com.example/my-server"
export VERSION="<version-string>" # e.g., "1.0.0" (optional, defaults to latest)
# URL encode the server name (replace / with %2F)
ENCODED_SERVER_NAME=$(echo "$SERVER_NAME" | sed 's|/|%2F|g')
# Get specific version
curl -s "https://registry.modelcontextprotocol.io/v0/servers/${ENCODED_SERVER_NAME}/versions/${VERSION}" > server.json
# Or get latest version (omit /versions/VERSION)
curl -s "https://registry.modelcontextprotocol.io/v0/servers/${ENCODED_SERVER_NAME}" > server.json
```
### Step 2: Make Changes
Open `server.json` and edit the specific version details. You cannot change the server name or version number.
### Step 3: Update Version
```bash
# Update specific version
curl -X PUT "https://registry.modelcontextprotocol.io/v0/servers/${ENCODED_SERVER_NAME}/versions/${VERSION}" \
-H "Authorization: Bearer ${REGISTRY_TOKEN}" \
-H "Content-Type: application/json" \
-d "$(cat server.json)"
```
## Edit an Entire Server (All Versions)
Use this when you need to apply changes across all versions of a server (e.g., mark entire server as deleted, apply content scrubbing).
### Step 1: List All Versions
```bash
export SERVER_NAME="<server-name>" # e.g., "com.example/my-server"
ENCODED_SERVER_NAME=$(echo "$SERVER_NAME" | sed 's|/|%2F|g')
curl -s "https://registry.modelcontextprotocol.io/v0/servers/${ENCODED_SERVER_NAME}/versions" > all_versions.json
```
### Step 2: Extract Versions
```bash
# Extract all versions from the server
jq -r '.servers[].server.version' all_versions.json > versions.txt
```
### Step 3: Apply Changes to All Versions
```bash
# For each version, apply changes using the edit endpoint
while read VERSION; do
echo "Processing version: $VERSION"
# Apply your changes here (e.g., set status to "deleted")
curl -X PUT "https://registry.modelcontextprotocol.io/v0/servers/${ENCODED_SERVER_NAME}/versions/${VERSION}?status=deleted" \
-H "Authorization: Bearer ${REGISTRY_TOKEN}" \
-H "Content-Type: application/json"
done < versions.txt
# Clean up temporary files
rm versions.txt all_versions.json
```
## Quick Operations
### Get Latest Version of a Server
```bash
export SERVER_NAME="<server-name>" # e.g., "com.example/my-server"
ENCODED_SERVER_NAME=$(echo "$SERVER_NAME" | sed 's|/|%2F|g')
curl -s "https://registry.modelcontextprotocol.io/v0/servers/${ENCODED_SERVER_NAME}" > latest_version.json
export VERSION=$(jq -r '.server.version' latest_version.json)
echo "Latest version: $VERSION"
```
### Takedown a Specific Version
```bash
export SERVER_NAME="<server-name>" # e.g., "com.example/my-server"
export VERSION="<version-string>" # e.g., "1.0.0"
export REGISTRY_TOKEN="<your-token>"
REGISTRY_TOKEN="$REGISTRY_TOKEN" SERVER_NAME="$SERVER_NAME" VERSION="$VERSION" ./tools/admin/takedown.sh
```
### Takedown Latest Version (Entire Server)
```bash
export SERVER_NAME="<server-name>" # e.g., "com.example/my-server"
export REGISTRY_TOKEN="<your-token>"
# This marks the latest version as deleted
REGISTRY_TOKEN="$REGISTRY_TOKEN" SERVER_NAME="$SERVER_NAME" ./tools/admin/takedown.sh
```
### Takedown All Versions of a Server
```bash
export SERVER_NAME="<server-name>" # e.g., "com.example/my-server"
export REGISTRY_TOKEN="<your-token>"
ENCODED_SERVER_NAME=$(echo "$SERVER_NAME" | sed 's|/|%2F|g')
# Get all versions and takedown each one
curl -s "https://registry.modelcontextprotocol.io/v0/servers/${ENCODED_SERVER_NAME}/versions" | \
jq -r '.servers[].server.version' | \
while read VERSION; do
echo "Taking down version: $VERSION"
REGISTRY_TOKEN="$REGISTRY_TOKEN" SERVER_NAME="$SERVER_NAME" VERSION="$VERSION" ./tools/admin/takedown.sh
done
```
## Notes
- **Version-specific changes**: Only affect that particular version
- **Server-wide changes**: Must be applied to each version individually
- **Content scrubbing**: Use the version-specific edit workflow to scrub sensitive content
- **Server name**: Cannot be changed in any version (it's the immutable identifier)

56
docs/contributing/add-package-registry.md Normal file
View file

@ -0,0 +1,56 @@
# Adding a new package registry
The MCP Registry project is a **metaregistry**, meaning that it hosts metadata for MCP servers but does not host the code for the servers directly.
For local MCP servers, the MCP Registry has pointers in the `packages` node of the [`server.json`](../../reference/server-json/generic-server-json.md) schema that refer to packages in supported package managers.
The list of supported package managers for hosting MCP servers is defined by the `properties.packages[N].properties.registryType` string enum in the [`server.json` schema](../../reference/server-json/server.schema.json). For example, this could be "npm" (for npmjs.com packages) or "pypi" (for PyPI packages).
For remote MCP servers, the package registry is not relevant. The MCP client consumes the server via a URL instead of by downloading and running a package. In other words, this document only applies to local MCP servers.
For the sake of illustration, this document will use npm (the Node.js package manager) as an example at each step.
## Prerequisites
The package registry must meet the following requirements:
1. The package registry supports packaging and executing CLI apps. Local MCP servers use the [stdio transport](https://modelcontextprotocol.io/docs/concepts/transports#standard-input%2Foutput-stdio).
- npm CLI tools typically express their CLI commands in the [`bin` property of the package.json](https://docs.npmjs.com/cli/v11/configuring-npm/package-json#bin)
1. The package registry (or associated client tooling) has a widely accepted **single-shot** CLI command.
- npm's `npx` tool executes CLI commands using a [documented execution heuristic](https://docs.npmjs.com/cli/v11/commands/npx#description)
- For example, the MCP client can map the `server.json` metadata to an `npx` CLI execution, with args and environment variables populated via user input.
1. The package registry supports anonymous package downloads. This allows the MCP client software to use the metadata found in the MCP registry to discover, download, and execute package-based local MCP servers with minimal user intervention.
- `npx` by default connects to the public npmjs.com registry, allowing simple consumption of public npm packages.
1. The package registry should support a validation mechanism to verify ownership of the server name. This prevents misattribution and ensures that only the actual package owner can reference their packages in server registrations. For example:
- npm requires an `mcpName` field in `package.json` that matches the server name being registered
- PyPI requires a `mcp-name:` line in the package README/description
- Each registry type must implement a validation mechanism accessible via public API
## Steps
These steps may evolve as additional validations or details are discovered and mandated.
1. [Create a feature request issue](https://github.com/modelcontextprotocol/registry/issues/new?template=feature_request.md) on the MCP Registry repository to begin the discussion about adding the package registry.
- Example for NuGet: https://github.com/modelcontextprotocol/registry/issues/126
1. Open a PR with the following changes:
- Update the [`server.json` schema](../../reference/server-json/server.schema.json)
- Add your package registry name to the `registryType` example array.
- Add your package registry base url to the `registryBaseUrl` example array.
- Add the single-shot CLI command name to the `runtimeHint` example value array.
- Update the [`openapi.yaml`](../../reference/api/openapi.yaml)
- Add your package registry name to the `registryType` enum value array.
- Add your package registry base url to the `registryBaseUrl` enum value array.
- Add the single-shot CLI command name to the `runtimeHint` example value array.
- Add a sample, minimal `server.json` to the [`server.json` examples](../../reference/server-json/generic-server-json.md).
- Implement a registry validator:
- Create a new validator file: `internal/validators/registries/yourregistry.go`, following the pattern of existing validators. Examples:
- **npm**: Checks for an `mcpName` field in `package.json` that matches the server name
- **PyPI**: Searches for `mcp-name: server-name` format in the package README content
- **NuGet**: Looks for `mcp-name: server-name` format in the package README file
- **Docker/OCI**: Validates a Docker image label `io.modelcontextprotocol.server.name` in the image manifest
- Add corresponding unit tests: `internal/validators/registries/yourregistry_test.go`
- Register your validator in `internal/validators/validators.go`
- Update the publishing documentation:
- Add a new publishing guide: `docs/guides/publishing/publish-[yourregistry].md`, following the pattern of existing publishing guides (e.g., `publish-npm.md`, `publish-pypi.md`)
- Include instructions on how to prepare packages for your registry, including any specific validation requirements
- Update `docs/guides/publishing/README.md` to reference your new publishing guide

60
docs/contributing/releasing.md Normal file
View file

@ -0,0 +1,60 @@
# Release Guide
## Creating a Release
1. **Go to GitHub**: Navigate to https://github.com/modelcontextprotocol/registry/releases
2. **Click "Draft a new release"**
3. **Choose a tag**: Click "Choose a tag" and type a new semantic version that follows the last one available (e.g., `v1.0.0`)
5. **Generate notes**: Click "Generate release notes" to auto-populate the name and description
6. **Publish**: Click "Publish release"
The release workflow will automatically:
- Build binaries for 6 platforms (Linux, macOS, Windows × amd64, arm64)
- Create and push Docker images with `:latest` and `:X.Y.Z` tags (note: no 'v' prefix)
- Attach all artifacts to the GitHub release
- Generate checksums and signatures
## After Release
- Docker images will be available at:
- `ghcr.io/modelcontextprotocol/registry:latest` - Latest stable release
- `ghcr.io/modelcontextprotocol/registry:X.Y.Z` - Specific release version (note: no 'v' prefix)
- Binaries can be downloaded from the GitHub release page
## Deploying to Production
Releases do not automatically deploy to production. To deploy a release:
1. Update `mcp-registry:imageTag` in `deploy/Pulumi.gcpProd.yaml` to the desired version (e.g., `1.2.3` - note: no 'v' prefix)
2. Commit and push the change to the `main` branch (either through a PR or by pushing directly to main)
3. The [deploy-production.yml](../../../.github/workflows/deploy-production.yml) workflow will automatically trigger and deploy the specified version
See the [deployment documentation](../../../deploy/README.md) for more details.
## Staging
Staging auto-deploys from `main` via [deploy-staging.yml](../../../.github/workflows/deploy-staging.yml). It always runs the latest `main` branch code.
## Rollback
To rollback production, update `deploy/Pulumi.gcpProd.yaml` to the previous version and push.
**Note:** Rollbacks may not work as expected if the release included database migrations, since migrations are not automatically reversed.
## Docker Image Tags
The registry publishes different Docker image tags for different use cases:
- **`:latest`** - Latest stable release (updated only on releases)
- **`:X.Y.Z`** - Specific release versions (e.g., `:1.0.0` - note: no 'v' prefix)
- **`:main`** - Rolling tag updated on every push to main branch (continuous deployment)
- **`:main-YYYYMMDD-sha`** - Specific development builds from main branch
**Note:** Git release tags include the 'v' prefix (e.g., `v1.0.0`), but Docker image tags follow the standard Docker convention and do not include the 'v' prefix (e.g., `1.0.0`).
## Versioning
We use semantic versioning (SemVer):
- `v1.0.0` - Major release with breaking changes
- `v1.1.0` - Minor release with new features
- `v1.0.1` - Patch release with bug fixes

39
docs/design/design-principles.md Normal file
View file

@ -0,0 +1,39 @@
# MCP Registry Design Principles
These are the core constraints that guide the design of the MCP Registry. They are not exhaustive, but they are the most important principles that we will use to evaluate design decisions.
## 1. Single Source of Truth
The registry serves as the authoritative metadata repository for publicly-available MCP servers, both locally-run and remote, open source and closed source. Server creators publish once, and all consumers (MCP clients, aggregators, etc.) reference the same canonical data.
## 2. Minimal Operational Burden
- Design for low maintenance and operational overhead
- Delegate complexity to existing services where possible (GitHub for auth, npm/PyPI/NuGet for packages)
- Avoid features that require constant human intervention or moderation
- Build for reasonable downtime tolerance (24h acceptable) by having consumers cache data for their end-users
## 3. Vendor Neutrality
- No preferential treatment for specific servers or organizations
- No built-in ranking, curation, or quality judgments
- Let consumers (MCP clients, aggregators) make their own curation decisions
## 4. Meets Industry Security Standards
- Leverage existing package registries (npm, PyPI, NuGet, Docker Hub, etc.) for source code distribution, obviating the need to reinvent source code security
- Use mechanisms like DNS verification, OAuth to provide base layer of authentication and trust
- Implement rate limiting, field validation, and blacklisting to prevent abuse
## 6. Reusable, Extensible Shapes; Not Infrastructure
- API shapes (OpenAPI, server.json) designed for reuse
- Enable private/internal registries using same formats
- Don't mandate infrastructure reuse - focus on interface compatibility
## 7. Progressive Enhancement
- Start with MVP that provides immediate value
- Build foundation that supports future features
- Don't over-engineer for hypothetical needs
- Each milestone should be independently valuable

42467
docs/design/dev-summit-2025-05-registry-goals-presentation.pdf Normal file
View file

File diff suppressed because one or more lines are too long

BIN
docs/design/dev-summit-2025-10-registry-status-presentation.pdf Normal file
View file

Binary file not shown.

4
docs/design/ecosystem-diagram.excalidraw.svg Normal file
View file

File diff suppressed because one or more lines are too long
Side by side

After

Width:  |  Height:  |  Size: 2.7 MiB

56
docs/design/ecosystem-vision.md Normal file
View file

@ -0,0 +1,56 @@
# Ecosystem Vision
How the MCP Registry fits into the broader ecosystem and our vision for the future.
## The Registry Ecosystem
The MCP registry provides MCP clients with a list of MCP servers, like an app store for MCP servers. (In the future it might do more, like also hosting a list of clients).
There are two parts to the registry project:
1. 🟦 **The MCP registry spec**: An [API specification](../reference/api/) that allows anyone to implement a registry.
2. 🟥 **The Official MCP registry**: A hosted registry following the MCP registry spec at [`registry.modelcontextprotocol.io`](https://registry.modelcontextprotocol.io). This serves as the **authoritative repository** for publicly-available MCP servers. Server creators publish once, and all consumers (MCP clients, aggregators, marketplaces) reference the same canonical data. This is owned by the MCP open-source community, backed by major trusted contributors to the MCP ecosystem such as Anthropic, GitHub, PulseMCP and Microsoft.
The registry is built around the [`server.json`](../reference/server-json/) format - a standardized way to describe MCP servers that works across discovery, initialization, and packaging scenarios.
In time, we expect the ecosystem to look a bit like this:
![](./ecosystem-diagram.excalidraw.svg)
Note that MCP registries are _metaregistries_. They host metadata about packages, but not the package code or binaries. Instead, they reference other package registries (like NPM, PyPi or Docker) for this.
Additionally, we expect clients pull from _subregistries_. These subregistries add value to the registry ecosystem by providing curation, or extending it with additional metadata. The Official MCP registry expects a lot of API requests from ETL jobs from these subregistries.
## Registry vs Package Registry
Key distinction: MCP Registries are **metaregistries**.
- **Package registries** (npm, PyPI, Docker Hub) host actual code/binaries
- **The MCP Registry** hosts metadata pointing to those packages
```
MCP Registry: "weather-server v1.2.0 is at npm:weather-mcp"
NPM Registry: [actual weather-mcp package code]
```
## Official vs Community Registries
**Official MCP Registry** (`registry.modelcontextprotocol.io`):
- Canonical source for publicly-available servers
- Community-owned, backed by trusted contributors
- Focuses on discoverability and basic metadata
**Subregistries** (Smithery, PulseMCP, etc.):
- Add value through curation, ratings, enhanced metadata
- ETL from official registry + additional annotations
- Serve specific communities or use cases
## How Servers Are Represented
Each server entry contains:
- **Identity**: Unique name (`io.github.user/server-name`)
- **Packages**: Where to download it (`npm`, `pypi`, `docker`, etc.)
- **Runtime**: How to execute it (args, env vars)
- **Metadata**: Description, capabilities, version
This is stored in a standardized `server.json` format that works across discovery, installation, and execution.

31
docs/design/roadmap.md Normal file
View file

@ -0,0 +1,31 @@
# MCP Registry Roadmap
This is a high-level roadmap for the MCP Registry. It is subject to change and not exhaustive, but it outlines the general thinking of the sequencing and scope of our work in this repository.
This roadmap may occasionally drift out of date. Please review [Issues](https://github.com/modelcontextprotocol/registry/issues) (and corresponding Labels) for the most current work in progress.
## Current Status
The initial version of the MCP Registry is actively being developed. The initial focus is on delivering a REST API to which server creators can publish, and aggregator/marketplace consumers can ETL.
## Phase 1: MVP/Go-Live (Current Focus)
See the [go-live blocker issues](https://github.com/modelcontextprotocol/registry/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22go-live%20blocker%22).
## Backlog (Future Work, may be moved to out of scope)
- [ ] UI implementation
- [ ] Store and surface other data besides servers (e.g. [clients](https://modelcontextprotocol.io/clients), resources)
- [ ] Download count tracking
- [ ] Internationalization (i18n)
## Out of Scope (Not Planned)
- **Source code hosting**: The registry will never host actual server code
- **Quality rankings**: No built-in server quality assessments or rankings
- **Curation**: No editorial decisions about which servers are "better"
- **Unified runtime**: Not solving how servers are executed
- **Server hosting**: The registry does not provide hosting for servers
- **Search engine**: The registry will not provide a commercial grade search engine for servers
- **Server tags or categories**: Not supported, to reduce moderation burden
- **Server rankings**: The registry will not rank servers by subjective measures of quality

202
docs/design/tech-architecture.md Normal file
View file

@ -0,0 +1,202 @@
# MCP Registry Technical Architecture
This document describes the technical architecture of the MCP Registry, including system components, deployment strategies, and data flows.
## System Overview
The MCP Registry is designed as a lightweight metadata service that bridges MCP server creators with consumers (MCP clients and aggregators).
## Core Components
### REST API (Go)
The main application server implemented in Go, providing:
- Public read endpoints for server discovery
- Authenticated write endpoints for server publication
- GitHub OAuth integration (extensible to other providers)
- DNS verification system (optional for custom namespaces)
### Database (PostgreSQL)
Primary data store for:
- Versioned server metadata (server.json contents)
- User authentication state
- DNS verification records
### CDN Layer
Critical for scalability:
- Caches all public read endpoints
- Reduces load on origin servers
- Enables global distribution
- Designed for daily consumer polling patterns
### CLI Tool
Developer interface for:
- Server publication workflow
- GitHub OAuth flow
- DNS verification
## Deployment Architecture
### Kubernetes Deployment (Helm)
The registry is designed to run on Kubernetes using Helm charts:
```mermaid
graph TB
subgraph "Kubernetes Cluster"
subgraph "Namespace: mcp-registry"
subgraph "Registry Service"
LB[Load Balancer<br/>:80]
RS[Registry Service<br/>:8080]
RP1[Registry Pod 1]
RP2[Registry Pod 2]
RP3[Registry Pod N]
end
subgraph "Database Service"
DBS[DB Service<br/>:27017]
SS[StatefulSet]
PV[Persistent Volume]
end
subgraph "Secrets"
GHS[GitHub OAuth Secret]
end
end
end
LB --> RS
RS --> RP1
RS --> RP2
RS --> RP3
RP1 --> DBS
RP2 --> DBS
RP3 --> DBS
DBS --> SS
SS --> PV
RP1 -.-> GHS
RP2 -.-> GHS
RP3 -.-> GHS
```
## Data Flow Patterns
### 1. Server Publication Flow
```mermaid
sequenceDiagram
participant Dev as Developer
participant CLI as CLI Tool
participant API as Registry API
participant DB as Database
participant GH as GitHub
participant DNS as DNS Provider
Dev->>CLI: mcp publish server.json
CLI->>CLI: Validate server.json
CLI->>GH: OAuth flow
GH-->>CLI: Access token
CLI->>API: POST /servers
API->>GH: Verify token
API->>DNS: Verify domain (if applicable)
API->>DB: Store metadata
API-->>CLI: Success
CLI-->>Dev: Published!
```
### 2. Consumer Discovery Flow
```mermaid
sequenceDiagram
participant Client as MCP Client Host App
participant INT as Intermediary<br/>(Marketplace/Aggregator)
participant CDN as CDN Cache
participant API as Registry API
participant DB as Database
Note over INT,CDN: Daily ETL Process
INT->>CDN: GET /servers
alt Cache Hit
CDN-->>INT: Cached response
else Cache Miss
CDN->>API: GET /servers
API->>DB: Query servers
DB-->>API: Server list
API-->>CDN: Response + cache headers
CDN-->>INT: Response
end
INT->>INT: Process & enhance data
INT->>INT: Store in local cache
Note over Client,INT: Real-time Client Access
Client->>INT: Request server list
INT-->>Client: Curated/enhanced data
```
### 3. DNS Verification Flow
```mermaid
sequenceDiagram
participant User as User
participant CLI as CLI Tool
participant API as Registry API
participant DNS as DNS Provider
participant DB as Database
User->>CLI: mcp verify-domain example.com
CLI->>API: POST /verify-domain
API->>API: Generate verification token
API->>DB: Store pending verification
API-->>CLI: TXT record: mcp-verify=abc123
CLI-->>User: Add TXT record to DNS
User->>DNS: Configure TXT record
User->>CLI: Confirm added
CLI->>API: POST /verify-domain/check
API->>DNS: Query TXT records
DNS-->>API: TXT records
API->>API: Validate token
API->>DB: Store verification
API-->>CLI: Domain verified
CLI-->>User: Success!
```
### 4. Admin OIDC Authentication Flow
For registry administration, users with @modelcontextprotocol.io Google Cloud Identity accounts can authenticate using OIDC:
```mermaid
sequenceDiagram
participant Admin as Admin User
participant CLI as Admin CLI
participant GCP as Google Cloud Identity
participant API as Registry API
Admin->>CLI: Request admin token
CLI->>GCP: gcloud auth print-identity-token --audiences=mcp-registry
GCP-->>CLI: ID Token (with hd: "modelcontextprotocol.io")
CLI->>API: POST /v0/auth/oidc {"oidc_token": "eyJ..."}
API->>GCP: Verify token signature (JWKS)
API->>API: Validate claims (issuer, audience, hd)
API->>API: Grant admin permissions (edit: *, publish: *)
API-->>CLI: Registry JWT Token
CLI->>API: POST /admin/* (with Registry JWT)
API->>API: Validate JWT + permissions
API-->>CLI: Admin operation success
```
**Usage:**
```bash
# Get Google Cloud Identity token
ID_TOKEN=$(gcloud auth print-identity-token)
# Exchange for Registry JWT token
REGISTRY_TOKEN=$(curl -X POST /v0/auth/oidc \
-H "Content-Type: application/json" \
-d '{"oidc_token": "'$ID_TOKEN'"}' | jq -r .registry_token)
# Use for admin operations
curl -H "Authorization: Bearer $REGISTRY_TOKEN" /v0/...
```

10
docs/explanations/README.md
View file

@ -1,10 +0,0 @@
# Explanations
Understanding-oriented documentation that clarifies and illuminates the MCP Registry.
- [Design principles](design-principles.md)
- [Ecosystem vision](ecosystem-vision.md)
- [Roadmap](roadmap.md)
- [Tech architecture](tech-architecture.md)
- [Namespacing](namespacing.md)
- [Versioning](versioning.md)

45
docs/explanations/namespacing.md
View file

@ -1,45 +0,0 @@
# Namespacing and Security
Namespacing prevents name squatting, makes impersonation and typo squatting much harder, and provides attribution through domain-based identity.
For practical steps on how to authenticate for different namespaces, see the [publishing guide](../guides/publishing/publish-server.md#authenticate).
## Namespace Format
All server names follow reverse-DNS format. Examples:
- `io.github.alice/weather-server` - GitHub user `alice`
- `com.acme/internal-tool` - Company domain `acme.com`
- `org.nonprofit.research/data-analyzer` - Subdomain `research.nonprofit.org`
## Security Model
### Ownership Verification
Publishing to a namespace requires proving you control the corresponding identity:
**GitHub namespaces** (`io.github.*`):
- OAuth login to GitHub account/organization
- OIDC tokens in GitHub Actions workflows
**Domain namespaces** (`com.company.*`):
- DNS verification: TXT record at `company.com`
- HTTP verification: File at `https://company.com/.well-known/mcp-registry-auth`
## Namespace Scoping
Different authentication methods grant different namespace access:
**GitHub OAuth/OIDC**:
- `io.github.username/*` (for personal accounts)
- `io.github.orgname/*` (for organizations)
**DNS verification**:
- `com.domain/*` and `com.domain.*/*` (domain + all subdomains)
**HTTP verification**:
- `com.domain/*` only (exact domain, no subdomains)
## Limitations
**Domain ownership changes**: If someone loses/sells a domain, they lose publishing rights. Similarly if someone gains a domain, they gain publishing rights.
**Package validation**: Registry validates namespace ownership, but actual packages may still be malicious etc.

231
docs/explanations/versioning.md
View file

@ -1,231 +0,0 @@
# Server Versioning Guide
This document describes the versioning approach for MCP servers published to the registry.
## Overview
The MCP Registry supports flexible versioning while encouraging semantic versioning best practices. The registry attempts to parse versions as semantic versions for ordering and comparison, but falls back gracefully for non-semantic versions.
## Version Requirements
1. **Version String**: `version` MUST be a string up to 255 characters
2. **Uniqueness**: Each version for a given server name must be unique
3. **Immutability**: Once published, version metadata cannot be changed
## Best Practices
### 1. Use Semantic Versioning
Server authors SHOULD use [semantic versions](https://semver.org/) following the `MAJOR.MINOR.PATCH` format:
```json
{
"version": "1.2.3"
}
```
### 2. Align with Package Versions
Server authors SHOULD use versions aligned with their underlying packages to reduce confusion:
```json
{
"version": "1.2.3",
"packages": [{
"registry_name": "npm",
"name": "@myorg/my-server",
"version": "1.2.3"
}]
}
```
### 3. Multiple Registry Versions
If server authors expect to have multiple registry versions for the same package version, they SHOULD follow the semantic version spec using the prerelease label:
```json
{
"version": "1.2.3-1",
"packages": [{
"registry_name": "npm",
"name": "@myorg/my-server",
"version": "1.2.3"
}]
}
```
**Note**: According to semantic versioning, `1.2.3-1` is considered lower than `1.2.3`, so if you expect to need a `1.2.3-1`, you should publish that before `1.2.3`.
## Version Ordering and "Latest" Determination
### For Semantic Versions
The registry attempts to parse versions as semantic versions. If successful, it uses semantic version comparison rules to determine:
- Version ordering in lists
- Which version is marked as `isLatest`
### For Non-Semantic Versions
If version parsing as semantic version fails:
- The registry will always mark the version as latest (overriding any previous version)
- Clients should fall back to using publish timestamp for ordering
**Important Note**: This behavior means that for servers with mixed semantic and non-semantic versions, the `isLatest` flag may not align with the total ordering. A non-semantic version published after semantic versions will be marked as latest, even if semantic versions are considered "higher" in the ordering.
## Implementation Details
### Registry Behavior
1. **Validation**: Versions are validated for uniqueness within a server name
2. **Parsing**: The registry attempts to parse each version as semantic version
3. **Comparison**: Uses semantic version rules when possible, falls back to timestamp
4. **Latest Flag**: The `isLatest` field is set based on the comparison results
### Client Recommendations
Registry clients SHOULD:
1. Attempt to interpret versions as semantic versions when possible
2. Use the following ordering rules:
- If one version is marked as isLatest: it is later
- If both versions are valid semver: use semver comparison
- If neither are valid semver: use publish timestamp
- If one is semver and one is not: semver version is considered higher
## Examples
### Valid Semantic Versions
```javascript
"1.0.0" // Basic semantic version
"2.1.3-alpha" // Prerelease version
"1.0.0-beta.1" // Prerelease with numeric suffix
"3.0.0-rc.2" // Release candidate
```
### Non-Semantic Versions (Allowed)
```javascript
"v1.0" // Version with prefix
"2021.03.15" // Date-based versioning
```
### Not Allowed: Version Ranges
The registry requires specific versions for both the top-level `version` and any `packages[].version`. Version ranges or wildcard versions are rejected during publish, including but not limited to:
```javascript
"^1.2.3"
"~1.2.3"
">=1.2.3"
"<=1.2.3"
">1.2.3"
"<1.2.3"
"1.x"
"1.2.*"
"1 - 2"
"1.2 || 1.3"
```
### Alignment Examples
```json
{
"version": "1.2.3-1",
"packages": [{
"registry_name": "npm",
"name": "@myorg/k8s-server",
"version": "1.2.3"
}]
}
```
## Migration Path
Existing servers with non-semantic versions will continue to work without changes. However, to benefit from proper version ordering, server maintainers are encouraged to:
1. Adopt semantic versioning for new releases
2. Consider the ordering implications when transitioning from non-semantic to semantic versions
3. Use prerelease labels for registry-specific versioning needs
## Common Scenarios
### Standard Releases
**Package and server versions aligned**:
```json
{
"version": "1.2.3",
"packages": [
{
"registryType": "npm",
"identifier": "@myorg/server",
"version": "1.2.3"
}
]
}
```
### Registry-Only Updates
**Server metadata changes without package updates**:
```json
{
"version": "1.2.3-1",
"packages": [
{
"registryType": "npm",
"identifier": "@myorg/server",
"version": "1.2.3"
}
]
}
```
Note: `1.2.3-1` is considered lower than `1.2.3` in semver ordering. Publish prerelease versions first.
### Remote Server Versioning
**Remote servers without package dependencies**:
```json
{
"version": "2.1.0",
"remotes": [
{
"transport_type": "sse",
"url": "https://api.myservice.com/mcp/v2.1"
}
]
}
```
Version strategy options:
- **API versioning**: Match your service API version
- **Semantic versioning**: Standard semver for feature changes
- **Date-based**: `2024.03.15` for regular releases
### Multi-Package Versioning
**Different package versions**:
```json
{
"version": "1.3.0",
"packages": [
{
"registryType": "npm",
"identifier": "@myorg/server",
"version": "1.3.0"
},
{
"registryType": "oci",
"identifier": "myorg/server",
"version": "1.2.5"
}
]
}
```
Use server version to indicate the overall release.
## Decision Guide
**Which version strategy should I use?**
```
Do you have underlying packages?
├─ Yes: Align with package version
│ ├─ Same package version → Use package version
│ └─ Different package versions → Use highest + indicate relationship
└─ No (remote server): Choose versioning scheme
├─ API versioning → Match service API version
├─ Feature-based → Use semantic versioning
└─ Regular releases → Consider date-based versioning
```
## Future Considerations
This versioning approach is designed to be compatible with potential future changes to the MCP specification's `Implementation.version` field. Any SHOULD requirements introduced here may be proposed as updates to the specification through the SEP (Specification Enhancement Proposal) process.

21
docs/guides/README.md
View file

@ -1,21 +0,0 @@
# How-To Guides
Problem-oriented guides for specific tasks with the MCP Registry.
## Publishing Servers
- [Publish a server](publishing/publish-server.md)
- [GitHub Actions](publishing/github-actions.md)
## Consuming Registry Data
- [Use the REST API](consuming/use-rest-api.md)
## Contributing
- [Add package registry](contributing/add-package-registry.md)
## Administration
- [Admin operations](administration/admin-operations.md)
- [Moderation guidelines](administration/moderation-guidelines.md)

60
docs/guides/administration/moderation-guidelines.md
View file

@ -1,60 +0,0 @@
# Moderation Guidelines
Guidelines for server publishers on the Official MCP Registry.
## TL;DR
We're quite permissive! We only remove illegal content, malware, spam and completely broken servers.
We don't make guarantees about our moderation, and subregistries should take our data "as is", assuming minimal to no moderation.
## Scope
These guidelines apply to the **Official MCP Registry** at `registry.modelcontextprotocol.io`.
Subregistries may have their own moderation policies. If you have questions about content on a specific subregistry, please contact them directly.
## Disclaimer
We have limited active moderation capabilities, and this is a community supported projects. We largely rely on upstream package registries (like NPM, PyPi, and Docker) or downstream subregistries (like the GitHub MCP Registry) to do more in-depth moderation.
This means there may be content in the registry that should be removed under these guidelines, which we haven't yet removed. You should treat registry data accordingly.
## What We Remove
We'll remove servers that contain:
- Illegal content, which includes obscene content, copyright violations, and hacking tools
- Malware, regardless of intentions
- Spam, especially mass-created servers that disrupt the registry. Examples:
- The same server being submitted multiple times under different names.
- The server doesn't do anything but provide a fixed response with some marketing copy.
- The server description is stuffed with marketing copy, and its implementation is unrelated to its name or description.
- Non-functioning servers
## What We Don't Remove
Generally, we believe in keeping the registry open and pushing moderation to subregistries. We therefore **won't** remove servers that are:
- Low quality or buggy servers
- Servers with security vulnerabilities
- Do the same thing as other servers
- Provide or contain adult content
## How Removal Works
When we remove a server:
- It's set to "deleted" status but remains accessible via the API
- This allows subregistries to remove it from their indexes
- In extreme cases, we may overwrite or erase details of a server, e.g. where the metadata itself is unlawful
## Appeals
Think we made a mistake? Open an issue on our [GitHub repository](https://github.com/modelcontextprotocol/registry) with:
- The ID and name of your server
- Why you believe it doesn't meet the criteria for removal above
## Changes to this policy
We're still learning how to best run the MCP registry! As such, we might end up changing this policy in the future.

28
docs/guides/administration/releases.md
View file

@ -1,28 +0,0 @@
# Releases
## Creating a Release
1. Create a new release on [GitHub](https://github.com/modelcontextprotocol/registry/releases) with a semver tag (e.g., `v1.3.9`)
2. This triggers the [release workflow](.github/workflows/release.yml) which:
- Builds `registry` and `mcp-publisher` binaries for all platforms using GoReleaser
- Signs artifacts with cosign
- Generates SBOMs
- Builds and pushes container images to `ghcr.io/modelcontextprotocol/registry`
## Deploying to Production
1. Update `deploy/Pulumi.gcpProd.yaml` (e.g., through a PR or by pushing directly to main):
```yaml
mcp-registry:imageTag: 1.3.9
```
2. The [deploy-production workflow](.github/workflows/deploy-production.yml) automatically deploys
## Staging
Staging auto-deploys from `main` via [deploy-staging.yml](.github/workflows/deploy-staging.yml). It always runs the latest `main` branch code.
## Rollback
To rollback production, update `deploy/Pulumi.gcpProd.yaml` to the previous version and push.
**Note:** Rollbacks may not work as expected if the release included database migrations, since migrations are not automatically reversed.

112
docs/guides/consuming/use-rest-api.md
View file

@ -1,112 +0,0 @@
# Consuming Registry Data via REST API
Integration patterns and best practices for building applications that consume MCP registry data.
## Key details
**Base URL**: `https://registry.modelcontextprotocol.io`
**Authentication**: Not required for read-only access
**API Versions**:
- `/v0/` - Development version with latest features (may receive breaking changes)
- `/v0.1/` - Stable version (only backward-compatible changes)
**Recommendation**: Use `/v0.1/` for production applications requiring API stability. Both versions currently have identical functionality.
We may add breaking changes _only_ to `/v0/` in the future, and we reserve the possibility of deprecating `/v0/` entirely.
**Core endpoints:**
- **`GET /v0.1/servers`** - List all servers with pagination
- **`GET /v0.1/servers/{serverName}/versions`** - List all versions of a server
- **`GET /v0.1/servers/{serverName}/versions/{version}`** - Get specific version of server. Use the special version `latest` to get the latest version.
Server names and version strings should be URL-encoded in paths.
See the [interactive API documentation](https://registry.modelcontextprotocol.io/docs) for complete request/response schemas.
**Disclaimer**: The official registry provides no uptime or data durability guarantees. You should design your applications to handle service downtime via caching.
## Building a subregistry
**Create enhanced registries** - ETL official registry data and add your own metadata like ratings, security scans, or compatibility info.
For now we recommend scraping the `GET /v0/servers` endpoint on some regular basis. In the future we might provide a filter for updatedAt ([#291](https://github.com/modelcontextprotocol/registry/issues/291)) to get only recently changed servers.
### Pagination Example
The API uses cursor-based pagination. Here's how to fetch all servers:
```bash
# Initial request
curl "https://registry.modelcontextprotocol.io/v0/servers?limit=100"
```
```json
{
"servers": [...],
"metadata": {
"count": 100,
"nextCursor": "com.example/my-server:1.0.0"
}
}
```
```bash
# Next page using cursor
curl "https://registry.modelcontextprotocol.io/v0/servers?limit=100&cursor=com.example%2Fmy-server%3A1.0.0"
```
**Important**: Always URL-encode cursor values when using them in query parameters.
Servers are generally immutable, except for the `status` field which can be updated to `deleted` (among other states). For these packages, we recommend you also update the status field to `deleted` or remove the package from your registry quickly. This is because this status generally indicates it has violated our permissive [moderation guidelines](../administration/moderation-guidelines.md), suggesting it is illegal, malware or spam.
### Filtering & Enhancement
The official registry has a [permissive moderation policy](../administration/moderation-guidelines.md), so you may want to implement your own filtering on top of registry data.
You can also add custom metadata to servers using the `_meta` field. For example, user ratings, download counts, or security scan results. If you do this, we recommend you put this under a key that is namespaced to your organization, for example:
```json
{
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json",
"name": "io.github.yourname/weather-server",
"description": "MCP server for weather data access",
"status": "active",
"version": "1.0.0",
"packages": [
{
"registryType": "npm",
"identifier": "weather-mcp-server",
"version": "1.0.0"
}
],
"_meta": {
"com.example.subregistry/custom": {
"user_rating": 4.5,
"download_count": 12345,
"security_scan": {
"last_scanned": "2024-06-01T12:00:00Z",
"vulnerabilities_found": 0
}
}
}
}
```
### Providing an API
We recommend that your subregistry provides an API meeting the registry API specification, so it's easy for clients to switch between registries. See the [registry API documentation](../../reference/api/) for details.
## MCP Client Integration
**Convert registry data to client configuration** - Fetch servers and transform package information into your MCP client's config format.
We highly recommend using a subregistry rather than fetching data from the official registry directly. You might want to make this configurable so that users of your client can choose their preferred registry, for example we expect that some enterprise users may have their own registry.
Your client should gracefully handle registries that meet the minimum spec, i.e. avoid hard dependencies on `_meta` fields.
### Filtering
You likely should filter out servers that are not `active` in the `status` field.
### Running servers
You can use the `packages` or `remotes` field to determine how to run a server. More details of these fields are in the [server.json documentation](../../reference/server-json/generic-server-json.md).

152
docs/guides/publishing/github-actions.md
View file

@ -1,152 +0,0 @@
# Automate Publishing with GitHub Actions
Set up automated MCP server publishing using GitHub Actions.
## What You'll Learn
By the end of this tutorial, you'll have:
- A GitHub Actions workflow that automatically publishes your server
- Understanding of GitHub OIDC authentication
- Knowledge of best practices for automated publishing
- Working examples for Node.js, Python, and Docker projects
## Prerequisites
- Understand general publishing requirements like package verification (see the [publishing guide](publish-server.md))
- GitHub repository with your MCP server code
## GitHub Actions Setup
### Step 1: Create Workflow File
Create `.github/workflows/publish-mcp.yml`. Here's an example for NPM-based packages, but the MCP registry publishing steps are the same for all package types:
```yaml
name: Publish to MCP Registry
on:
push:
tags: ["v*"] # Triggers on version tags like v1.0.0
jobs:
publish:
runs-on: ubuntu-latest
permissions:
id-token: write # Required for OIDC authentication
contents: read
steps:
- name: Checkout code
uses: actions/checkout@v5
- name: Setup Node.js # Adjust for your language
uses: actions/setup-node@v5
with:
node-version: "lts/*"
- name: Install dependencies
run: npm ci
- name: Run tests
run: npm run test --if-present
- name: Build package
run: npm run build --if-present
- 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_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
- name: Login to MCP Registry
run: ./mcp-publisher login github-oidc
- name: Publish to MCP Registry
run: ./mcp-publisher publish
```
### Step 2: Configure Secrets
You don't need any secrets for publishing to the MCP Registry using GitHub OIDC.
However you might need to add secrets for your package registry. For example the workflow above needs a `NPM_TOKEN` (which you can add in Settings → Secrets and variables → Actions).
### Step 3: Tag and Release
Create a version tag to trigger the workflow:
```bash
git tag v1.0.0
git push origin v1.0.0
```
The workflow runs tests, builds your package, publishes to npm, and publishes to the MCP Registry.
## Authentication Methods
### GitHub Actions OIDC (Recommended)
```yaml
- name: Login to MCP Registry
run: mcp-publisher login github-oidc
```
### GitHub Personal Access Token
You can authenticate using a GitHub Personal Access Token in two ways:
**Option 1: Using the --token flag**
```yaml
- name: Login to MCP Registry
run: mcp-publisher login github --token ${{ secrets.MCP_GITHUB_TOKEN }}
```
**Option 2: Using environment variable**
```yaml
- name: Login to MCP Registry
run: mcp-publisher login github
env:
MCP_GITHUB_TOKEN: ${{ secrets.MCP_GITHUB_TOKEN }}
```
**Note:** You must create a custom secret `MCP_GITHUB_TOKEN` with a GitHub Personal Access Token that has `read:org` and `read:user` scopes. The automatic `GITHUB_TOKEN` provided by GitHub Actions does not have these permissions and cannot be used.
### DNS Authentication
For custom domain namespaces (`com.yourcompany/*`):
```yaml
- name: Login to MCP Registry
run: |
echo "${{ secrets.MCP_PRIVATE_KEY }}" > key.pem
mcp-publisher login dns --domain yourcompany.com --private-key-file key.pem
```
Add your Ed25519 private key as `MCP_PRIVATE_KEY` secret.
## Examples
See these real-world examples of automated publishing workflows:
- [NPM, Docker and MCPB](https://github.com/domdomegg/airtable-mcp-server)
- [NuGet](https://github.com/domdomegg/time-mcp-nuget)
- [PyPI](https://github.com/domdomegg/time-mcp-pypi)
## Tips
You can keep your package version and server.json version in sync automatically with something like:
```yaml
- run: |
VERSION=${GITHUB_REF#refs/tags/v}
jq --arg v "$VERSION" '.version = $v' server.json > tmp && mv tmp server.json
```
## Troubleshooting
- **"Authentication failed"**: Ensure `id-token: write` permission is set for OIDC, or check secrets
- **"Package validation failed"**: Verify your package published to your registry (NPM, PyPi etc.) successfully first, and that you have done the necessary validation steps in the [Publishing Tutorial](publish-server.md)

525
docs/guides/publishing/publish-server.md
View file

@ -1,525 +0,0 @@
# Publish Your MCP Server
Complete guide to publishing an MCP server to the registry.
> [!TIP]
> Using an agentic AI coding assistant? Just use this prompt:
> ```
> Read https://raw.githubusercontent.com/modelcontextprotocol/registry/refs/heads/main/docs/guides/publishing/publish-server.md and https://raw.githubusercontent.com/modelcontextprotocol/registry/refs/heads/main/docs/guides/publishing/github-actions.md. Evaluate the best way to publish this server to the registry (prefer automated CI flows over manual flows where possible), and implement that. If possible, validate the server.json against the $schema before telling the user you are done, using a proper json schema library or tool available on the user's machine. If you get stuck, guide the user through the parts of the publishing process they need to do (e.g. logging into the publisher CLI if doing manual pubishing).
> ```
## What You'll Learn
By the end of this tutorial, you'll have:
- Created a server.json file for your MCP server
- Authenticated with the registry
- Successfully published your server
- Verified your server appears in the registry
## Prerequisites
- An MCP server you've already built ([follow this guide if you don't have one already](https://modelcontextprotocol.io/quickstart/server))
- Your server must be publicly accessible (closed source servers are welcome, but private/internal servers are not supported)
## Deployment Options
You can make your MCP server available in multiple ways:
- **📦 Package deployment**: Published to registries (npm, PyPI, NuGet, Docker Hub, etc.) and run locally by clients
- **🌐 Remote deployment**: Hosted as a web service that clients connect to directly
- **🔄 Hybrid deployment**: Offer both package and remote options for maximum flexibility
Learn more about [MCP server architecture](https://modelcontextprotocol.io/docs/learn/architecture) in the official docs.
## Step 1: Install the Publisher CLI
<details>
<summary><strong>🍺 macOS/Linux/WSL: With Homebrew (recommended)</strong></summary>
Requires [Homebrew](https://brew.sh):
```bash
brew install mcp-publisher
```
</details>
<details>
<summary><strong>⬇️ macOS/Linux/WSL: Pre-built binaries</strong></summary>
```bash
curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher && sudo mv mcp-publisher /usr/local/bin/
```
</details>
<details>
<summary><strong>🏗️ macOS/Linux/WSL: From source</strong></summary>
Requires Git, Make and Go 1.24+:
```bash
# Clone the registry repository
git clone https://github.com/modelcontextprotocol/registry
cd registry
make publisher
# The binary will be at bin/mcp-publisher
export PATH=$PATH:$(pwd)/bin
```
</details>
<details>
<summary><strong>🪟 Windows PowerShell: Pre-built binaries</strong></summary>
```powershell
$arch = if ([System.Runtime.InteropServices.RuntimeInformation]::ProcessArchitecture -eq "Arm64") { "arm64" } else { "amd64" }; Invoke-WebRequest -Uri "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_windows_$arch.tar.gz" -OutFile "mcp-publisher.tar.gz"; tar xf mcp-publisher.tar.gz mcp-publisher.exe; rm mcp-publisher.tar.gz
# Move mcp-publisher.exe to a directory in your PATH
```
</details>
## Step 2: Initialize Your server.json
Navigate to your server's directory and create a template:
```bash
cd /path/to/your/mcp-server
mcp-publisher init
```
This creates a `server.json` with auto-detected values. You'll see something like:
```json
{
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json",
"name": "io.github.yourname/weather-data-mcp",
"title": "Weather Data",
"description": "Access real-time weather data and forecasts",
"version": "1.0.0",
"packages": [
{
"registryType": "npm",
"identifier": "@yourname/weather-data-mcp",
"version": "1.0.0",
"transport": {
"type": "stdio"
}
}
]
}
```
## Step 3: Configure Your Server Details
Edit the generated `server.json`:
### Choose Your Namespace
The `name` field determines authentication requirements:
- **`io.github.yourname/*`** - Requires GitHub authentication
- **`com.yourcompany/*`** - Requires DNS or HTTP domain verification
### Configure Deployment Methods
Configure your server to support packages, remotes, or both:
#### Package Deployment
Add package validation metadata to prove ownership of your packages.
<details>
<summary><strong>📦 NPM Packages</strong></summary>
### Requirements
Add an `mcpName` field to your `package.json`:
```json
{
"name": "your-npm-package",
"version": "1.0.0",
"mcpName": "io.github.username/server-name"
}
```
### How It Works
- Registry fetches `https://registry.npmjs.org/your-npm-package`
- Checks that `mcpName` field matches your server name
- Fails if field is missing or doesn't match
### Example server.json
```json
{
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json",
"name": "io.github.username/slack-integration-mcp",
"title": "Slack Integration",
"description": "Send messages and manage Slack workspaces",
"version": "1.0.0",
"packages": [
{
"registryType": "npm",
"identifier": "@username/slack-integration-mcp",
"version": "1.0.0",
"transport": {
"type": "stdio"
}
}
]
}
```
The official MCP registry currently only supports the NPM public registry (`https://registry.npmjs.org`).
</details>
<details>
<summary><strong>🐍 PyPI Packages</strong></summary>
### Requirements
Include your server name in your package README file using this format:
**MCP name format**: `mcp-name: io.github.username/server-name`
Add it to your README.md file (which becomes the package description on PyPI). This can be in a comment if you want to hide it from display elsewhere.
### How It Works
- Registry fetches `https://pypi.org/pypi/your-package/json`
- Passes if `mcp-name: server-name` is in the README content
### Example server.json
```json
{
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json",
"name": "io.github.username/database-query-mcp",
"title": "Database Query",
"description": "Execute SQL queries and manage database connections",
"version": "1.0.0",
"packages": [
{
"registryType": "pypi",
"identifier": "database-query-mcp",
"version": "1.0.0",
"transport": {
"type": "stdio"
}
}
]
}
```
The official MCP registry currently only supports the official PyPI registry (`https://pypi.org`).
</details>
<details>
<summary><strong>📋 NuGet Packages</strong></summary>
### Requirements
Include your server name in your package's README using this format:
**MCP name format**: `mcp-name: io.github.username/server-name`
Add a README file to your NuGet package that includes the server name. This can be in a comment if you want to hide it from display elsewhere.
### How It Works
- Registry fetches README from `https://api.nuget.org/v3-flatcontainer/{id}/{version}/readme`
- Passes if `mcp-name: server-name` is found in the README content
### Example server.json
```json
{
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json",
"name": "io.github.username/azure-devops-mcp",
"title": "Azure DevOps",
"description": "Manage Azure DevOps work items and pipelines",
"version": "1.0.0",
"packages": [
{
"registryType": "nuget",
"identifier": "Username.AzureDevOpsMcp",
"version": "1.0.0",
"transport": {
"type": "stdio"
}
}
]
}
```
The official MCP registry currently only supports the official NuGet registry (`https://api.nuget.org`).
</details>
<details>
<summary><strong>🐳 Docker/OCI Images</strong></summary>
### Requirements
Add an annotation to your Docker image:
```dockerfile
LABEL io.modelcontextprotocol.server.name="io.github.username/server-name"
```
### How It Works
- Registry authenticates with container registries using token-based authentication:
- **Docker Hub**: Uses `auth.docker.io` token service
- **GitHub Container Registry**: Uses `ghcr.io` token service
- Fetches image manifest using Docker Registry v2 API
- Checks that `io.modelcontextprotocol.server.name` annotation matches your server name
- Fails if annotation is missing or doesn't match
### Example server.json (Docker Hub)
```json
{
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json",
"name": "io.github.username/kubernetes-manager-mcp",
"title": "Kubernetes Manager",
"description": "Deploy and manage Kubernetes resources",
"version": "1.0.0",
"packages": [
{
"registryType": "oci",
"identifier": "docker.io/yourusername/kubernetes-manager-mcp:1.0.0",
"transport": {
"type": "stdio"
}
}
]
}
```
### Example server.json (GitHub Container Registry)
```json
{
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json",
"name": "io.github.username/git-operations-mcp",
"title": "Git Operations",
"description": "Advanced Git repository management and operations",
"version": "1.0.0",
"packages": [
{
"registryType": "oci",
"identifier": "ghcr.io/username/git-operations-mcp:1.0.0",
"transport": {
"type": "stdio"
}
}
]
}
```
The identifier format is `registry/namespace/repository:tag` (e.g., `docker.io/user/app:1.0.0` or `ghcr.io/user/app:1.0.0`). The version can also be specified as a digest.
The official MCP registry supports:
- Docker Hub (`docker.io`)
- GitHub Container Registry (`ghcr.io`)
- Google Artifact Registry (any `*.pkg.dev` domain)
- Azure Container Registry (`*.azurecr.io`)
- Microsoft Container Registry (`mcr.microsoft.com`)
</details>
<details>
<summary><strong>📁 MCPB Packages</strong></summary>
### Requirements
**MCP reference** - MCPB package URLs must contain "mcp" somewhere within them, to ensure the correct artifact has been uploaded. This may be with the `.mcpb` extension or in the name of your repository.
**File integrity** - MCPB packages must include a SHA-256 hash for file integrity verification. This is required at publish time and MCP clients will validate this hash before installation.
### How to Generate File Hashes
Calculate the SHA-256 hash of your MCPB file:
```bash
openssl dgst -sha256 server.mcpb
```
### Example server.json
```json
{
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json",
"name": "io.github.username/image-processor-mcp",
"title": "Image Processor",
"description": "Process and transform images with various filters",
"version": "1.0.0",
"packages": [
{
"registryType": "mcpb",
"identifier": "https://github.com/username/image-processor-mcp/releases/download/v1.0.0/image-processor.mcpb",
"fileSha256": "fe333e598595000ae021bd27117db32ec69af6987f507ba7a63c90638ff633ce",
"transport": {
"type": "stdio"
}
}
]
}
```
### File Hash Validation
- **Authors** are responsible for generating correct SHA-256 hashes when creating server.json
- **MCP clients** validate the hash before installing packages to ensure file integrity
- **The official registry** stores hashes but does not validate them
- **Subregistries** may choose to implement their own validation. This enables them to perform security scanning on MCPB files, and ensure clients get the same security scanned content.
The official MCP registry currently only supports artifacts hosted on GitHub or GitLab releases.
</details>
#### Remote Deployment
Add the `remotes` field to your `server.json` (can coexist with `packages`):
<details>
<summary><strong>🌐 Remote Server Configuration</strong></summary>
### Requirements
- **Service endpoint**: Your MCP server must be accessible at the specified URL
- **Transport protocol**: Choose from `streamable-http` (recommended) or `sse` (deprecated)
- **URL validation**: For domain namespaces only (see URL requirements below)
### Example server.json
```json
{
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json",
"name": "com.yourcompany/acme-analytics",
"title": "ACME Analytics",
"description": "Real-time business intelligence and reporting platform",
"version": "2.0.0",
"remotes": [
{
"type": "streamable-http",
"url": "https://mcp.yourcompany.com/mcp"
}
]
}
```
### Multiple Transport Options
You can offer multiple connection methods:
```json
{
"remotes": [
{
"type": "streamable-http",
"url": "https://mcp.yourcompany.com/mcp"
},
{
"type": "sse",
"url": "https://mcp.yourcompany.com/sse"
}
]
}
```
### URL Validation Requirements
- For `com.yourcompany/*` namespaces: URLs must be on `yourcompany.com` or its subdomains
- For `io.github.username/*` namespaces: No URL restrictions (but you must authenticate via GitHub)
### Authentication Headers (Optional)
Configure headers that clients should send when connecting:
```json
{
"remotes": [
{
"type": "streamable-http",
"url": "https://mcp.yourcompany.com/mcp",
"headers": [
{
"name": "X-API-Key",
"description": "API key for authentication",
"isRequired": true,
"isSecret": true
}
]
}
]
}
```
</details>
## Step 4: Authenticate
Choose your authentication method based on your namespace:
### GitHub Authentication (for io.github.* namespaces)
```bash
mcp-publisher login github
```
This opens your browser for OAuth authentication.
### DNS Authentication (for custom domains)
```bash
# Generate keypair
openssl genpkey -algorithm Ed25519 -out key.pem
# Get public key for DNS record
echo "yourcompany.com. IN TXT \"v=MCPv1; k=ed25519; p=$(openssl pkey -in key.pem -pubout -outform DER | tail -c 32 | base64)\""
# Add the TXT record to your DNS, then login
mcp-publisher login dns --domain yourcompany.com --private-key $(openssl pkey -in key.pem -noout -text | grep -A3 "priv:" | tail -n +2 | tr -d ' :\n')
```
The ECDSA P-384 algorithm is also supported, along with HTTP-based authentication. See the [publisher CLI commands reference](../../reference/cli/commands.md) for more details.
## Step 5: Publish Your Server
With authentication complete, publish your server:
```bash
mcp-publisher publish
```
You'll see output like:
```
✓ Successfully published
```
## Step 6: Verify Publication
Check that your server appears in the registry by searching for it:
```bash
curl "https://registry.modelcontextprotocol.io/v0/servers?search=io.github.yourname/weather-server"
```
You should see your server metadata returned in the JSON response.
## Troubleshooting
**"Package validation failed"** - Ensure your package includes the required validation metadata (mcpName field, README mention, or Docker label).
**"Authentication failed"** - Verify you've correctly set up DNS records or are logged into the right GitHub account.
**"Namespace not authorized"** - Your authentication method doesn't match your chosen namespace format.
## Examples
See these real-world examples of published servers:
- [NPM, Docker and MCPB example](https://github.com/domdomegg/airtable-mcp-server)
- [NuGet example](https://github.com/domdomegg/time-mcp-nuget)
- [PyPI example](https://github.com/domdomegg/time-mcp-pypi)
## Next Steps
- **Update your server**: Publish new versions with updated server.json files
- **Set up CI/CD**: Automate publishing with [GitHub Actions](github-actions.md)
- **Learn more**: Understand [server.json format](../../reference/server-json/generic-server-json.md) in depth
- **More examples**: See [remote server configurations](../../reference/server-json/generic-server-json.md#remote-server-example) and [hybrid deployments](../../reference/server-json/generic-server-json.md#server-with-remote-and-package-options) in the schema documentation
## What You've Accomplished
You've successfully published your first MCP server to the registry! Your server is now discoverable by MCP clients and can be installed by users worldwide.

89
docs/modelcontextprotocol-io/about.mdx Normal file
View file

@ -0,0 +1,89 @@
---
title: The MCP Registry
sidebarTitle: About
---
The MCP Registry is the official centralized metadata repository for publicly accessible MCP servers, backed by major trusted contributors to the MCP ecosystem such as Anthropic, GitHub, PulseMCP, and Microsoft.
The MCP Registry provides:
- A single place for server creators to publish metadata about their servers
- Namespace management through DNS verification
- A REST API for MCP clients and aggregators to discover available servers
- Standardized installation and configuration information
Server metadata is stored in a standardized [`server.json` format](https://github.com/modelcontextprotocol/registry/blob/main/docs/reference/server-json/server.schema.json), which contains:
- The server's unique name (e.g., `io.github.user/server-name`)
- Where to locate the server (e.g., npm package name, remote server URL)
- Execution instructions (e.g., command-line args, env vars)
- Other discovery data (e.g., description, server capabilities)
## The MCP Registry Ecosystem
The MCP Registry is part of an ecosystem that looks something like:
![The MCP Registry ecosystem](./ecosystem-diagram.excalidraw.svg)
### Relationship with Package Registries
Package registries — such as npm, PyPI, and Docker Hub — host packages with code and binaries.
The MCP Registry hosts metadata that points to those packages.
For example, a `weather-mcp` package could be hosted on npm, and metadata in the MCP Registry could map the "weather v1.2.0" server to `npm:weather-mcp`.
The [Package Types guide](./package-types.mdx) lists the supported package types and registries. More package registries may be supported in the future based on community demand. If you are interested in building support for a package registry, please [open an issue](https://github.com/modelcontextprotocol/registry).
### Relationship with Server Developers
The MCP Registry supports both open-source and closed-source servers. Server developers can publish their server's metadata to the registry as long as the server's installation method is publicly available (e.g., an npm package or a Docker image on a public registry) _or_ the server itself is publicly accessible (e.g., a remote server that is not restricted to private networks).
The MCP Registry **does not** support private servers. Private servers are those that are only accessible to a narrow set of users. For example, servers published on a private network (like `mcp.acme-corp.internal`) or on private package registries (e.g. `npx -y @acme/mcp --registry https://artifactory.acme-corp.internal/npm`). If you want to publish private servers, we recommend that you host your own private MCP registry and add them there.
### Relationship with Downstream Aggregators
The MCP Registry is intended to be consumed primarily by downstream aggregators, such as MCP server marketplaces.
The metadata hosted by the MCP Registry is deliberately unopinionated. Downstream aggregators can provide curation or additional metadata such as community ratings.
We expect that downstream aggregators will use the MCP Registry API to pull new metadata on a regular but infrequent basis (for example, once per hour). See the [MCP Registry Aggregators guide](./registry-aggregators.mdx) for more information.
### Relationship with Other MCP Registries
In addition to a public REST API, the MCP Registry defines an [OpenAPI spec](https://github.com/modelcontextprotocol/registry/blob/main/docs/reference/api/openapi.yaml) that other MCP registries can implement in order to provide a standardized interface for MCP host applications.
We expect that many downstream aggregators will implement this interface. Private MCP registries can implement it as well to benefit from existing host application support.
Note that the official MCP Registry codebase is **not** designed for self-hosting, and the registry maintainers cannot provide support for this use case. If you choose to fork it, you would need to maintain and operate it independently.
### Relationship with MCP Host Applications
The MCP Registry is not intended to be directly consumed by host applications. Instead, host applications should consume other MCP registries, such as downstream marketplaces, via a REST API conforming to the official MCP Registry's OpenAPI spec.
## Trust and Security
### Verifying Server Authenticity
The MCP Registry uses namespace authentication to ensure that servers come from their claimed sources. Server names follow a reverse DNS format (like `io.github.username/server` or `com.example/server`) that ties them to verified GitHub accounts or domains.
This namespace system ensures that only the legitimate owner of a GitHub account or domain can publish servers under that namespace, providing trust and accountability in the ecosystem. For details on authentication methods, see the [Authentication guide](./authentication.mdx).
### Security Scanning
The MCP Registry delegates security scanning to:
- **Underlying package registries** — npm, PyPI, Docker Hub, and other package registries perform their own security scanning and vulnerability detection.
- **Downstream aggregators** — MCP Registry aggregators and marketplaces can implement additional security checks, ratings, or curation.
The MCP Registry focuses on namespace authentication and metadata hosting, while relying on the broader ecosystem for security scanning of actual server code.
### Spam Prevention
The MCP Registry uses multiple mechanisms to prevent spam:
- **Namespace authentication requirements** — Publishers must verify ownership of their namespace through GitHub, DNS, or HTTP challenges, preventing arbitrary spam submissions.
- **Character limits and validation** — Free-form fields have strict character limits and regex validation to prevent abuse.
- **Manual takedown** — The registry maintainers can manually remove spam or malicious servers. See the [Moderation Policy](./moderation-policy.mdx) for details on what content is removed.
Future spam prevention measures under consideration include stricter rate limiting, AI-based spam detection, and community reporting capabilities.

Some files were not shown because too many files have changed in this diff Show more