What is an MCP Registry?

The proliferation of AI agents and tools has created a fragmented ecosystem, making the discovery, verification, and governance of these components a major challenge for developers and enterprises. As teams build increasingly complex AI applications, they face a critical question: How do our agents find the tools they need to operate, and how can we trust that those tools are legitimate? This lack of a central, standardized discovery mechanism introduces friction, security risks, and operational overhead.

The Model Context Protocol (MCP) is the emerging standard for agent-to-tool communication, and its MCP Registry is the official discovery layer that solves this problem. Backed by Anthropic, GitHub, PulseMCP, and Microsoft, it provides a centralized, searchable directory where applications can look up the “contact information” for any MCP server they need to interact with, from a weather server to a complex internal data-processing service. Think of it as the phonebook for AI agents.

The MCP Registry is currently in preview. Breaking changes or data resets may occur before general availability, so check the official docs when you build against it.

This article provides a comprehensive guide for developers, system architects, and technical leaders. We will deconstruct the MCP Registry from first principles and foundational architecture to practical API interactions and enterprise-grade security strategies. You will learn: 

• What an MCP registry is
• Its core architectural components
• How it differs from package managers and gateways
• How to publish and query servers using the real spec
• Why a private registry implementation is critical for enterprise governance

What is an MCP registry? The phonebook for AI agents

An MCP registry is a centralized, searchable discovery service that stores metadata about MCP servers, enabling AI applications, aggregators, and agents to find and understand the tools available to them. It acts as the authoritative source of truth for what tools exist, what they do, and how to connect to them within the AI ecosystem.

A clear definition: More than just a list

At its core, an MCP registry is a specialized metadata repository designed for service discovery. The phonebook analogy holds: The registry provides the “number” (the server’s address and installation metadata), but it doesn’t host the conversation itself. A consuming application uses the information from the registry to install or connect to the MCP server directly.

A critical distinction is what a registry stores. It holds metadata only, in a standardized file called server.json. It doesn’t store the actual server code, machine-learning models, or container images. Those continue to live on package registries like npm, PyPI, or Docker Hub. This lightweight, pointer-based approach makes the registry highly efficient and scalable; it is purely a discovery and verification layer, not a code repository.

The core capabilities of a registry

An effective MCP registry provides four essential capabilities:

• Publishing: Server developers publish metadata about their servers to the registry through a publisher CLI.
• Namespace management: Server names use reverse-DNS form (e.g. io.github.username/server or com.example/server). Publishers must prove ownership of their namespace before they can publish under it. This is done via GitHub OAuth, a DNS TXT record with a cryptographic public key, or a .well-known/mcp-registry-auth file.
• Discovery API: A REST API lets MCP clients and aggregators query for servers by name or other metadata.
• Standardized installation and configuration metadata: Every server publishes installation instructions (npm package, Docker image, remote URL, etc.), required environment variables, and transport details in a single, well-defined shape.

The key participants in the registry ecosystem

The MCP Registry ecosystem has a deliberately layered consumption model:

• Server developers: Build MCP servers and publish their server.json metadata to the registry so others can discover them.
• The official MCP Registry: Hosts unopinionated metadata. It is not intended to be queried directly by AI applications.
• Downstream aggregators (marketplaces) also called subregistries when they implement the official OpenAPI spec: Pull metadata from the official registry on a regular cadence (typically hourly), then re-expose it through their own APIs with curation, ratings, and additional metadata.
• Private MCP registries: Run inside an enterprise perimeter, often implementing the official OpenAPI spec so that any aggregator-aware host application can also consume them.
• MCP host applications: Claude, ChatGPT, VS Code, Cursor, and other AI applications. The official guidance is that host applications consume aggregators (or private registries that implement the OpenAPI spec), not the official registry directly.

This separation of concerns is what lets the public registry stay lean and unopinionated while letting marketplaces and enterprises layer curation, scoring, and policy on top.

The core architecture: How an MCP registry works

