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

Big docs tidy up in preparation for launch (#364)

Browse source 
## Motivation and Context
Docs currently don't have very clear organisation, and don't explain
core flows.

This fixes #89 (although we still might want to push these to
`https://modelcontextprotocol.io/docs/`), based on the plan there.

One minor change from that plan is that I merged tutorials and guides,
because they ended up basically being duplicates which I thought would
be annoying for us to keep in sync. Additionally in the Diátaxis
framework, tutorials and guides are separated by whether they are
focused on acquisition of skills (e.g. in a learning environment) or
application of skills (e.g. in a work environment). I expect the
registry to be something that will be used occasionally in a work
environment, rather than a fundamental 'learnable' skill so I think it's
reasonable not to have tutorials and fold these into guides.

## How Has This Been Tested?
- Read through all these updated docs
- Unit and integration tests (that previously used examples.md and use
the schema) working
- Ran `npx markdown-link-check .` to check all the links work

## Breaking Changes
Links to old docs will break, but I don't think there are any. All
internal links have been checked and updated.

## Types of changes
<!-- What types of changes does your code introduce? Put an `x` in all
the boxes that apply: -->
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update
This commit is contained in:
adam jones 2025-09-07 10:44:42 +01:00 • committed by GitHub
commit 2e7108d366
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
9 changed files with 1200 additions and 376 deletions
Download patch file Download diff file Expand all files Collapse all files

10
docs/explanations/README.md Normal file
View file

@ -0,0 +1,10 @@
# 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)

39
docs/explanations/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

13
docs/explanations/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/explanations/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.

45
docs/explanations/namespacing.md Normal file
View file

@ -0,0 +1,45 @@
# 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 `_mcp-registry.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.

42467
docs/explanations/registry-goals-presentation.pdf Normal file
View file

File diff suppressed because one or more lines are too long

31
docs/explanations/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/explanations/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/...
```

233
docs/explanations/versioning.md Normal file
View file

@ -0,0 +1,233 @@
# 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_detail": {
"version": "1.2.3"
}
}
```
### 2. Align with Package Versions
Server authors SHOULD use versions aligned with their underlying packages to reduce confusion:
```json
{
"version_detail": {
"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_detail": {
"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 `is_latest`
### 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 `is_latest` 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 `is_latest` 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 is_latest: 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
"snapshot" // Development snapshots
"latest" // Custom versioning scheme
```
### Alignment Examples
```json
{
"version_detail": {
"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_detail": {
"version": "1.2.3"
},
"packages": [
{
"registry_type": "npm",
"identifier": "@myorg/server",
"version": "1.2.3"
}
]
}
```
### Registry-Only Updates
**Server metadata changes without package updates**:
```json
{
"version_detail": {
"version": "1.2.3-1"
},
"packages": [
{
"registry_type": "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_detail": {
"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_detail": {
"version": "1.3.0"
},
"packages": [
{
"registry_type": "npm",
"identifier": "@myorg/server",
"version": "1.3.0"
},
{
"registry_type": "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.