The MCP Registry: How Agents Find Servers, Dissected

The MCP spec that finalized yesterday tells agents how to talk to servers. It says nothing about how to find them. That job belongs to the official MCP Registry — a deliberately boring metadata layer that is quietly becoming the root of server discovery. We dissect it, then crawl its live API to measure what is actually inside.

This blog has covered two discovery layers already. x402 Bazaar indexes paid endpoints and ranks them by real settlement activity. ERC-8004 puts agent identity on-chain — and the first empirical audit found most registrations are placeholders pointing at dead endpoints. The MCP Registry is the third layer, and the least glamorous: it answers the question "what is this server called, and where do I get it." It turns out that answering only that question, and refusing to answer anything else, is the most interesting design decision in the whole system.

A metadata layer, not an app store

The registry launched in preview on September 8, 2025 at registry.modelcontextprotocol.io, announced as "an open catalog and API for publicly available MCP servers". Development was led by PulseMCP, Block's Goose team, GitHub, and Anthropic, with contributors spanning nine companies. Day to day it is governed by a registry working group with members from PulseMCP, Stacklok, TeamSpark, and Ravenmail. The codebase is open source — Go and PostgreSQL.

The first thing to understand is what it does not host: code. Packages live where they always lived — npm, PyPI, Docker Hub. The registry hosts metadata that points at them. The official docs use the example of a weather-mcp package on npm: the registry entry maps "weather v1.2.0" to npm:weather-mcp. Security scanning is explicitly delegated to the underlying package registries and to downstream consumers. Private servers are out of scope entirely — anything behind a corporate network or a private package registry is expected to live in a private registry instead.

The second thing to understand is its maturity posture. Ten months after launch, the registry is still labeled preview, and the docs warn that breaking changes or data resets may occur before general availability. The API, however, entered a freeze at v0.1 in October 2025 so that integrators could build against it with confidence, with a v1 planned for GA. That combination — frozen read API, preview data guarantees — shapes everything downstream, as we will see.

server.json: the unit of publication

Every entry in the registry is a server.json document, validated against a versioned schema (current: 2025-12-11, hosted at static.modelcontextprotocol.io). The name uses reverse-DNS plus a slash: io.github.username/weather, com.example/server. Beyond name, description, and version, the document has two mutually complementary sections: packages for servers you install, and remotes for servers you connect to.

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
  "name": "io.github.my-username/weather",
  "description": "An MCP server for weather information.",
  "version": "1.0.1",
  "packages": [
    {
      "registryType": "npm",
      "identifier": "@my-username/mcp-weather-server",
      "version": "1.0.1",
      "transport": { "type": "stdio" },
      "environmentVariables": [
        { "name": "YOUR_API_KEY", "isRequired": true, "isSecret": true }
      ]
    }
  ]
}

The packages array supports six registry types — npm, pypi, cargo, nuget, oci, and mcpb — each entry declaring its transport (stdio or streamable-http), an optional runtimeHint like npx, plus structured runtimeArguments and packageArguments (positional or named, with templated variables) and environment variables flagged isRequired and isSecret. That last part matters more than it looks: a client can render a correct configuration UI for any server without ever reading its README.

The remotes array is the part a gateway operator cares about: entries of type streamable-http or sse with a URL. No package, no install step — the server is a hosted endpoint you connect to. And everything else goes in _meta, an extension bag namespaced by reverse DNS, the same convention the 2026-07-28 spec adopted for protocol extensions. Publisher-provided extras live under io.modelcontextprotocol.registry/publisher-provided; anyone else picks their own key.

Namespaces are the identity layer

The registry's trust model is concentrated in one place: proving you own the name you publish under. io.github.* namespaces are verified through GitHub OAuth (or GitHub OIDC from Actions, for CI publishing). Custom domains — com.example/* — are verified through a DNS TXT record or an HTTP challenge. Publishing happens through the mcp-publisher CLI: init scaffolds the server.json, login github runs a device flow, publish pushes the document.

On top of namespace verification sits package ownership validation. For an npm package, the registry requires an mcpName field inside package.json that exactly matches the registry name. Publish metadata claiming someone else's package and the registry rejects it: the artifact itself must point back at the name. This closes the exact gap the ERC-8004 audit exposed on-chain, where anyone could register an identity wrapping any URL and only 3–15% of entries resolved to a valid live registration file. In the MCP Registry, an entry is at minimum bound to a real, owned artifact.

The API: small, frozen, cursor-paginated

The read API is minimal and has been stable since the freeze. Three endpoints matter: GET /v0.1/servers lists everything, GET /v0.1/servers/{name}/versions lists one server's versions, and GET /v0.1/servers/{name}/versions/{version} fetches one document — with latest as a special version alias. Server names contain a slash, so they must be URL-encoded: io.modelcontextprotocol/everything becomes io.modelcontextprotocol%2Feverything. The list endpoint takes cursor and limit for pagination, search for substring matching on names, version=latest to collapse to current versions, and — the parameter that makes the whole consumption model work — updated_since, an RFC 3339 timestamp for incremental sync.

# first page of current servers
curl "https://registry.modelcontextprotocol.io/v0.1/servers?limit=100&version=latest"

# everything that changed since a timestamp — the aggregator loop
curl "https://registry.modelcontextprotocol.io/v0.1/servers?updated_since=2026-07-28T00:00:00Z"

Each returned document carries registry-generated metadata under _meta["io.modelcontextprotocol.registry/official"]: publishedAt, updatedAt, isLatest, and a status that is active, deprecated, or deleted. Server metadata is otherwise treated as immutable — status is the one field expected to change, and the docs recommend consumers keep it fresh. The OpenAPI document is itself date-versioned, 2025-12-01, mirroring how the MCP spec versions itself.

