Skip to main content

What Is the MCP Registry and How to Search It

Short answer

The MCP Registry at registry.modelcontextprotocol.io is the official public catalog of MCP server metadata. Each entry is a server.json file that gives the server's name, description and version, plus where to get it: an npm, PyPI or Docker package, or a remote URL. Anyone can search it through a REST API without signing in. Publishing is different, because you have to prove you control the namespace in the server's name.

Tested withMCP Registry API v0.1 (registry service 1.8.1)server.json schema 2025-12-11Checked 20 Oct 2026

By Tony LewisHow we test these guides

What the registry holds​

The registry stores metadata, not code. It doesn't host server packages. A server.json entry points at a package on npm or PyPI, a Docker image, or a URL where a remote server runs, and the client downloads or connects from there. The registry's quickstart says it plainly: "The MCP Registry only hosts metadata, not artifacts."

The registry is in preview, and the project says breaking changes or data resets can happen before general availability. The official docs say it's meant to be read mainly by aggregators: marketplaces that add ratings, security checks or curation on top. Host apps are supposed to read those marketplaces, not the registry itself.

Some clients already read a registry directly. VS Code's MCP gallery calls a URL set by chat.mcp.gallery.serviceUrl and sends search, version=latest and cursor parameters, the same ones described below. Organizations can point it at their own registry. The VS Code docs describe the gallery, and the VS Code enterprise settings describe the McpGalleryServiceUrl policy.

The server.json entry​

Every server in the registry has a server.json. The publisher writes it, and the registry checks it when you publish. These are the fields you'll see most:

FieldRules
nameRequired. Reverse-DNS form, namespace/server-name, with exactly one /. 3 to 200 characters, using letters, digits, ., - and _.
descriptionRequired. 1 to 100 characters. Describe what the server does, not how it's built.
versionRequired. A specific version such as 1.0.2. Version ranges are rejected. Up to 255 characters.
titleOptional. A display name of up to 100 characters.
repositoryOptional, but recommended. Has url and source, such as github.
websiteUrlOptional. Homepage or documentation link.
packagesOptional. Describes a server a client runs locally, with registryType, identifier, version and transport.
remotesOptional. Describes a server a client connects to over a URL, such as streamable-http.
_metaOptional. On publish, only the io.modelcontextprotocol.registry/publisher-provided key is kept, up to 4KB.

Here's a complete remote server entry. The name and domains are fictional:

server.json
{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
  "name": "io.github.acme/weather-server",
  "title": "Weather",
  "description": "Current conditions and forecasts for any city.",
  "repository": {
    "url": "https://github.com/acme/weather-server",
    "source": "github"
  },
  "version": "1.0.0",
  "remotes": [
    {
      "type": "streamable-http",
      "url": "https://mcp.example.com/weather"
    }
  ]
}

The registry's validator checks a file without publishing it. The official API docs list POST /v0.1/validate for this, and mcp-publisher validate uses it. Sending the sample above returns valid: true:

{"valid":true,"issues":[]}

If you change version to ^1.0.0, the validator reports:

{"valid":false,"issues":[{"type":"semantic","path":"version","message":"version must be a specific version, not a range: \"^1.0.0\"","severity":"error","reference":"version-looks-like-range"}]}

The published JSON schema for server.json describes the shape of the file but doesn't reject ranges in version, so run the validator when you need that check.

Namespaces: who can publish a name​

The part of the name before the slash is a namespace, and it has to belong to you. The sign-in method you use decides which namespace you can publish under:

Sign-in methodName must start withExample
GitHubio.github.<username>/ or io.github.<orgname>/io.github.alice/weather-server
Domain, by DNS or HTTP proofthe reverse of your domain, such as com.example/com.example/weather

This is why the registry can say a name is verified. The check is on the account or domain, not on the server's code. The registry also doesn't accept private servers. Servers on a private network or private package feed are out of scope, and the docs suggest running your own private registry for those. The publish guide covers the sign-in and the commands.

Packages in a server.json must come from public registries: npm (registryType npm), PyPI (pypi), NuGet (nuget), crates.io (cargo), Docker or OCI images (oci), and MCPB files on GitHub or GitLab releases (mcpb). Each type has its own ownership check, which the package types page lists.

Search the registry​

The REST API is public and read-only. Reading it doesn't need a sign-in. These are the endpoints:

