MCP Server Registry and Discovery Mechanics

Before the registry existed, finding an MCP server meant asking around. GitHub searches, Discord threads, someone's README linked from a forum comment. If you were lucky, you found the right repo. If you were less lucky, you found a fork from three months ago that hadn't tracked upstream changes and had no indication it ever would.

The fragmentation wasn't just inconvenient; if you were an organization deploying agents and someone asked which servers you were actually running, who published them, what version was live right now, you had no clean answer. No namespace enforcement meant anyone could publish anything under any name. Impersonation wasn't a theoretical risk; it was latent chaos, and deployment pipelines got hand-configured per server, per team. That compounds fast.

The registry didn't originate from a corporate roadmap; in February 2025, MCP maintainers David Soria Parra and Justin Spahr-Summers recruited the PulseMCP and Goose teams to build a centralized community registry. Grassroots, not top-down. The formal release came September 8, 2025, when Anthropic and the MCP maintainers launched registry.modelcontextprotocol.io as an open catalog and API. Sixteen contributing individuals from at least nine companies were named at launch, which signals something: multi-stakeholder ownership was intentional from the beginning, not retrofitted for optics after the fact.

On October 24, 2025, the team froze the API at v0.1, guaranteeing no breaking changes for at least a month. Freeze-then-iterate is a discipline you only see from teams that have shipped infrastructure before; it communicates something specific: people are already building on top of this, and stability has value independent of features.

The governance arc completed December 9, 2025, when MCP was contributed to the newly formed Agentic AI Foundation under the Linux Foundation. Platinum members include AWS, Anthropic, Block, Bloomberg, Cloudflare, Google, Microsoft, and OpenAI, with over 150 member organizations at launch. The Agentic AI Foundation governs strategic investments and membership, but individual projects like MCP retain full autonomy over technical direction. Those are different things; the registry is now neutral infrastructure with broad industry backing, not a single vendor's proprietary catalog redressed as a community good.

The Meta-Registry Design: What the Official Registry Stores and What It Deliberately Does Not

Here's where most people's mental model breaks down. The official registry does not host MCP servers. It stores metadata and installation instructions, and it points to where actual artifacts live: npm, PyPI, Docker Hub, container registries. It doesn't proxy them, run them, or mirror their contents.

Think of it less like a warehouse and more like a card catalog. The books are elsewhere. The catalog tells you what exists, where to find it, and enough about it to know whether you want it.

But what if that separation introduced more problems than it solved? That design choice has real downstream consequences, and they're worth tracing. Artifacts stay in registries that already have security scanning, CDN infrastructure, and service-level guarantees. The MCP registry doesn't replicate any of that, because it doesn't need to. Keeping scope narrow to discovery also keeps the attack surface narrow; an attacker who compromises the discovery layer gets metadata. The actual supply chain integrity work happens where it always did, in the artifact registries.

Supported package sources as of 2025 are specific and restricted: NPM via registry.npmjs.org only, PyPI via pypi.org only, NuGet via api.nuget.org only, Docker and OCI images via Docker Hub, GitHub Container Registry, Quay.io, Google Artifact Registry, Azure Container Registry, and Microsoft Container Registry. Binary packages use GitHub and GitLab releases. Packages must point to these trusted registries, not arbitrary URLs. Those restricted base URLs are the first layer of supply chain integrity built into the schema itself, not patched in afterward.

The registry also explicitly does not serve organizations running private servers accessible only to a narrow set of users. Those organizations run their own registry instances. The official registry is upstream infrastructure; it expects aggregators and private instances below it.

The server.json Schema: How a Server's Identity and Capabilities Are Encoded

The server.json file is a static, machine-readable definition that travels from publisher to registry to client. Any MCP-compliant client or agent can parse it without custom integration work. That's the whole point of standardization: write it once, parse it everywhere.

The core fields are each doing real work, and it's worth slowing down on them.

