MCP Server Registry Design and Implementation

The MCP Registry is a metaregistry. It stores metadata about servers, not code, not binaries, not runtime traffic. That boundary is the whole point, and if you miss it, you'll spend months building infrastructure the registry was never meant to provide.

Think of the registry as a card catalog, not a library. If you publish a weather server as an npm package, the registry entry maps "weather v1.2.0" to npm:weather-mcp. The registry is the pointer. The payload lives on npm, PyPI, NuGet, or an OCI-compatible image repository, wherever it was always going to live. Offloading binary distribution and vulnerability scanning to existing package ecosystems means the registry avoids duplicating infrastructure that already works, and keeps its own performance burden low. Metadata is cheap to serve and cache. Binaries are not.

What the registry owns is still significant: authoritative metadata, namespace identity, version records, and the API contract that downstream clients and subregistries consume. It does not proxy or mediate runtime traffic between agents and servers. If you understand that early, you know exactly where your governance hooks need to live elsewhere in the stack.

Five design principles animate every architectural choice that follows: single source of truth, vendor neutrality, reuse of industry security standards, reusable API shapes, and progressive enhancement. David Soria Parra and Justin Spahr-Summers bootstrapped the early effort in February 2025, drawing on work from PulseMCP and Goose. The official registry launched in preview on September 8, 2025. That provenance, community-driven rather than vendor-controlled, shapes every tradeoff in the design.

How the server.json Manifest Encodes Everything a Client Needs to Know

Every server is described by a server.json file. The schema is versioned; the latest is dated 2025-12-11. Required fields are deliberately minimal: name, version, description. The barrier to publish is low by design, which is either a feature or a risk depending on how your organization governs what goes in.

The name field carries more structural weight than it appears to. It encodes namespace and server identifier in reverse-DNS format, tying identity to a verifiable owner before any runtime connection is attempted. That's not a naming convention, it's the foundation of the trust model, and everything else in the schema builds on top of it.

Deployment descriptors split cleanly by server type. The packages descriptor covers installable local servers, referencing npm, PyPI, NuGet, and OCI registries. The remotes descriptor covers hosted endpoints, supporting SSE and streamable-HTTP transport types. Auth declarations in the remotes object surface credential requirements at the schema level, before runtime. The headers array includes isRequired and isSecret flags, so clients know the auth scheme before they attempt a connection. In practice, that means fewer silent failures and more debuggable integration paths.

The _meta extension field uses reverse-DNS keyed namespaces, giving publishers a governed extension point without polluting the core schema. For enterprise teams, this is where audit tags, approval status, and team ownership metadata can attach without forking the spec. The November 2025 spec update added an optional description field to the Implementation interface specifically to align initialization handshakes with the server.json format, a quiet signal that the manifest is becoming a protocol-level contract, not just a catalog artifact.

Teams that understand the optional fields early can extend the registry to meet governance requirements without building parallel systems. Those that don't discover this the hard way, somewhere around their third internal audit.

How Namespace Ownership Is Verified and Why That Shapes the Trust Model

The reverse-DNS name format is not cosmetic. It encodes the authentication path, and the distinction between those two things is where a lot of implementations go wrong.

A server named io.github.username/server requires GitHub authentication. A server named com.example/server requires proof of domain ownership for example.com. Four mechanisms support this: GitHub OAuth for interactive flows, GitHub OIDC for CI/CD pipelines, DNS TXT record verification, and HTTP file verification. The GitHub OIDC path matters most for teams shipping frequently, because a publish-on-merge pipeline works without embedding credentials anywhere. That is a supply-chain security property: it means credentials are not embedded in pipeline configuration.

Version immutability is enforced at publish time. Re-publishing an existing version fails. This prevents silent overwrites — one of the most consequential supply-chain risks in any package ecosystem, and one that goes unnoticed until it's too late to trace.