An MCP registry functions as a straightforward yet powerful system, centered around a standardized metadata file and a well-defined REST API for publishing and querying. Its architecture is designed for simplicity and efficiency, focusing exclusively on the discovery and verification of MCP servers.

The server.json metadata file explained

The server.json file is the manifest or “business card” for an MCP server. It’s a JSON file that contains all the essential metadata an application needs to understand and install the server. Server authors create this file and publish it to the registry.

Here is a valid server.json matching the current schema (2025-12-11), for a hypothetical GitHub repo-stats MCP server published by Tyk:

{

  “$schema”: “https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json”,

  “name”: “io.github.tyk/repo-stats”,

  “description”: “A tool to fetch statistics for a GitHub repository.”,

  “version”: “1.0.1”,

  “repository”: {

    “url”: “https://github.com/tyk/repo-stats”,

    “source”: “github”

  },

  “packages”: [

    {

      “registryType”: “npm”,

      “identifier”: “@tyk/repo-stats”,

      “version”: “1.0.1”,

      “transport”: { “type”: “stdio” },

      “environmentVariables”: [

        {

          “name”: “GITHUB_TOKEN”,

          “description”: “GitHub personal access token”,

          “isRequired”: true,

          “isSecret”: true        }

      ]

    }

  ]

}

Key fields:

• $schema: The schema URL (versioned by date). Including it enables IDE schema validation and signals which schema version the file conforms to.
• name: The unique reverse-DNS server name. For GitHub auth, must be io.github.username/* or io.github.orgname/*. For domain auth, must be a reverse-DNS form of your domain (e.g. com.example.*/*).
• version: Your server’s version (semver is encouraged; see the official MCP versioning guide).
• repository: { url, source } for the source code repository.
• packages: Array of installable packages. Each entry has registryType (e.g. npm, pypi, oci), identifier (the package name on that registry), version, transport (with type: “stdio” or “streamable-http”), and optional environmentVariables.
• remotes (alternative to packages): Array of hosted remote MCP servers, used when the MCP server runs as a hosted service rather than as an installable package.

A server.json typically declares either packages[] (installable packages) or remotes[] (hosted remote servers), not both (though both can be present if you offer both deployment options). See the official package types and remote servers guides for the supported package registries and remote-server patterns.

Visualizing the registry workflow

The interaction between participants follows a clear flow:

1. Publish: A server author runs mcp-publisher init to generate a server.json template, authenticates with mcp-publisher login, and publishes with mcp-publisher publish. The official registry validates that the underlying package metadata matches (for npm, by checking the mcpName field in package.json).
2. Aggregate: Downstream aggregators/marketplaces poll the official registry’s API on a cadence (e.g. hourly), pulling new and updated server metadata.
3. Query. An MCP host application (or an aggregator’s own client) queries an aggregator or private registry to find a server by name, function, or other metadata.
4. Install/connect: The host application parses the returned server.json to find the package identifier or remote URL, then installs the package (e.g. npx, Docker pull) or opens a Streamable HTTP connection, completely bypassing the registry for runtime communication.

This decouples discovery from execution. The registry is involved only at install/startup time, making it a non-critical-path component for runtime operations.

Federation: The official MCP Registry, aggregators, and private registries

The MCP ecosystem is designed to be federated:

• The official MCP Registry (registry.modelcontextprotocol.io) is the canonical metadata source for publicly accessible MCP servers. It deliberately holds unopinionated metadata.
• Downstream aggregators (MCP marketplaces) pull from the official registry and re-expose it with curation, ratings, install statistics, and search UX. These are the layers host applications typically consume.
• Private MCP registries sit inside an enterprise perimeter and host metadata for internal-only servers, vetted third-party servers, and approved versions. Private registries typically implement the official MCP Registry OpenAPI spec so that any aggregator-aware host application can consume them.

Note that the official MCP Registry codebase is not designed for self-hosting. If you want a private registry, the recommended path is to adopt or build an implementation that conforms to the registry’s OpenAPI spec, not to fork the reference repo.

For a hybrid setup, configure your host application’s aggregator client to consult your private registry first and fall back to an aggregator that serves the public MCP Registry. That gives you the security and governance of a private allowlist while retaining access to the broader ecosystem.

