What Is an MCP Registry? Tool Discovery for AI Agents

An MCP registry is a searchable index of Model Context Protocol servers — a package-manager-style directory where AI clients and their users discover, evaluate, and install tools. Instead of hunting through GitHub READMEs and hand-copying JSON config blocks, a registry gives both humans and machines a structured answer to two questions: what MCP servers exist, and how do I run them?

The ecosystem now has an official MCP registry maintained by the Model Context Protocol project, plus a layer of sub-registries — client marketplaces, curated directories, and private company registries — that build on top of it. This guide covers how the pieces fit together, how clients use registries for discovery, how to publish your own server, and where skill registries fit alongside server registries.

What is an MCP registry and what problem does it solve?

Before registries existed, MCP server discovery was a mess of GitHub searches and awesome-mcp-servers lists. The closest thing to an MCP server directory was a hand-maintained markdown file. Installation meant reading a README, copying a JSON snippet into your client config, guessing at environment variables, and hoping the package name in the docs matched the one on npm.

That workflow breaks down fast:

• No canonical names. Three servers called "github" with no way to tell which is the real one.
• No machine-readable metadata. A README tells a human how to install a server; it tells a client nothing.
• No versioning story. The README documents the latest version, but you may be running last month's.
• No trust signal. Anyone can publish an npm package named after a popular service — see our guide to MCP security best practices for why that matters.

An MCP registry addresses all four. Each entry has a namespaced, verified name, a structured description of its packages and transports, explicit versions, and enough metadata that a client can render an install flow — or an agent can install the server itself — without a human parsing prose.

Think of it as the npm registry moment for MCP: the protocol standardized how tools talk to models, and registries standardize how those tools get found and installed.

The official MCP registry: status, API, and caveats

The official MCP registry lives at registry.modelcontextprotocol.io. It's an open-source project under the Model Context Protocol GitHub organization, launched in preview in September 2025 and iterating since. A few design decisions are worth understanding before you rely on it.

It's a metadata index, not a package host. The registry does not store server code. Each entry points at artifacts hosted elsewhere — npm, PyPI, Docker/OCI registries, NuGet — or at a remote URL for hosted servers. Compromising the registry entry doesn't replace the code; the upstream package registry remains the distribution channel.

It's designed as a registry of registries. The official registry is intended to be the shared source of truth that downstream sub-registries replicate from, filter, and enrich. Client vendors and marketplaces are expected to pull its data on a schedule rather than proxy every end-user request to it live.