The $schema field points to a versioned JSON Schema URL. Without versioning, you get silent format drift, the kind of thing that produces bugs six months later that nobody can explain. The name field uses a reverse DNS naming scheme, something like com.microsoft.playwright. This isn't cosmetic; the namespace encodes ownership, and a client seeing com.microsoft.* knows that server's provenance traces back to microsoft.com. That's the trust-building block on which namespace authentication rests.

The version field, combined with name, forms the unique identifier for a specific server release. The packages field points to the actual artifact in npm, PyPI, Docker, wherever it lives. The remotes field carries endpoint information for HTTP servers.

The _meta field has a split behavior worth understanding carefully. In a server.json file, it holds publisher-provided custom metadata under a reserved namespace. In API responses, it becomes registry-managed metadata: status flags like active, deprecated, or deleted, along with publication and update timestamps and an isLatest indicator. Clients can distinguish publisher claims from registry-verified state. That separation matters considerably when you're building trust hierarchies across dozens of servers from publishers you've never vetted personally.

On top of the schema, the registry enforces namespace authentication, package ownership verification, restricted registry base URLs, and restrictions on what publishers can write into the _meta namespace. Publishers cannot forge registry-managed fields.

Before server.json existed, clients had to parse bespoke READMEs or ad hoc config formats, none of which were automatable at scale. A common schema is what makes automated agent discovery possible; agents can query and parse without human mediation, which is the entire premise of the system working the way it's supposed to.

How Namespace Ownership Is Verified Before a Server Can Be Published

The namespace verification system is where the registry does its most consequential security work, and it's worth being precise about what it actually covers and what it doesn't.

Publishers must prove they control a namespace before any submission is accepted; this closes the impersonation vector that made the pre-registry landscape risky, not hypothetically risky. But what does "proving control" look like in practice, and does it hold under adversarial conditions?

Two verification paths exist depending on the namespace type.

For GitHub namespaces (io.github.), the publisher must be authenticated as the relevant GitHub user, or authenticated via GitHub Actions running on that user's repositories. The CI/CD case is genuinely elegant: GitHub OIDC authentication lets pipelines publish with only id-token: write permission, no stored secrets required. To publish io.github.domdomegg/my-cool-mcp, you need to be, or act as, that GitHub user. For domain namespaces (com.yourcompany.), the URLs referenced must resolve to yourcompany.com or its subdomains, verified via a DNS TXT record in the form v=MCPv1; k=ed25519; p=<public_key>, authenticated using an Ed25519 keypair through the mcp-publisher CLI.

Package ownership verification runs alongside namespace verification. Publishing com.example/server also requires proving control of the packages referenced under example.com. An attacker would need to compromise both independently, which raises the bar substantially.

What this prevents is squatting and impersonation at publish time. What it doesn't prevent is a legitimately owned namespace shipping a server with vulnerabilities or malicious behavior. Authentication is identity, not a security audit. That raises an important question: if the registry handles identity well but says nothing about behavior, what does "trust" actually mean in this context? Organizations consuming servers at scale still need runtime observability, behavioral analysis, and their own vetting layers on top of what the registry provides. The registry handles a narrow problem well; it does not solve the broader one, and confusing those two things will eventually cost someone.

How the REST API Exposes the Registry for Client and Agent Queries

The base URL is https://registry.modelcontextprotocol.io. The current stable path is /v0/servers, also accessible as /v0.1/servers.

Three core endpoints do most of the work. GET /v0/servers lists and searches all servers with pagination. GET /v0/servers/{name}/{version} fetches a specific server version by exact coordinates. GET /v0/servers/{name}/versions enumerates all available versions for a given server.

Pagination is cursor-based, not page-number-based. Each response includes a metadata.nextCursor field; you pass it as the cursor query parameter to retrieve the next page. Hard limit is 100 results per page, and when nextCursor is null or empty, you've reached the end. Clients must treat cursors as opaque strings, not parse or construct them. Cursor-based pagination ensures stable traversal even when the underlying dataset changes mid-iteration, something page-number pagination cannot guarantee. That stability matters when you're building an aggregator that runs continuously against a live catalog.