Nobody consumes it directly — by design

Here is the unusual part. The official docs state plainly that host applications should not consume the official registry. It offers no uptime or data durability guarantees. Instead, it expects downstream aggregators to scrape it on a regular but infrequent basis — the docs suggest once per hour — persist the data in their own stores, and serve end users themselves. The registry is a root, not a resolver. The analogy to DNS is hard to miss: a small neutral root zone, and all the opinionated serving pushed to the edges.

Aggregators that also implement the registry's OpenAPI spec become subregistries: drop-in compatible sources that any MCP host can consume through the same interface. The spec explicitly blesses injecting custom metadata — the docs' example shows a subregistry adding user_rating, download_count, and security_scan results under its own _meta key. Curation, ratings, scanning, enterprise policy: all downstream, all namespaced, none of it polluting the root.

This is already a real ecosystem, not a diagram. The community projects list includes enterprise-grade subregistry servers like Stacklok's ToolHive (Kubernetes-native, with access control and audit logging), hosted registry extensions like ToolSDK, browsing frontends, client SDKs in Go, TypeScript, and Java, and a GitHub Action for publishing from CI. Enterprise vendors are positioning registries as governance control planes. The neutral root created a market for opinions on top of it.

Measuring the registry, live

Documentation describes intent; the API describes reality. So we measured it. On July 29, 2026, we paginated GET /v0.1/servers?version=latest from the first cursor to the last: 191 pages of 100, for a total of 19,016 servers at their latest version — 18,814 with status active and 202 deprecated. Deleted entries do not appear unless you pass include_deleted=true, so the visible catalog is effectively the post-moderation one. The names sweep alphabetically from ai.* vanity domains through corporate com.* namespaces to the long tail of io.github.* — with aggregate publishers in the mix, like the 213 entries under Smithery's ai.smithery/ namespace.

One operational note from the exercise: a full crawl at limit=100 took the better part of an hour against a public endpoint with no SLA. That is not a bug — it is the design telling you how to behave. Full scans are for bootstrapping; after that, you are meant to hold your own copy and poll updated_since hourly. Any serious consumer of this registry is, structurally, forced to become an aggregator.

The lesson from the ERC-8004 audit applies here too: registration counts are not adoption. Registration is cheap, and a preview registry with permissive moderation will accumulate noise. The structural difference is that every MCP Registry entry is at least anchored to an owned artifact or namespace — the floor is higher than an unverified on-chain pointer. What the registry still lacks, deliberately, is any signal of quality or liveness: no probes, no ratings, no usage data. That is the subregistries' job.

Three discovery layers, one stack

Put the three layers side by side and the division of labor is clean. The MCP Registry solves naming and packaging: canonical identifiers, verified namespaces, machine-readable install and connect metadata. x402 Bazaar solves paid discovery: it indexes endpoints at settlement time and ranks them by real payment activity — a reputation signal that costs money to fake. ERC-8004 aims at portable on-chain identity, and so far delivers the weakest guarantees of the three. None of them replaces the others. An agent economy needs all three answers: what is this called, does it actually work, and who is accountable for it.

The registry's bet is that staying unopinionated at the root is what lets it win the naming layer. It refuses to rank, refuses to scan, refuses to host, and freezes a tiny API. Everything contested — trust, quality, price — is pushed to layers where competition can happen. It is the most infrastructure-shaped piece of the MCP ecosystem, in the sense that nobody will ever get excited about it, and everything will quietly depend on it.

What it means for LLM4Agents

LLM4Agents ships a hosted MCP server — the 67-tool surface agents use for inference, wallets, workspace, and memory. Today, an agent finds it because its operator read our docs. A registry entry changes the funnel: a DNS-verified com.llm4agents namespace with a remotes entry of type streamable-http makes the gateway discoverable by any MCP client that consumes any subregistry, with configuration metadata rich enough to connect without reading anything. Combined with x402 walk-up — pay per call, no account — discovery-to-first-settlement becomes a fully autonomous path: an agent can find the gateway in a registry, connect over Streamable HTTP, hit a 402, pay in USDC, and get work done, with no human in the loop at any step.

The consumer side matters just as much. A gateway that fronts hundreds of models is, functionally, a curator — and the subregistry model is the standard-shaped way to expose curation. Syncing hourly from the official root with updated_since, filtering to live remote servers, and serving the result through the same OpenAPI interface would give agents on our platform a discovery surface that is standards-compatible and opinionated where it counts: liveness, payment support, observed reliability. The threat is symmetric: discovery is the top of the funnel, and whoever curates trust for agents owns it. The enterprise subregistry vendors have understood this; so should every gateway.

Staying on the frontier

Concrete steps, in order. First, publish: verify the com.llm4agents namespace with a DNS TXT record and ship a server.json with a streamable-http remote pointing at the MCP endpoint — and because the registry is preview and data resets are possible, make publishing a CI step with mcp-publisher and GitHub OIDC rather than a one-off. Second, build the subregistry: an hourly updated_since sync into our own store, exposed through the registry's OpenAPI spec, filtered to servers that pass live health probes — the check the root deliberately does not do. Third, attach payment metadata: a namespaced _meta key declaring x402 support, schemes, and pricing for each indexed server, and a proposal upstream to standardize that convention so payment-aware discovery stops being bespoke. Fourth, rank by settlements: fold the gateway's own settlement history into the subregistry's ordering, importing the one idea from Bazaar that actually resists Sybil attacks. Fifth, track the road to GA: the v1 API will be the compatibility break that matters, and daily monitoring of status transitions keeps deprecated and deleted servers out of agent contexts.