MCP Registry

What It Does

The MCP Registry is the official, community-owned discovery and publishing service for MCP servers. Think of it as the app store for MCP servers: server authors publish a server.json manifest once, and every consumer (MCP clients, aggregators like Smithery and PulseMCP, marketplaces) reads the same canonical metadata. It is maintained by the modelcontextprotocol org with a named Registry Working Group drawn from PulseMCP, Stacklok, TeamSpark, and Ravenmail, backed by Anthropic, GitHub, and Microsoft. The project ships two things: a REST API specification that anyone can implement, and the official hosted registry at registry.modelcontextprotocol.io. It also includes a Go publisher CLI (mcp-publisher) for creating, validating, and publishing server manifests from the terminal or CI.

The Good

The publisher CLI works end to end against the live registry with precise error reporting. I installed it via Homebrew (v1.8.0, 19.1 MB) and ran mcp-publisher init to generate a server.json template, then mcp-publisher validate against the production API. A valid manifest returned a clean checkmark. A deliberately malformed manifest (missing $schema, invalid name format) returned structured HTTP 422 errors with JSON path locations (body.name, body.$schema) and the exact regex pattern that failed. The validator reports all issues at once rather than failing on the first error, which is the correct behavior for a publishing workflow where authors need to fix everything in one pass.

The codebase is exemplary for an infrastructure project of this scope. The repo holds 142 Go files totaling 34,893 lines of source, with 56 test files containing 231 test functions. The data model in pkg/model/types.go is thorough: six package registry types (npm, pypi, nuget, cargo, oci, mcpb), three transport types (stdio, streamable-http, sse), structured argument types (positional and named), and an icon spec with theme and MIME type support. Seven JSON schema versions are tracked (2025-07-09 through 2025-12-11), each with backward-compatible validation, so older published manifests keep validating as the format evolves.

The namespace ownership model is well designed and security-conscious. Publishing to io.github.user/server-name requires GitHub OAuth login as that user, or a GitHub Actions OIDC token from that user's repos. Domain-based namespaces (com.example.server) require DNS or HTTP verification with Ed25519 or ECDSA P-384 signatures. Cloud signing providers (Google KMS, Azure Key Vault) are documented with copy-pasteable setup commands. This prevents namespace squatting and impersonation, which is the central trust problem for any public registry.

Documentation is thorough and production-grade. The docs directory holds 5,623 lines across markdown and mdx files: an ecosystem vision, design principles, a roadmap, a tech architecture doc, a 1,099-line OpenAPI specification, an 826-line server.json format spec, a full CLI command reference, and official registry requirements. The live API has interactive Stoplight Elements documentation with try-it-now functionality at registry.modelcontextprotocol.io/docs. The README covers Docker image variants (release tags, continuous main builds, development commits) with clear semantics.

The Bad

The full server stack cannot be tested without significant infrastructure. Running the registry locally requires Docker, Go 1.26, the ko container image builder, golangci-lint v2.4.0, and a PostgreSQL database. Of the 18 Go test packages, 9 fail without a running PostgreSQL because the handler and database integration tests need a real connection. The test error message helpfully says to run docker-compose up -d postgres, but on a host without Docker this is a hard wall. The publisher CLI and API client packages (119 test functions across 6 packages) do pass cleanly, but the server-side code paths remain unverified in a no-Docker environment.

CHANGES.md is empty (0 bytes). A project at this maturity level (7,087 stars, 69 contributors, API frozen at v0.1) should maintain a release changelog. The file exists but contains nothing. Release history is only recoverable from git log or the GitHub Container Registry tag list, which is harder for consumers tracking breaking changes across the v0 to v0.1 transition.

The API versioning surface is slightly confusing. Both /v0/servers and /v0.1/servers return live data from the production API, and the documentation references both interchangeably. The generic spec documents /v0.1/ endpoints while many examples use /v0/. A reader has to read the official-registry-api.md extension doc carefully to understand which version is canonical. During testing I hit a 404 on one version-history endpoint because the server name needed URL-encoding of the slash (%2F), which is documented but easy to miss.

The license is in a transitional state that GitHub cannot classify. GitHub reports the license as NOASSERTION because the project is migrating from MIT to Apache-2.0 and some contributions remain under the original MIT terms. The LICENSE file explains the dual-licensing situation in detail, which is honest, but downstream consumers running automated license checks will see "Other" rather than a clean SPDX identifier until the transition completes.

Smoke Test Results

Host-based testing on macOS (aarch64). No Docker or PostgreSQL available, so the full server stack was not run. The publisher CLI and live REST API were tested end to end.