Namespaces are verified. Server names use reverse-DNS format, like io.github.yourname/weather. Publishing under io.github.* requires authenticating with the matching GitHub account; publishing under a custom domain namespace like com.yourcompany/* requires DNS or HTTP-based domain verification. That kills the "which github server is real?" problem at the naming layer.

The MCP registry API

The MCP registry API is a plain REST interface. Listing and searching servers requires no authentication:

# Search for servers
curl "https://registry.modelcontextprotocol.io/v0/servers?search=github"

# Fetch a specific server's metadata
curl "https://registry.modelcontextprotocol.io/v0/servers?search=io.github.yourname/weather"

Responses return server.json documents: the server's name, description, version, its package coordinates per ecosystem, transport details (stdio, streamable HTTP), and any remote endpoints. That's everything a client needs to construct a runnable config entry programmatically.

Caveats to know

• The API is versioned v0 for a reason. The registry launched as a preview, and the shape of endpoints and schemas has evolved. Sub-registries that snapshot data insulate users from breaking changes; direct consumers should pin to schema versions.
• Listing is not endorsement. Moderation is closer to a blocklist than a review process. Nobody audits a server's code before it appears in the registry, so treat every entry as untrusted input until you've vetted it.
• Namespace verification proves ownership, not safety. io.github.someuser/postgres proves that GitHub user published it — not that it's the Postgres server you want, and not that it's well-behaved.

Sub-registries and private registries explained

The official registry deliberately does less so that sub-registries can do more. A sub-registry consumes the official registry's data and layers on its own value: curation, security scanning, compatibility testing, ratings, or enterprise policy. Client marketplaces — the built-in browse-and-install screens in MCP clients — are effectively sub-registries with a UI. Each one is a curated MCP server directory tuned to its client's capabilities.

A private registry flips the model: instead of filtering the public index, it serves servers that were never public in the first place. Companies run private registries for internal MCP servers that wrap proprietary APIs, internal databases, or deploy tooling. The pattern mirrors private npm registries or internal Docker registries, and the requirements are the same ones covered in our guide to running a private skill registry: authentication, access control, versioning, and an audit trail.

Because the official server.json schema is open, a private registry can speak the same format — which means internal tooling and future client integrations can treat public and private sources uniformly.

How MCP server discovery works in clients

MCP server discovery is the client-side half of the registry story. Today it works at three levels of automation:

1. Manual config. You find a server (registry, directory, or README), then add it to your client's config file — .mcp.json for Claude Code, mcp.json in Cursor, and so on. The registry helps here even without integration, because the metadata tells you the exact package name, transport, and required environment variables.
2. Marketplace install. Clients with built-in marketplaces render registry data as a browsable list with an install button. The client translates the server.json entry into its own config format, prompts for secrets, and wires up the transport.
3. Agent-driven discovery. The registry API is unauthenticated JSON, which means an agent can query it mid-task: "I need a tool for X, search the registry, propose an install." This is the most interesting frontier — and the most dangerous one, since it means the model is choosing its own tools. Human-in-the-loop confirmation and allowlists matter here.

One caution as your installed list grows: every server you add contributes tool definitions to the model's context on every request. Discovery makes installing servers easy; it doesn't make them free. If your client is dragging, see too many MCP tools cause token bloat before you install a tenth server.

If you're new to what a server actually is under the hood — tools, resources, transports — start with what is an MCP server and come back.

Publishing your server to a registry

Publishing to the official registry is a three-step flow built around a server.json file and the mcp-publisher CLI.

1. Publish your package normally. Your server must already exist on a supported package registry (npm, PyPI, Docker Hub/OCI, NuGet). For npm, add an mcpName field to package.json so the registry can verify that the package and the registry entry claim each other:

{
  "name": "@yourname/weather-mcp",
  "version": "1.0.0",
  "mcpName": "io.github.yourname/weather"
}

2. Describe it in server.json. This is the registry's manifest — name, version, and how to run it:

{
  "name": "io.github.yourname/weather",
  "description": "MCP server exposing weather lookups as tools",
  "version": "1.0.0",
  "packages": [
    {
      "registryType": "npm",
      "identifier": "@yourname/weather-mcp",
      "version": "1.0.0",
      "transport": { "type": "stdio" }
    }
  ]
}

Hosted servers list a remotes array with a streamable HTTP URL instead of (or alongside) packages.

3. Authenticate and publish:

# Generate a starter server.json in your project
mcp-publisher init

# Prove you own the namespace (GitHub OAuth for io.github.*)
mcp-publisher login github

# Push the entry to the registry
mcp-publisher publish

Custom-domain namespaces (com.yourcompany/*) swap the GitHub login for DNS TXT or HTTP file verification. Once published, sub-registries pick up your entry on their next sync, and any client or agent hitting the registry API can find it.

Registries for skills vs registries for servers

MCP registries solve distribution for capabilities — servers that give an agent new tools to call. But there's a second thing teams need to distribute: knowledge. Conventions, workflows, coding standards, and domain context don't belong in an MCP server; they belong in skills and rules — markdown instructions the agent reads before it acts.

That's the layer localskills.sh is a registry for. Every skill is a package with a root SKILL.md — optionally a multi-file folder with docs, scripts, and templates — versioned with rollback, and published as public, private, or unlisted. One localskills install writes the tool-native format for each target: .claude/skills/ for Claude Code, .cursor/rules for Cursor, .windsurf/rules/ for Windsurf, and more.

The two registry types also converge: localskills exposes its own MCP server, so an agent can search and install skills over MCP itself — with OAuth and scoped access controlling what it can touch. Your agent discovers tools through an MCP registry and discovers your team's conventions through a skill registry, over the same protocol.

FAQ

Is there an official MCP registry?

Yes. The Model Context Protocol project maintains an open-source registry at registry.modelcontextprotocol.io, launched in preview in September 2025. It's the canonical index that client marketplaces and sub-registries build on. It stores metadata only — the actual server packages live on npm, PyPI, Docker/OCI registries, and similar.

What's the difference between the MCP registry and a marketplace?

The official registry is a raw, minimally moderated index with a public API. A marketplace is a sub-registry: it pulls from that index, then adds curation, security review, ratings, and one-click install inside a specific client. Most users interact with marketplaces; marketplaces interact with the registry.

Can I run a private MCP registry?

Yes. The server.json schema and registry code are open source, so companies can run an internal registry for proprietary servers — same pattern as a private npm registry. The requirements match any private artifact registry: authentication, access control, versioning, and audit logging.

Does being listed in the MCP registry mean a server is safe?

No. Namespace verification proves the publisher controls the matching GitHub account or domain — nothing more. No one audits server code before listing. Vet servers before installing them, prefer well-known publishers, and pin versions.

How do AI agents use the MCP registry?

The registry API is unauthenticated REST, so an agent can search it directly, read a server's server.json, and propose (or perform) an install mid-task. Pair that power with allowlists and human confirmation — an agent choosing its own tools is exactly the scenario where supply-chain hygiene matters most.

---

Servers give your agent tools; skills give it your team's judgment about how to use them. Sign up for localskills.sh to publish your skills and rules once and install them across Claude Code, Cursor, Windsurf, and more — over the CLI or MCP.

npm install -g @localskills/cli
localskills login
localskills install your-org/your-skill --target claude cursor windsurf