RequestReturns
GET /v0.1/serversOne page of servers.
GET /v0.1/servers/{serverName}/versionsEvery version of one server.
GET /v0.1/servers/{serverName}/versions/{version}One version. Use latest for the newest.

Server names contain a slash, so URL-encode it as %2F. The query parameters on the list endpoint are:

ParameterWhat it does
searchCase-insensitive substring match on the server name.
versionlatest returns one entry per server, the newest version.
limitPage size.
cursorThe nextCursor value from the previous page. Treat it as opaque.
updated_sinceServers updated after an RFC 3339 timestamp, for syncing.
include_deletedIncludes servers with status deleted, which are hidden by default.

Search for soil, one result per server:

curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=soil&version=latest&limit=1"

The response, trimmed:

{
    "servers": [
        {
            "server": {
                "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
                "name": "dev.nativesoil/soil",
                "description": "Save an AI chat's working state, load it in any other model or provider. Verified, secret-safe.",
                "title": "Native Soil",
                "version": "1.0.0",
                "websiteUrl": "https://nativesoil.dev",
                ...
                "remotes": [
                    {
                        "type": "streamable-http",
                        "url": "https://mcp.nativesoil.dev/mcp/soil"
                    }
                ]
            },
            "_meta": {
                "io.modelcontextprotocol.registry/official": {
                    "status": "active",
                    "statusChangedAt": "2026-06-23T20:53:05.746852Z",
                    "publishedAt": "2026-06-23T20:53:05.746852Z",
                    "updatedAt": "2026-06-23T20:53:05.746852Z",
                    "isLatest": true
                }
            }
        }
    ],
    "metadata": {
        "nextCursor": "dev.nativesoil/soil:1.0.0",
        "count": 1
    }
}

A few things to know from that call and from testing the API:

  • Leave out version=latest and you get every version. In our test, limit=2 with no filter returned ac.inference.sh/mcp twice, once per version.
  • Search only looks at names. search=soil matched four servers whose names contain "soil", and none of the servers that only mention soil in their description.
  • Pagination uses nextCursor. Pass the value back as cursor= to get the next page. When nextCursor is missing or empty, you've reached the end.
  • Some searches are slow. In our tests, a few took more than 30 seconds, so give your client a generous timeout.

To read one server, request its latest version:

curl "https://registry.modelcontextprotocol.io/v0.1/servers/ai.precip%2Fweather/versions/latest"

Each response carries registry-managed fields under _meta in io.modelcontextprotocol.registry/official. Their status is active, deprecated or deleted. A deprecated server still appears with a message. A deleted one is hidden from default results, and the registry says deletion usually means the server broke its moderation policy.

Common misconceptions​

"The registry runs or hosts the servers." It doesn't. It stores metadata and points at packages or remote URLs. Your client still installs the package or connects to the remote URL.

"Listed means reviewed or safe." The registry checks namespace ownership and package ownership, and it can remove spam or malicious entries. It doesn't scan the code. The docs leave security scanning to the package registries and to marketplaces built on top.

"Publishing here makes my server show up in Claude or ChatGPT." Host apps don't read the registry directly. Marketplaces and directories read it, and some apps read their own gallery sources. Getting listed in those is a separate step covered in list in MCP directories.

"The list shows each server once." Only with version=latest. Without it, every version appears.

Common problems​

version must be a specific version, not a range The version field holds a range such as ^1.0.0 or 1.x. Replace it with an exact version such as 1.0.0. The validator output in the section above shows this error.

Registry validation failed for package The package doesn't contain the ownership marker the registry looks for, such as mcpName in an npm package.json. The publish guide walks through each package type.

You do not have permission to publish this server The name's namespace doesn't match the account you signed in with. A GitHub sign-in must publish under io.github.<your-username>/. See the namespaces table above.

FAQ​

Is the MCP Registry the same as a marketplace?

Not quite. The MCP Registry is the metadata source. Marketplaces and directories read it and add their own features, such as ratings, reviews and curation. The official docs say host apps should read those marketplaces rather than the registry itself.

Do I need to sign in to search the MCP Registry?

No. The read API is unauthenticated, so you can search it and read any server entry from a terminal. Signing in is only required to publish a server.

Can I keep a private MCP server out of the registry?

Yes, by not publishing it. The official registry doesn't accept servers that only live on a private network or a private package feed. Teams that want an internal catalog can run their own registry that implements the same API.

Why does the same server appear several times in search results?

Each published version is a separate entry. Add version=latest to the request to get one entry per server.