MCP registry vs package manager vs MCP gateway

An MCP Registry is a new piece of infrastructure in the developer toolkit, and it’s easy to confuse with familiar concepts like package managers or API gateways. Understanding the distinct role of each is critical for designing a clean and effective AI architecture.

Registry vs package manager (npm, Docker Hub)

The core difference between an MCP registry and a package manager is what they store: A registry stores metadata pointers, while a package manager stores the actual code artifacts.

An MCP registry tells an application where to install a server from and what it does. A package manager like npm, PyPI, or Docker Hub gives you the artifact itself (the JavaScript package, Python wheel, or container image needed to run the server). The registry is the library catalog card that tells you which shelf the book is on; the package manager is the warehouse that stores the actual book. An MCP registry’s server.json points to an artifact on npm/PyPI/Docker Hub via packages[].identifier, but it doesn’t host that artifact.

Registry vs MCP gateway/API gateway

The difference between a registry and a gateway is one of timing and function. A registry is for discovery, while a gateway is for execution and governance.

You interact with a registry at build-time or application startup to find the metadata for a server. Once you have that, the registry’s job is done. An API or MCP gateway, on the other hand, sits in the request path at runtime. It intercepts the actual MCP traffic between client and server, enforces security and rate-limiting policies, handles authentication, collects telemetry, and manages flow.

This is where a gateway such as the Tyk Gateway becomes the essential counterpart to an MCP Registry. The registry helps you discover the right tool; the gateway helps you securely manage, control, and observe all the traffic flowing to and from that tool once it’s in use.

A comparative analysis

Understanding these distinctions lets architects place each component correctly, using the registry for discovery, the package manager for artifact storage, and a gateway for runtime governance and security.

How to interact with an MCP registry: A practical guide

Developers interact with the official MCP Registry through a REST API for querying and the mcp-publisher CLI for publishing. The process is designed to be straightforward and easily integrated into automated workflows.

Step 1: Querying the registry to find servers

The primary way to find servers is by making a GET request to the registry’s /v0.1/servers endpoint, filtered with a search query parameter. For example, to find the io.github.tyk/repo-stats server published in our earlier example:

curl “https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.tyk/repo-stats”

The registry responds with a JSON object containing a servers array, where each entry’s server object conforms to server.schema.json, accompanied by registry-managed _meta. A client application would parse this response, identify the desired server, and either install the package (servers[].server.packages) or connect to the remote URL (servers[].server.remotes):