What the namespace model does not solve is equally worth understanding. It verifies that a publisher controls a namespace, which answers "who published this?" but says nothing about "should my agents be allowed to call it?" Teams that treat those as equivalent questions will build incomplete governance models. The registry was designed to answer only the first question. That responsibility sits at the runtime layer, and you need to build for it separately.

The REST API Contract That Clients and Subregistries Build Against

The API is specified in OpenAPI 3.1.0. Three key endpoints define the surface: GET /v0/servers for listing and searching with pagination, GET /v0/servers/{server-id} for retrieving a specific record, and POST /v0/servers for authenticated publishing.

Pagination uses a cursor-based design. Responses include metadata.nextCursor for sequential fetching, with page size capped at 100 results. The updated_since parameter, formatted in RFC 3339, enables incremental sync, so subregistries can poll for changes since their last fetch rather than re-ingesting the full catalog on every cycle. For organizations maintaining large internal registries, that particular detail determines whether sync is fast or punishing.

The API freeze at v0.1, announced October 24, 2025, is a meaningful commitment: no breaking changes. Integrators have a stable surface to build against, which is the actual prerequisite for serious enterprise tooling investment.

Because the registry serves metadata rather than live data, caching works cleanly. ETag and conditional request patterns apply without friction, TTL-based caching is straightforward, and subregistries are expected to absorb availability risk by caching upstream data locally. Schema versioning is the mechanism for evolving the metadata contract without breaking existing consumers. Private registry implementations should replicate that pattern rather than treating schema evolution as something to handle ad hoc when it becomes urgent.

How the Reference Implementation Is Structured Under the Hood

The repository layout reflects a clear separation of concerns. Internal packages handle HTTP routing and handlers, GitHub OAuth and JWT auth, namespace blocking, PostgreSQL persistence, business logic, metrics and monitoring, and input validation. Public packages expose API types and data model types for consumers building against the registry. Each layer has a defined responsibility and a defined boundary.

The development stack is containerized. ko handles image builds; make dev-compose orchestrates a local PostgreSQL instance alongside the registry itself. The dev database is ephemeral, resetting on restart, which keeps local development clean. Pre-built images are published to GitHub Container Registry, and the toolchain is opinionated toward cloud-native deployment.

One operational caveat deserves direct treatment: the reference implementation is not designed for self-hosting. It is community-maintained without full-time staffing, and the project documentation explicitly acknowledges that downtime of up to one business day should be expected. It is a blueprint, not a production SLA.

For enterprise teams, the reference implementation is where you go to understand design decisions, not the artifact you ship. Production registries require either a managed layer on top or a fork with explicit availability commitments. The telemetry module is present in the reference but underdocumented; teams building internal registries should treat observability as a first-class design requirement rather than something they expect to inherit from the community codebase.

Federation and the Subregistry Pattern That Makes Enterprise Adoption Practical

The official registry is designed to be one registry, not the only registry. Federation is a first-class architectural principle, and it's what makes the design viable at anything approaching enterprise scale.

Two subregistry types serve distinct purposes. Public subregistries function as marketplaces tied to specific clients or communities; they can enrich metadata with ratings, audit information, and curated search results. Private enterprise subregistries combine approved public servers with internal ones, apply custom access policies, and present a consistent API surface to all internal clients. Because subregistries reuse the upstream OpenAPI schema and metadata contracts, SDKs and tooling built for the public registry transfer to private deployments without modification. You don't rebuild the integration layer for each environment.

The practical enforcement model is straightforward. An organization points its agents at its private subregistry and restricts usage to the servers listed there. The subregistry becomes the allowlist. GitHub Copilot can be configured to point at an MCP registry to restrict developers to approved servers. Azure API Center and MCP Gateway Registry both respect the registry specification.

Subregistries add value beyond simple pass-through: curation, security scanning, vulnerability checks, approval workflows, and enterprise-specific metadata like team ownership tags. They also carry an availability benefit that matters operationally. By caching upstream data locally, a private subregistry insulates internal agent workflows from upstream outages, which directly compensates for the availability limitations of the community reference implementation. That's an intended consequence of the architecture, not a workaround.