Run A. Fresh install, publisher CLI only

$ brew install mcp-publisher
mcp-publisher 1.8.0 (Homebrew bottle, 19.1 MB) installed

$ mcp-publisher --version
mcp-publisher 1.8.0 (commit: Homebrew, built: 2026-07-12T19:24:34Z)

$ mcp-publisher --help
Commands: init, login, logout, publish, status, validate

$ cd /tmp/pub-test && mcp-publisher init
Created server.json (template with $schema, name, packages, transport)

Pass rate: 3 of 3. The CLI installs, reports its version, and generates a valid template in one command each.

Run B. Build from source with Go 1.26 (with deps)

$ go version
go version go1.26.5 darwin/arm64

$ go test ./cmd/publisher/...
ok cmd/publisher/auth 0.597s
ok cmd/publisher/commands 0.729s

$ go test ./cmd/... ./internal/api/router/ ./internal/auth/ ./internal/validators/... ./pkg/...
ok (6 packages, 119 test functions, all pass)

Pass rate: 6 of 6 non-database packages. The 9 database-dependent packages fail with dial tcp 127.0.0.1:5432: connect: connection refused because no PostgreSQL is running. This is an environment limitation, not a code defect.

Run C. Functional verification (live API and validation)

$ curl -s "https://registry.modelcontextprotocol.io/v0/servers?limit=2"
HTTP 200, returns real MCP server entries with $schema, name, description,
version, remotes, repository, and _meta (status, publishedAt, isLatest)

$ curl -s "https://registry.modelcontextprotocol.io/v0/servers?search=github&limit=2"
HTTP 200, substring search returns matching servers

$ curl -s "https://registry.modelcontextprotocol.io/v0/servers/ac.inference.sh%2Fmcp/versions/latest"
HTTP 200, returns latest version detail with isLatest: true

$ echo '{"$schema":"...","name":"bad-name","description":"x","version":"1.0.0"}' > bad.json
$ mcp-publisher validate /tmp/bad.json
HTTP 422, two structured errors:
 - body.$schema: expected length >= 1
 - body.name: expected string to match pattern ^[a-zA-Z0-9.-]+/[a-zA-Z0-9._-]+$

$ cat > good.json (valid io.github.testuser/example-server manifest)
$ mcp-publisher validate /tmp/good.json
Validating against https://registry.modelcontextprotocol.io...
server.json is valid

Functional pass rate: 5 of 5. List, search, version detail, invalid validation, and valid validation all behave exactly as documented.

What the runs tell you

The publisher CLI and REST API are production-ready and match the documentation precisely. The validation engine catches real schema and semantic errors with actionable JSON-path feedback. The gap is the server itself: without Docker and PostgreSQL, half the test suite and the entire local-server experience are out of reach. For consumers (which is most users), this does not matter. For contributors and self-hosters, the infrastructure bar is real.

Setup Walkthrough

1. Install the publisher CLI: brew install mcp-publisher. This gives you init, validate, publish, status, login, and logout. Version 1.8.0 is current.
2. Generate a server manifest: cd your-project && mcp-publisher init. Fill in the name (must be io.github.youruser/server-name or com.yourdomain.server-name), description, version, and package details.
3. Validate locally before publishing: mcp-publisher validate. This hits the live registry's validation endpoint and reports any schema or semantic issues.
4. Authenticate: mcp-publisher login github (browser OAuth) for GitHub namespaces, or mcp-publisher login dns --domain=example.com --private-key=HEX for domain namespaces.
5. Publish: mcp-publisher publish.
6. To run the full registry server locally (self-hosting or contribution), you need Docker, Go 1.26, ko, and golangci-lint. Run make dev-compose to start the registry at localhost:8080 with PostgreSQL and seed data pulled from production.

Post-install gotcha: the local database uses ephemeral storage and resets on every container restart. For offline development, seed from the bundled data/seed.json with MCP_REGISTRY_SEED_FROM=data/seed.json MCP_REGISTRY_ENABLE_REGISTRY_VALIDATION=false make dev-compose.

Alternatives

1. Smithery - a subregistry that ETLs from the official registry and adds curation, one-click install, and a hosting layer. Prefer it when you want a managed marketplace experience rather than raw canonical data.
2. PulseMCP - another subregistry with ratings and enhanced discovery. Same relationship: it enriches the official registry's data rather than competing with it.
3. Glama MCP Registry - a community directory (61,091 servers at time of writing) with broader coverage including servers not yet in the official registry. Useful for discovery, but it is not the authoritative source.