The updated_since filter accepts RFC 3339 timestamps and lets downstream consumers pull only what changed since their last sync. Server metadata is generally immutable; the main exception is the status field, which can transition from active to deprecated to deleted. Aggregators don't need to re-fetch the full catalog daily. They fetch diffs, which is a meaningful operational efficiency for anyone building seriously on top of the registry.

One thing the official registry does not promise: uptime or data durability SLAs. The official guidance is that downstream applications must handle service downtime via caching. This is by design. The registry is upstream infrastructure; sub-registries provide the reliability layer for end users. Expecting production-grade uptime from the upstream reflects a misreading of the architecture, though I've seen experienced engineers make that assumption on first contact with the system.

How Sub-Registries Extend Discovery into Specialized and Enterprise Contexts

The registry's OpenAPI spec is open source. Anyone can build a compatible sub-registry. In practice, sub-registries periodically pull the upstream dataset, often once per day, then apply their own logic before serving downstream.

Three transformations recur across implementations: vetting and filtering, which excludes servers that don't meet security or quality thresholds; augmentation, which adds platform-specific metadata; and caching, which provides the high availability and low latency the upstream explicitly doesn't guarantee. The _meta field is the injection point for augmentation; sub-registries can add user ratings, download counts, security scan results, and container configuration while staying compatible with the shared schema.

PulseMCP, one of the community directories that predated the official registry, implements the v0.1 spec with authentication, rate limiting, and enriched metadata including visitor estimates and official status flags. The GitHub MCP Registry takes a different approach: a curated directory backed by repository provenance, integrated with the Copilot toolchain. mcp.so occupies the breadth end of the spectrum, listing over 20,000 servers as of mid-2026. Breadth and curation pull against each other, and mcp.so makes the tradeoff explicit.

ToolHive from Stacklok is the most instructive case for enterprise contexts. It extends the schema with OCI permissions, provenance data, Docker tags, and proxy port fields for container servers. That's a concrete demonstration of how enterprise requirements drive schema extension without breaking upstream compatibility. The shared schema accommodates enrichment without requiring it, which is the right design decision if you want both a flourishing public commons and viable enterprise adoption.

It is also worth considering what this layered architecture demands of the teams consuming it. Private registries for internal tooling follow the same OpenAPI spec. An organization can run its own MCP registry instance for servers that should never be publicly discoverable, and that internal registry can federate or selectively sync with the upstream as needed. The architecture anticipated this use case early, which is one reason it held up as enterprise interest accelerated.

What Ecosystem Growth Reveals About Registry Adoption and the Remaining Gaps

The speed of this ecosystem's formation is itself informative, and a little disorienting if you've watched infrastructure projects develop slowly over years. From a grassroots recruitment effort in February 2025 to a Linux Foundation contribution by December of the same year, the registry moved through what would normally take years of maturation in under twelve months.

The proliferation of sub-registries tells a similar story, and a somewhat uncomfortable one. When mcp.so is listing tens of thousands of servers and enterprise-focused registries are extending the schema with provenance and permissions fields, you're looking at an ecosystem that outpaced its own governance scaffolding. Infrastructure that grows faster than its oversight mechanisms creates gaps, and some of those gaps are the kind that surface badly.

Namespace verification proves identity at publish time but says nothing about what a server does at runtime. A legitimately owned namespace can still ship a malicious tool. The registry's scope is discovery and identity; behavioral trust has to be constructed elsewhere, through runtime monitoring, policy enforcement, and organizational vetting processes that most teams haven't built yet. The tooling for that layer is still nascent, and the teams that will need it most are probably the ones least equipped to notice the absence.

The lack of an uptime SLA on the official registry sounds like a minor architectural note until you watch a team build a production dependency on upstream availability without caching. The architecture is sound; the on-ramp is genuinely steep, and documentation addressing that gap directly is sparse.

There's also the question of what "adoption" actually measures at this layer. Server count metrics, whether from the official registry or community directories, measure publication, not use. A server listed is not necessarily a server running in production, serving real agent traffic. The ecosystem will need better observability primitives before anyone can say with real confidence which parts of the registry graph are load-bearing and which are aspirational. That's where the next set of hard questions lives, and nobody has clean answers yet.