The Security Threats That Registry Architecture Must Account for by Design

The attack class most directly implicating the registry layer is server spoofing and name-squatting: registering a server name that resembles a trusted one to intercept agents during configuration or update. OWASP's first MCP Top 10, published in mid-2025, explicitly identifies server spoofing as a primary supply-chain risk requiring registry-level verification, and names the registry as the mitigation layer.

Tool poisoning is a distinct threat. Adversarial instructions embedded in tool descriptions, parameter schemas, or response content can direct agents to take unintended actions, because agents treat this content as trusted operational context. Invariant Labs named and demonstrated this attack class in April 2025, and working exploits against production MCP servers followed within months. Microsoft researchers disclosed a related attack class in July 2026 showing how malicious tool descriptions can direct agents to leak sensitive data. There is no native MCP mechanism that currently detects or prevents these injections, and the registry's metadata layer cannot address tool poisoning on its own. Runtime inspection is required.

Four CVEs in the MCP layer emerged within a single year: CVE-2025-6514, CVE-2025-49596, CVE-2025-54136, and CVE-2025-54994. The vulnerability surface is real, not theoretical. Access scoping and credential hygiene remain broadly unimplemented across MCP deployments; a significant share expose credentials through hard-coded configuration values.

Abandoned and broken servers proliferate in open catalogs. The base spec provides no quality or maintenance signals. Subregistry-level curation and security scanning are necessary complements to namespace verification, not optional features for organizations that care about this. The registry answers "who published this?" The threat landscape demands that enterprise deployments also answer "is this server still maintained?", "has it been scanned for known vulnerabilities?", and "is my agent's access to it scoped and logged?"

What a Governance-Ready Registry Implementation Needs Beyond the Spec

The spec gives you discovery. It does not give you control. Most enterprise registry implementations underinvest in exactly that gap, then feel it later, usually after something breaks in production.

Four capabilities are absent from the base spec but essential for serious deployments. Runtime access control determines which agents can call which servers and enforces that determination at the gateway layer; RBAC for agents is an organizational decision that must be made explicitly, because the default is no enforcement. Real-time observability means a record of what an agent accessed, surfaced as it happens, because an audit log read after an incident is a postmortem, not a safety mechanism. Server lifecycle governance covers approval workflows, deprecation signals, and ownership tracking, and every unregistered server is an identity that cannot be accounted for. Policy enforcement at the subregistry layer is what makes the allowlist model actually work, and it must be consistent across all client entry points, not applied selectively where it's convenient.

The case for building governance in from the start rather than retrofitting it is not primarily about security posture. It's about velocity. Teams with access controls and observability in place can approve production deployments faster, because the conversations that slow those approvals down are almost always about the absence of a governance layer, not the presence of one. Retrofitting is slower and more expensive, and it happens under the worst possible conditions.

Several registry design choices pay forward into governance. Immutable version records prevent silent substitution. Auth declarations in the schema surface credential requirements before runtime. The _meta extension field provides a governed path for attaching enterprise metadata without diverging from the spec. These choices compound across a mature deployment in ways that are hard to fully appreciate until you've watched a team try to reconstruct audit history from a registry that wasn't built with any of them.

MCPManager is an example of this pattern in practice. It sits between agents and servers as a gateway layer, enforcing access controls derived from namespace identity and capturing the observability that a registry alone cannot provide. Approval workflows, RBAC, and real-time visibility into agent-to-server traffic are capabilities in that model.

The namespace model, the schema extension points, the federation pattern, the API contract: these design decisions add up to something that can carry genuine operational weight. Treat the registry as infrastructure and you'll have something to build on. Treat it as a list of servers and you'll eventually reconstruct the governance layer yourself, from scratch, under pressure, after something has already gone wrong.