MCP Registry: publishing and discovering MCP servers

The gap the MCP Registry fills between clients and servers

An MCP client needs to know which servers exist before it can connect to any of them. The README describes the project as providing MCP clients with a list of MCP servers, and calls it "like an app store for MCP servers". That comparison is the whole scope. It is not a runtime proxy, not a sandbox, and not a package manager that installs anything for you. It is an index with a publish path and a read path.

The audience is narrow and worth stating plainly. Server authors publish metadata about their server so clients and directories can find it. Client authors query the API to populate a list of available servers. Everyone else, including teams looking for a general artifact repository, is outside the target. The repository is community driven, with a Registry Working Group listed in the README and four named members from Stacklok, PulseMCP, TeamSpark and Ravenmail.

Architecture: Go API server, PostgreSQL, and a separate publisher CLI

The repository layout splits the system into two binaries under cmd/: registry, the API server, and publisher, the publishing tool. Everything private sits under internal/, with api/ for HTTP handlers and routing, auth/ for GitHub OAuth, JWT and namespace blocking, database/ for PostgreSQL persistence, importer/ for seed data, service/ for business logic, telemetry/ for metrics, and validators/ for input validation. Public types live under pkg/, including pkg/api/v0 for the version 0 API types and pkg/model for the server.json data model.

The dependency list in go.mod confirms the shape of the service. It uses huma/v2 for the HTTP layer, pgx/v5 for PostgreSQL, golang-jwt/jwt/v5 for tokens, coreos/go-oidc/v3 for OIDC, santhosh-tekuri/jsonschema/v5 for schema validation, and the OpenTelemetry SDK with a Prometheus exporter for metrics. Cloud KMS and Azure Key Vault clients are present, which points at signing or key handling in the auth path rather than plain symmetric secrets.

Data flow is one direction on the write side and one on the read side. A publisher authenticates, submits a server record that is validated against registry rules, and the record lands in PostgreSQL. On startup the server can import seed data from a URL or a local file through the importer package. The default seed source in docker-compose.yml is a filtered query against the production API, which the README explains keeps startup fast and guarantees the seed data passes validation.

Installing the MCP Registry with make dev-compose

The README lists four prerequisites: Docker, Go at the version in the go directive in go.mod (the toolchain fetches it), ko as the container image builder, and golangci-lint pinned to match CI. With those in place, one make target brings up the whole stack.

make dev-compose

That target starts the registry at localhost:8080 together with PostgreSQL. The README states the database uses ephemeral storage and is reset on every container restart, so you get a clean state each time. The dev-compose target builds the image with ko and loads it into the local Docker daemon before starting services. Because the default seed pulls from the production API, first startup depends on network access.

For offline work the README gives an environment-variable override that seeds from a file and skips validation.

MCP_REGISTRY_SEED_FROM=data/seed.json MCP_REGISTRY_ENABLE_REGISTRY_VALIDATION=false make dev-compose

The second variable matters: the README notes data/seed.json is not guaranteed to pass validation, which is exactly why the flag exists. If you leave validation on and point at that file, expect import failures.

If you would rather not build anything, pre-built images are published to GitHub Container Registry. The image does not bundle PostgreSQL, so you have to run your own and point the registry at it through MCP_REGISTRY_DATABASE_URL.

docker run -p 8080:8080 ghcr.io/modelcontextprotocol/registry:latest

The README documents the tag scheme: latest and version tags such as v1.0.0 for releases, main for continuous builds, and main-<date>-<sha> for specific commits. Note that the example above starts the registry without a database behind it, so it is not a complete deployment on its own.

Publishing is a second binary. Build it and inspect its interface before using it.

make publisher
./bin/mcp-publisher --help

The README points to the publisher guide at docs/modelcontextprotocol-io/quickstart.mdx for the actual publish workflow, and that document is where the authentication and namespace steps live rather than in the README itself. Read it before you attempt a first publish.

Where the MCP Registry is the wrong tool

