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

Update documentation structure and content (#302)

Browse source 
## Summary

- Restructure main README to focus on registry purpose and quick start
guide
- Streamline docs/README.md with better organization and linking
- Update FAQ with current publishing methods, security approach, and
community practices
- Simplify roadmap to focus on go-live blockers rather than exhaustive
backlog
- Add ecosystem diagram to visualize registry architecture
This commit is contained in:
adam jones 2025-08-26 15:58:49 +01:00 • committed by GitHub
commit d663406280
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
5 changed files with 177 additions and 292 deletions
Download patch file Download diff file Expand all files Collapse all files

320
README.md
View file

@ -1,214 +1,86 @@
# MCP Registry
A community driven registry service for Model Context Protocol (MCP) servers.
> [!WARNING]
> The registry is under [active development](#development-status). The registry API spec is unstable and the official MCP registry database may be wiped at any time.
📖 **[API Documentation](https://staging.registry.modelcontextprotocol.io/docs)** | 📚 **[Technical Docs](./docs)**
## What is the registry?
The registry will provide MCP clients with a list of MCP servers. Like an app store for MCP servers. (In 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](./docs/server-registry-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`](./docs/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:
![](./docs/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.
## Development Status
This project is being built in the open and is currently in the early stages of development. Please see the [overview discussion](https://github.com/modelcontextprotocol/registry/discussions/11) for the project scope and goals.
**2025-08-26 update**: We're targeting a 'preview' go-live on 4th September. This may still be unstable and not provide durability guarantees, but is a step towards being more solidified. A general availability (GA) release will follow later.
### Contributing
Current key maintainers:
- **Adam Jones** (Anthropic) [@domdomegg](https://github.com/domdomegg)
- **Tadas Antanavicius** (PulseMCP) [@tadasant](https://github.com/tadasant)
- **Toby Padilla** (GitHub) [@toby](https://github.com/toby)
Use [Discussions](https://github.com/modelcontextprotocol/registry/discussions) to propose and discuss product and/or technical **requirements**.
## Contributing
Use [Issues](https://github.com/modelcontextprotocol/registry/issues) to track **well-scoped technical work** that the community agrees should be done at some point.
We use multiple channels for collaboration - see [modelcontextprotocol.io/community/communication](https://modelcontextprotocol.io/community/communication).
Open [Pull Requests](https://github.com/modelcontextprotocol/registry/pulls) when you want to **contribute work towards an Issue**, or you feel confident that your contribution is desireable and small enough to forego community discussion at the requirements and planning levels.
Often (but not always) ideas flow through this pipeline:
## Overview
- **[Discord](https://modelcontextprotocol.io/community/communication)** - Real-time community discussions
- **[Discussions](https://github.com/modelcontextprotocol/registry/discussions)** - Propose and discuss product/technical requirements
- **[Issues](https://github.com/modelcontextprotocol/registry/issues)** - Track well-scoped technical work
- **[Pull Requests](https://github.com/modelcontextprotocol/registry/pulls)** - Contribute work towards issues
The MCP Registry service provides a centralized repository for MCP server entries. It allows discovery and management of various MCP implementations with their associated metadata, configurations, and capabilities.
### Quick start:
## Features
#### Pre-requisites
- RESTful API for managing MCP registry entries (list, get, create, update, delete)
- Health check endpoint for service monitoring
- Support for various environment configurations
- Graceful shutdown handling
- PostgreSQL and in-memory database support
- Comprehensive API documentation
- Pagination support for listing registry entries
- Seed data export/import composability with HTTP support
- Registry instance data sharing via HTTP endpoints
- **Docker**
- **Go 1.24.x**
- **golangci-lint v2.4.0**
## Getting Started
### Prerequisites
- Go 1.24.x (required - check with `go version`)
- PostgreSQL
- Docker (optional, but recommended for development)
For development:
- golangci-lint v2.4.0 - Install with:
```bash
curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin v2.4.0
```
## Running
The easiest way to get the registry running is uses docker compose. This will setup the MCP Registry service, import the seed data and run PostgreSQL in a local Docker environment.
#### Running the server
```bash
# Start full development environment
make dev-compose
```
This will start the MCP Registry service running at [`localhost:8080`](http://localhost:8080).
This starts the registry at [`localhost:8080`](http://localhost:8080) with PostgreSQL and seed data. It can be configured with environment variables in [docker-compose.yml](./docker-compose.yml) - see [.env.example](./.env.example) for a reference.
## Building
<details>
<summary>Alternative: Local setup without Docker</summary>
If you prefer to run the service locally without Docker, you can build and run it directly:
**Prerequisites:**
- PostgreSQL running locally
- Go 1.24.x installed
```bash
# Build a registry executable
# Build and run locally
make build
```
This will create the `registry` binary in the current directory.
To run the service locally:
```bash
# Run registry locally
make dev-local
```
By default, the service will run on [`localhost:8080`](http://localhost:8080). You'll need to use the in-memory database or have PostgreSQL running.
The service runs on [`localhost:8080`](http://localhost:8080) by default. This can be configured with environment variables in `.env` - see [.env.example](./.env.example) for a reference.
To build the CLI tool for publishing MCP servers to the registry:
</details>
```bash
# Build the publisher tool
make publisher
```
<details>
<summary>Alternative: Running a pre-built Docker image</summary>
## Development
### Available Make Targets
To see all available make targets:
```bash
make help
```
Key development commands:
```bash
# Development
make dev-compose # Start development environment with Docker Compose
make dev-local # Run registry locally
# Build targets
make build # Build the registry application
make publisher # Build the publisher tool
make migrate # Build the database migration tool
# Testing
make test-unit # Run unit tests with coverage report
make test-integration # Run integration tests
make test-endpoints # Test API endpoints (requires running server)
make test-publish # Test publish endpoint (requires BEARER_TOKEN)
make test-all # Run all tests
# Code quality
make lint # Run linter (same as CI)
make lint-fix # Run linter with auto-fix
# Validation
make validate-schemas # Validate JSON schemas
make validate-examples # Validate examples against schemas
make validate # Run all validation checks
# Combined workflows
make check # Run all checks (lint, validate, unit tests)
# Utilities
make clean # Clean build artifacts and coverage files
```
### Linting
The project uses golangci-lint with extensive checks. Always run linting before pushing:
```bash
# Run all linters (same as CI)
make lint
# Run linter with auto-fix
make lint-fix
```
### Git Hooks (Optional)
To automatically run linting before commits:
```bash
git config core.hooksPath .githooks
```
This will prevent commits that fail linting or have formatting issues.
### Project Structure
```
├── api/ # OpenApi specification
├── cmd/ # Application entry points
├── config/ # Configuration files
├── internal/ # Private application code
│ ├── api/ # HTTP server and request handlers (routing)
│ ├── auth/ # GitHub OAuth integration
│ ├── config/ # Configuration management
│ ├── database/ # Data persistence abstraction
│ ├── model/ # Data models and domain structures
│ └── service/ # Business logic implementation
├── pkg/ # Public libraries
├── scripts/ # Utility scripts
└── tools/ # Command line tools
└── publisher/ # Tool to publish MCP servers to the registry
```
### Architecture Overview
### Request Flow
1. HTTP requests enter through router (`internal/api/router/`)
2. Handlers in `internal/api/handlers/v0/` validate and process requests
3. Service layer executes business logic
4. Database interface handles persistence
5. JSON responses returned to clients
### Key Interfaces
- **Database Interface** (`internal/database/database.go`) - Abstracts data persistence with PostgreSQL and in-memory implementations
- **RegistryService** (`internal/service/service.go`) - Business logic abstraction over database
- **Auth Service** (`internal/auth/jwt.go`) - Registry token creation and validation
### Authentication Flow
Publishing requires GitHub OAuth validation:
1. Extract bearer token from Authorization header
2. Validate token with GitHub API
3. Verify repository ownership matches token owner
4. Check organization membership if applicable
### Design Patterns
- **Factory Pattern** for service creation with dependency injection
- **Repository Pattern** for database abstraction
- **Context Pattern** for timeout management (5-second DB operations)
- **Cursor-based Pagination** using UUIDs for stateless pagination
## API Endpoints
### API Documentation
```
GET /docs
```
The API is documented using Swagger/OpenAPI. This page provides a complete reference of all endpoints with request/response schemas and examples, and allows you to test the API directly from your browser.
## Configuration
The service can be configured using environment variables. See [.env.example](./.env.example) for details.
## Pre-built Docker Images
Pre-built Docker images are automatically published to GitHub Container Registry on each release and main branch commit:
Pre-built Docker images are automatically published to GitHub Container Registry:
```bash
# Run latest from main branch
@ -218,41 +90,75 @@ docker run -p 8080:8080 ghcr.io/modelcontextprotocol/registry:latest
docker run -p 8080:8080 ghcr.io/modelcontextprotocol/registry:main-20250806-a1b2c3d
```
**Available image tags:**
- `latest` - Latest commit from main branch
- `main-<date>-<sha>` - Specific commit builds
**Available tags:** `latest`, `main-<date>-<sha>`
**Configuration:** The Docker images support all environment variables listed in the [Configuration](#configuration) section. For production deployments, you'll need to configure the database connection and other settings via environment variables.
</details>
### Import Seed Data
#### Publishing a server
Registry instances can import data from:
**Local files:**
```bash
MCP_REGISTRY_SEED_FROM=data/seed.json ./registry
```
**HTTP endpoints:**
```bash
MCP_REGISTRY_SEED_FROM=http://other-registry:8080 ./registry
```
## Testing
Run the test script to validate API endpoints:
To publish a server, we've built a simple CLI. You can use it with:
```bash
./scripts/test_endpoints.sh
# Build the latest CLI
make publisher
# Use it!
./tools/publisher/bin/mcp-publisher --help
```
You can specify specific endpoints to test:
See [the publisher README](./tools/publisher/README.md) for more details.
#### Other commands
```bash
./scripts/test_endpoints.sh --endpoint health
./scripts/test_endpoints.sh --endpoint servers
# Run lint, unit tests and integration tests
make check
```
## License
There are also a few more helpful commands for development. Run `make help` to learn more, or look in [Makefile](./Makefile).
See the [LICENSE](LICENSE) file for details.
<!--
For Claude and other AI tools: Always prefer make targets over custom commands where possible.
-->
## Architecture
### Project Structure
```
├── cmd/ # Application entry points
├── data/ # Seed data
├── deploy/ # Deployment configuration (Pulumi)
├── docs/ # Technical documentation
│ ├── server-json/ # server.json specification & examples
│ └── server-registry-api/ # API specification
├── internal/ # Private application code
│ ├── api/ # HTTP handlers and routing
│ ├── auth/ # Authentication (GitHub OAuth, JWT)
│ ├── config/ # Configuration management
│ ├── database/ # Data persistence (PostgreSQL, in-memory)
│ ├── model/ # Data models and domain structures
│ ├── service/ # Business logic
│ └── telemetry/ # Metrics and monitoring
├── scripts/ # Development and testing scripts
├── tests/ # Integration tests
└── tools/ # CLI tools
├── publisher/ # Server publishing tool
└── validate-*.sh # Schema validation tools
```
### Authentication
Publishing supports multiple authentication methods:
- **GitHub OAuth** - For publishing by logging into GitHub
- **GitHub OIDC** - For publishing from GitHub Actions
- **DNS verification** - For proving ownership of a domain and its subdomains
- **HTTP verification** - For proving ownership of a domain
The registry validates namespace ownership when publishing. E.g. to publish...:
- `io.github.domdomegg/my-cool-mcp` you must login to GitHub as `domdomegg`, or be in a GitHub Action on domdomegg's repos
- `me.adamjones/my-cool-mcp` you must prove ownership of `adamjones.me` via DNS or HTTP challenge
## More documentation
See the [docs](./docs) folder for more details if your question has not been answered here!

27
docs/README.md
View file

@ -1,23 +1,18 @@
# Official Registry Documentation
This extends [the main README](../README.md).
## Project Documentation
[`design_principles.md`](./design_principles.md) - Core constraints and principles guiding the registry design
[`faq.md`](./faq.md) - Frequently asked questions about the MCP Registry
[`roadmap.md`](./roadmap.md) - High-level roadmap for the MCP Registry development
[`MCP Developers Summit 2025 - Registry Talk Slides.pdf`](./MCP%20Developers%20Summit%202025%20-%20Registry%20Talk%20Slides.pdf) - Slides from a talk given at the MCP Developers Summit on May 23, 2025, with an up-to-date vision of how we are thinking about the official registry.
- [`faq.md`](./faq.md) - Frequently asked questions about the MCP Registry
- [`design_principles.md`](./design_principles.md) - Core constraints and principles guiding the registry design
- [`roadmap.md`](./roadmap.md) - High-level roadmap for the MCP Registry development
- [`MCP Developers Summit 2025 - Registry Talk Slides.pdf`](./MCP%20Developers%20Summit%202025%20-%20Registry%20Talk%20Slides.pdf) - Slides from a talk given at the MCP Developers Summit on May 23, 2025, with an up-to-date vision of how we are thinking about the official registry.
## API & Technical Specifications
[`openapi.yaml`](./openapi.yaml) - OpenAPI specification for the official registry API
[`api_examples.md`](./api_examples.md) - Examples of what data will actually look like coming from the official registry API
[`architecture.md`](./architecture.md) - Technical architecture, deployment strategies, and data flows
[`server.json` README](./server-json/README.md) - description of the `server.json` purpose and schema
[`new_package_registry.md`](./new_package_registry.md) - steps to add a new package registry for local server packages
- [`openapi.yaml`](./openapi.yaml) - OpenAPI specification for the official registry API
- [`api_examples.md`](./api_examples.md) - Examples of what data will actually look like coming from the official registry API
- [`architecture.md`](./architecture.md) - Technical architecture, deployment strategies, and data flows
- [`server.json` README](./server-json/README.md) - description of the `server.json` purpose and schema
- [`new_package_registry.md`](./new_package_registry.md) - steps to add a new package registry for local server packages

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

116
docs/faq.md
View file

@ -33,26 +33,21 @@ The registry is designed for programmatic consumption by:
- Server aggregators (Smithery, PulseMCP, etc.)
- NOT individual end-users (they should use MCP clients or aggregator UIs)
### Will there be a UI for browsing servers?
### Will there be feature X?
A UI is planned as a future milestone after the initial API launch, but is not part of the MVP.
See [roadmap.md](./roadmap.md).
## Publishing Servers
### How do I publish my MCP server?
Servers are published by submitting a `server.json` file through our CLI tool. The process requires:
1. GitHub authentication
2. A public GitHub repository (even for closed-source servers - just for the metadata)
3. Your server package published to a supported registry (npm, PyPI, NuGet, Docker Hub, etc.)
4. Optional: DNS verification for custom namespacing
See the [publisher README](../tools/publisher/README.md)
### What namespaces are available?
- **With DNS verification**: `com.yourcompany/server-name` (reverse DNS notation)
- **Without DNS verification**: `io.github.yourusername/server-name`
- DNS verification is done via TXT records and enables authoritative namespacing
- **With GitHub verification**: `io.github.yourusername/server-name`, `io.github.yourorg/server-name`
- **With DNS verification**: `com.yourcompany.*`, `com.yourcompany.*/*`
- **With HTTP verification**: `com.yourcompany/*`
### Is open source required?
@ -90,9 +85,21 @@ The registry accepts any version string up to 255 characters, but we recommend:
The registry attempts to parse versions as semantic versions for proper ordering. Non-semantic versions are allowed but will be ordered by publication timestamp. See the [versioning guide](./versioning.md) for detailed guidance.
### Can I add custom metadata when publishing?
Yes, extensions under the `x-publisher` property are preserved when publishing to the registry. This allows you to include custom metadata specific to your publishing process.
### Can I delete/unpublish my server?
A reverse-publication flow is planned to allow quick deletion of accidentally published data.
At time of last update, this was open for discussion in [#104](https://github.com/modelcontextprotocol/registry/issues/104).
### Can I publish a private server?
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`).
These are generally not supported on the official MCP registry, which is designed for publicly accessible MCP servers.
If you want to publish private servers we recommend you host your own MCP subregistry, and add them there.
## Security & Trust
@ -101,27 +108,22 @@ A reverse-publication flow is planned to allow quick deletion of accidentally pu
DNS verification ensures namespace ownership. For example:
- `com.microsoft/server` requires DNS verification of microsoft.com
- `io.github.username/server` is tied to a GitHub account or GitHub organization
### What about typosquatting?
The registry implements (or is slated to soon implement):
- Automatic blocking of names within a certain edit distance of existing servers
- Community reporting mechanisms
- `io.github.name/server` is tied to a GitHub account or GitHub organization `name`
### Is there security scanning?
The MVP delegates security to the underlying package registries. Future iterations may include:
- Vulnerability scanning
- Dependency analysis
The MVP delegates security scanning to:
- underlying package registries; and
- subregistries
### How is spam prevented?
- GitHub authentication requirement
- Rate limiting (e.g., 10 new servers per user per day)
- Namespace authentication requirements
- Character limits and regex validation on free-form fields
- Manual takedown of spam or malicious servers
In future we might explore:
- Stricter rate limiting (e.g., 10 new servers per user per day)
- Potential AI-based spam detection
- Community reporting and admin blacklisting capabilities
@ -135,64 +137,42 @@ Recommended polling frequency:
- `/servers/:id` endpoint: once per version (results are immutable)
- Design assumes CDN caching between registry and consumers
Also see [#291](https://github.com/modelcontextprotocol/registry/issues/291), which might mean the above can be more regular.
### Will there be webhooks?
Not in the initial MVP, but the architecture supports adding webhooks for update notifications in the future.
### Can I run my own registry instance?
While the API shapes and data formats are designed for reuse, the registry implementation itself is not designed for self-hosting. Organizations needing private registries should:
Yes! The API shapes and data formats are intentionally designed for reuse by subregistries. Organizations needing private registries should:
- Implement the same API shape
- Use the same `server.json` format
- Potentially mirror/filter the official registry data
### Can I extend the registry API?
Yes, we support `x-com.example` style extensions in a bunch of places - see the official MCP registry API spec. This can be used to add annotations to many objects, e.g. add security scanning details, enrich package metadata, etc.
If you have a use case that can't be addressed here, raise a GitHub issue!
### Can I use the code here to run my own registry instance?
The registry implementation here is not designed for self-hosting, but you're welcome to try to use it/fork it as necessary. Note that this is not an intended use, and the registry maintainers cannot provide any support for this at this time.
## Operations & Maintenance
### What's the expected reliability?
- 24-hour+ downtime tolerance is acceptable, so you shouldn't rely on the registry being always available.
- No direct end-user impact (consumers cache data)
- Relies on CDN for actual availability
- Volunteer maintainer model (no formal on-call)
- This is a community maintained project without full time staffing. You should therefore expect downtime periods of up to 1 business day. No strict guarantees are provided. (Also see discussion in [#150](https://github.com/modelcontextprotocol/registry/issues/150))
- Ideally clients should use subregistries with higher availability guarantees, to avoid direct end-user impact (as subregistries can cache data).
### How are DNS records verified?
### What if I need to report a spam or malicious server?
- Initial verification via TXT records
- Daily re-verification to catch domain transfers
- Publishing blocked if verification fails
- Historical packages remain available with warnings
1. Report it as abuse to the underlying package registry (e.g. NPM, PyPi, DockerHub, etc.); and
2. Raise a GitHub issue on the registry repo with a title beginning `Abuse report: `
### What about GitHub repository transfers?
### What if I need to report a security vulnerability in the registry itself?
The registry tracks GitHub repository IDs (not just URLs) to detect transfers. Daily checks update metadata if repositories move.
### How is namespace transfer handled?
Namespace transfers (e.g., when someone leaves a company) are handled through the DNS verification system and GitHub organization membership.
## Future Considerations
### Will download counts be tracked?
Download count tracking is being considered as a quality signal, but must be designed carefully to not impact CDN caching.
### What about tags or categories?
Categorization and curation are intentionally left to consumers (MCP clients and aggregators) to avoid maintenance burden and subjective decisions.
### Will there be quality metrics?
Quality assessment is explicitly out of scope for the official registry. This is delegated to:
- MCP clients (for their specific use cases)
- Third-party aggregators
- Community reviews on external platforms
### What about internationalization?
Internationalization is a future consideration but not part of the MVP.
### Will private registries be supported?
The registry design (API shapes, data formats) is intended to be reusable for private deployments, but the official registry will only host public servers.
Follow [the MCP community SECURITY.md](https://github.com/modelcontextprotocol/.github/blob/main/SECURITY.md).

17
docs/roadmap.md
View file

@ -10,19 +10,14 @@ The initial version of the MCP Registry is actively being developed. The initial
## Phase 1: MVP/Go-Live (Current Focus)
- [ ] Specification: OpenAPI definition for the official REST API
- [ ] Specification: Extensible OpenAPI definition for marketplace/aggregator consumers to repurpose
- [ ] REST API: Publish workflow
- [ ] REST API: Read workflow
- [ ] CLI: Publish tool
- [ ] CLI/REST API: DNS verification system for namespacing
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)
## 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)
- [ ] Additional IdP support (beyond GitHub)
- [ ] Download count tracking
- [ ] Internationalization (i18n)
## Out of Scope (Not Planned)
@ -32,9 +27,5 @@ The initial version of the MCP Registry is actively being developed. The initial
- **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 tagging**: The registry will not support server tagging
- **Server tags or categories**: Not supported, to reduce moderation burden
- **Server rankings**: The registry will not rank servers by subjective measures of quality
## Contributing
See [CONTRIBUTING.md](../CONTRIBUTING.md) for details on how to contribute to the MCP Registry project.