{

  “servers”: [

    {

      “server”: {

        “$schema”: “https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json”,

        “name”: “io.github.tyk/repo-stats”,

        “description”: “A tool to fetch statistics for a GitHub repository.”,

        “version”: “1.0.1”,

        “repository”: { “url”: “https://github.com/tyk/repo-stats”, “source”: “github” },

        “packages”: [

          {

            “registryType”: “npm”,

            “identifier”: “@tyk/repo-stats”,

            “version”: “1.0.1”,

            “transport”: { “type”: “stdio” }

          }

        ]

      },

      “_meta”: {

        “io.modelcontextprotocol.registry/official”: {

          “status”: “active”,

          “publishedAt”: “2025-09-16T16:43:44Z”,

          “updatedAt”: “2025-09-16T16:43:44Z”,

          “isLatest”: true

        }

      }

    }

  ],

  “metadata”: {

    “count”: 1,

    “nextCursor”: “io.github.tyk/repo-stats:1.0.1”

  }

}

In practice, host applications usually go through an aggregator that implements the same OpenAPI shape, rather than calling the official registry directly.

Step 2: Publishing your MCP server metadata

To make your server discoverable, publish its server.json file using the official mcp-publisher CLI. Install it from the latest GitHub release of the modelcontextprotocol/registry repo, or via Homebrew, then verify with mcp-publisher –help.

The full publishing flow looks like:

# 1. From your server project directory, generate a server.json template

mcp-publisher init

# 2. (npm only) Add an mcpName property to package.json so the registry can

#    validate the package matches your metadata, e.g.:

#    “mcpName”: “io.github.tyk/repo-stats”

# 3. Publish your underlying package to npm / PyPI / Docker Hub / etc.

npm publish –access public

# 4. Authenticate with the MCP Registry (see Step 3 below)

mcp-publisher login github

# 5. Publish your server.json to the registry

mcp-publisher publish

The publish step validates the server.json format, checks that the underlying package’s metadata matches (e.g. the npm package’s mcpName matches server.json‘s name), and that the authenticated identity owns the requested namespace.

Step 3: Verifying namespace ownership

Before your server is listed, the registry verifies that you own the namespace you’re publishing under. The MCP Registry supports three authentication methods, and the method you use determines which namespace prefix you can claim:

DNS and HTTP authentication are cryptographic; you generate an Ed25519 or ECDSA P-384 key pair (optionally backed by Google KMS or Azure Key Vault), publish the public key in a TXT record (v=MCPv1; k=ed25519; p={PUBLIC_KEY}) or .well-known file, and prove possession of the private key through mcp-publisher login dns|http. This gives the registry strong cryptographic evidence of namespace ownership.

Why enterprises need a private MCP registry for governance

While the official MCP Registry is excellent for the public ecosystem, relying on it exclusively presents significant security, compliance, and operational risks for enterprises. A private MCP registry, implemented against the official OpenAPI spec, is not a luxury but a practical necessity for any organization that’s serious about AI governance.

Mitigating risk: The dangers of public-only registries

Using only public sources opens the door to several critical threats:

• Supply-chain attacks: An AI application could install or connect to a malicious MCP server disguised as a legitimate tool, providing a vector for malware, harmful actions, or credential theft.
• Data exfiltration: An unvetted public server, even if not overtly malicious, could send sensitive internal data to an external endpoint. Without a curation process, there’s no way to prevent this leakage.
• Lack of control: You can’t enforce which versions of a tool are used, apply specific security standards, or manage the lifecycle of third-party tools that your applications depend on.

The benefits of a private, curated registry

Standing up a private MCP registry, typically a commercial or OSS implementation of the registry’s OpenAPI spec, creates a “walled garden” that directly addresses these risks.

• Curated allowlist: Only MCP servers that have been reviewed, scanned for vulnerabilities, and approved by the security team are published.
• Granular access control: Integrate with internal identity systems to enforce who can publish or discover certain tools. For example, restrict sensitive financial tools to finance-department applications.
• Lifecycle management: Stage new server versions, test them, formally deprecate, and remove old or insecure versions from discovery.
• Audit and compliance: Maintain a complete record of which applications discovered which tools and when. This is essential for compliance reporting and incident investigation.

These governance capabilities are enforced at runtime by an API management platform. By using a private registry for discovery and a platform such as Tyk for execution, you create a comprehensive control plane for your AI stack. Tyk’s security policies and API lifecycle management features are the natural enforcement point for the rules you define in your private registry.

Note that the official MCP Registry’s reference implementation is published on GitHub but isn’t designed for self-hosting, and the maintainers do not support that use case. Enterprises that want a private MCP registry should adopt a commercial or OSS implementation of the registry’s OpenAPI spec, or build one internally.

Common pitfalls and future directions

As with any emerging technology, several common misunderstandings exist about MCP registries. Clarifying these points is key to successful implementation.

Misconception: The registry guarantees server security

An MCP Registry’s primary security function is namespace authentication, not comprehensive security scanning of the underlying server code. It confirms that the entity publishing the server is who they say they are. It doesn’t scan the package’s container image for vulnerabilities or analyze its source code for flaws.

The MCP Registry deliberately delegates security scanning to:

• Underlying package registries: npm, PyPI, Docker Hub, and other package registries run their own vulnerability scanning.
• Downstream aggregators: Marketplaces and curation layers can add their own ratings, security checks, and policy filters.
• Your DevSecOps pipeline: The internal curation process before a server is admitted into your private MCP registry is where you should run additional scanning, dependency analysis, and policy checks.

Misconception: The registry is a single point of failure

The registry is not a single point of failure for runtime traffic because it isn’t in the request path. It’s used for discovery, which typically happens once at install/application startup or periodically.

Resilience is further enhanced by two mechanisms:

1. Aggregator caching: Aggregators pull from the official registry on a cadence (e.g. hourly) and cache results. Host applications consume aggregators rather than the official registry, so a short outage at the official registry is invisible to most users.
2. Federation: A well-architected enterprise system can fall back from its private registry to an aggregator that serves the public registry, or operate from cached metadata.

What’s next? Package attestations and richer metadata

The MCP Registry specification is still evolving; the registry itself is in preview as of early 2026. There are several spec areas to watch:

• Package attestations: The metadata layer already supports cryptographic signing via DNS and HTTP authentication today (Ed25519 / ECDSA P-384 key pairs). The likely next step is package-content attestations, involving signing the underlying npm/PyPI/OCI artifact (e.g. via sigstore-style signatures) so consumers can verify that the artifact installed at runtime matches what the publisher intended.
• More identity providers: OIDC-based auth for non-GitHub identity providers, allowing more flexible namespace structures.
• Richer machine-readable capability metadata: Beyond install instructions, server-side declarations of capabilities, scopes, and policy requirements that host applications and aggregators can use for finer-grained filtering.

Frequently asked questions about MCP registries

What is the difference between the MCP Registry spec and the official registry?

The MCP Registry specification (including the server.schema.json and the OpenAPI spec) is the open standard that defines the metadata format, API, and behavior any registry must follow. The official MCP Registry is the specific public instance at registry.modelcontextprotocol.io, backed by Anthropic, GitHub, PulseMCP, and Microsoft. Private registries and downstream aggregators implement the same spec to remain interoperable with host applications.

How does an MCP registry handle versioning?

A server.json includes a version field for the server itself, plus a per-package version inside each entry of packages[]. Semantic versioning is encouraged. The registry has a dedicated versioning guide that covers how versions are listed, deprecated, and resolved by clients.

Can I run an MCP registry on-premises?

You can run a private MCP registry on-premises. That’s the recommended approach for enterprises that need to publish private servers or maintain an internal allowlist. However, the official MCP Registry codebase at github.com/modelcontextprotocol/registry is explicitly not designed for self-hosting. The right path for a private registry is to adopt a commercial or OSS product that implements the OpenAPI spec, or to build one internally that conforms to it.

Does the MCP registry cost anything to use?

The official public MCP Registry is a free service. Costs are incurred only if you self-host a private registry (infrastructure plus maintenance) or adopt a commercially supported managed registry product.

What is a namespace in an MCP registry?

A namespace is a unique reverse-DNS prefix tied to either a verified GitHub user/org (io.github.username/io.github.orgname) or a DNS-verified domain (com.example, reverse-DNS of your domain). Ownership must be proven to the registry before you can publish servers under it, by GitHub OAuth, a DNS TXT record carrying your public key, or a .well-known/mcp-registry-auth file on your domain.

Conclusion

The MCP Registry is the essential “phonebook” for the emerging AI agent ecosystem. It provides a standardized, secure, and efficient layer for tool discovery by storing verifiable metadata, not bulky code artifacts. It fills a critical gap in the AI stack, enabling interoperability and trust between MCP servers, aggregators, and host applications.

Understanding its architecture reveals that a registry differs fundamentally from a package manager (which handles storage) and from an MCP/API gateway (which manages runtime execution). While the public registry is a vital resource for the open-source community, enterprises require private registries (implementations of the official OpenAPI spec) to enforce security, governance, and compliance for their AI applications.

As the MCP Registry matures past its current preview status, standardized and secure discovery will become non-negotiable for any team building robust, scalable, enterprise-ready AI applications. Mastering the role and implementation of the MCP Registry is a foundational step.

To secure and manage the traffic to the MCP servers you discover, you need a powerful API gateway. Explore how Tyk can help you govern your entire AI and microservices architecture today.