The project is in preview, and the README is unusually direct about it. The 2025-09-08 note says that while the system is more stable than before, this is still a preview release and breaking changes or data resets may occur. A later note announces an API freeze on v0.1 for a month or more, explicitly to let integrators implement support, while development continues on v0. If you need a durable index whose identifiers will never move, that is a real risk to weigh, not a hypothetical one.

There is a second boundary the README does not address at all: it does not document rollback, and it does not describe what happens to a published record if you later want it removed. If your compliance process requires a documented unpublish or takedown path, you will not find it in the README, and you should treat that silence as an open question rather than assume an answer.

The licence is also worth flagging. The repository metadata reports NOASSERTION, and the README does not explain the terms. There is a LICENSE file at the top level, so the answer exists, but it is not stated where a reader of the README would see it. Anyone embedding this in a commercial product should read LICENSE directly instead of inferring terms from the project's open governance.

Finally, the local development story assumes Docker and Go. If your environment cannot run containers, the make dev-compose path is closed to you and you are left with the pre-built image plus your own PostgreSQL, which is still a container-shaped deployment.

Alternatives and how their approach differs

The obvious alternative is to run no registry at all and have each MCP client hard-code the servers it knows about, or read them from a local config file. That approach has no shared namespace, no validation step and no publish workflow, but it also has no dependency on an external service and no preview-stage API to track. For a single team wiring two or three internal servers, a config file is genuinely simpler, and the registry's value only appears once you want discovery by people you have never met.

A second alternative is a general-purpose package or container registry that you already operate. Those solve distribution of artifacts, and the MCP Registry deliberately does not: the README frames it as a list of servers for clients, not a place that serves binaries or images. If your need is artifact hosting, a container registry is the right tool and this one is not, even though the project publishes its own images to one.

The distinguishing design choice is the validation and namespace model. Submissions are checked against registry rules through the validators package and a JSON Schema dependency, and namespace ownership is enforced in the auth package with GitHub OAuth, GitHub OIDC token exchange and generic OIDC. A plain list of URLs has none of that. Whether the validation is worth the constraint depends on whether you want a curated index or just a directory.

Maintenance, releases and what upgrading costs

The repository is not archived, and the last push was on 2026-09-09. Releases are frequent and versioned: v1.8.1 on 2026-08-06, v1.8.0 on 2026-07-13, and v1.7.9 on 2026-05-12. Continuous deployment builds are published from main, so there are two upgrade tracks with different risk profiles, and the README's tag list makes that explicit.

Upgrade cost concentrates in the API surface. The freeze covers v0.1 only, and the README states development continues on v0, which means the version you integrate against determines whether you are on stable ground. The API types are versioned in the repository under pkg/api/v0, so the version boundary is visible in code and not just in prose.

On the operator side, the configuration surface is environment variables documented in .env.example and consumed through docker-compose.yml. That file ships development defaults, including a GitHub client ID and secret described as belonging to a local GitHub App with no real privileged access, an anonymous-auth flag set to true, and a JWT seed. The .env.example comments say anonymous authentication should be disabled in production and that the JWT value should be a 32-byte Ed25519 seed generated with openssl rand -hex 32. Anyone deploying beyond localhost should treat every one of those defaults as something to replace, not inherit.

The licence question is unresolved in the README. Metadata reports NOASSERTION and the README does not describe terms, so verify LICENSE before redistributing or embedding the service.

Editorial conclusion

Adopt the MCP Registry if you maintain an MCP server you want listed, or if you are building a client that needs a server index and can tolerate a preview API. Do not adopt it as a general-purpose package index or as a private internal catalog; it is scoped to MCP servers and the README states the preview may still reset data. Before wiring anything into a release pipeline, read docs/modelcontextprotocol-io/quickstart.mdx, check which registry host the publisher CLI targets, and decide whether your namespace ownership is GitHub OAuth, GitHub OIDC or OIDC. The API freeze applies to v0.1 only, and the README says development continues on v0, so pin the API version you integrate against.

Frequently asked questions

Official sources

1. Issues
2. modelcontextprotocol/registry on GitHub
3. Project website
4. README
5. Releases