Publish an MCP Server to the Official Registry: Names, Ownership Proof and server.json

How big is the MCP Registry now?

We pulled every server from the public API on 31 October 2026, using the version=latest filter. The default listing leaves out entries marked deleted, so these counts do too.

Which namespace should you choose?

Your login method decides the first half of the name, and the authentication guide offers two families: GitHub-based and domain-based. Choose a domain name if the server is part of a product you own a domain for. Choose GitHub if it is a personal or open source project. That is our advice, not a registry rule.

Domain names are written backwards: example.com becomes com.example. The two domain methods use a key pair, so treat key.pem like a password and keep it out of your repository. Both refuse github.io domains, which go through GitHub login instead. The CLI reference lists no rename command, so choose a name you can keep.

What proof does each package type need?

The namespace login proves the name is yours. The package check proves the package agrees, so a stranger cannot point a listing at your code. The exception is MCPB, where the check is lighter. Each page below shows what the registry reads.

• npm

  An mcpName field in package.json, equal to the server name.

• PyPI

  mcp-name: your/name in the README. It may sit in an HTML comment.

• NuGet

  The same mcp-name: line in the README. A comment works here too.

• Cargo

  The mcp-name: line in visible README text. crates.io strips comments, so a hidden line fails.

• OCI image

  A label io.modelcontextprotocol.server.name, set in the Dockerfile with LABEL.

• MCPB file

  A GitHub or GitLab release URL containing "mcp", plus a fileSha256. Clients check that hash; the registry does not.

• Remote URL

  No marker. The validator wants HTTPS, not localhost, and the URL must be free: no other server may hold it.

Only public registries count: the requirements page names npmjs.org, pypi.org, nuget.org, crates.io and a short list of container hosts. A private server cannot be listed. The docs point those teams to a private registry of their own.

What goes in server.json?

This is a complete file for a package server. The schema requires only name, description and version, and the rest tells a client how to start your server.

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
  "name": "io.github.alice/weather",
  "title": "Weather",
  "description": "Forecasts and severe weather alerts for any US city.",
  "repository": {
    "url": "https://github.com/alice/mcp-weather",
    "source": "github"
  },
  "version": "1.0.1",
  "packages": [
    {
      "registryType": "npm",
      "identifier": "@alice/mcp-weather",
      "version": "1.0.1",
      "transport": { "type": "stdio" }
    }
  ]
}

name

3 to 200 characters, one slash. For npm it must equal mcpName.

description

100 characters at most. The median listing uses 90, and 31.2% use 95 or more, so write it to fit.

version

Unique for every publish. Align it with the package version. latest and ranges such as ^1.2.3 are refused.

repository

Optional, yet 66.9% of listings fill it in, and 62.0% add a websiteUrl.

What are the publish steps, in order?

The order matters because the registry reads the live package. The steps follow the official quickstart for an npm server, with the name proved through GitHub, plus validate from the CLI reference.

1. Add the marker. Put "mcpName": "io.github.alice/weather" in package.json.
2. Publish the package. Run npm publish --access public. The marker must be in the version you ship.
3. Install the CLI. Run brew install mcp-publisher, or use the prebuilt binary from the quickstart.
4. Create the file. Run mcp-publisher init, then replace every placeholder it leaves. The init source writes ones such as io.github.<your-username>/... in the name, [describe what your server does] and @your-org/your-package. Delete the sample YOUR_API_KEY variable if your server needs none.
5. Check it. Run mcp-publisher validate. It lists every schema and format problem at once and publishes nothing. It does not check the marker, your login or duplicates.
6. Log in. Run mcp-publisher login github and enter the code it prints.
7. Publish. Run mcp-publisher publish.
8. Confirm. Search the API for your name, as below.

curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.alice/weather"

How do you publish from CI?

The GitHub Actions guide recommends OIDC, so no registry token sits in your secrets. This is the same idea as npm trusted publishing. Keep the job's tag trigger and the npm publish step, then end with:

permissions:
  id-token: write   # required for OIDC
  contents: read

steps:
  # checkout, build, npm publish, install mcp-publisher
  - run: ./mcp-publisher login github-oidc
  - run: ./mcp-publisher publish

Why was my publish rejected?

The first three messages come from the quickstart troubleshooting table. The last three come from the source code: database, validator and service.

What does a listing not mean?

Will a registry listing bring you users?

Not by itself. The list is crowded, and ten namespaces hold 15.7% of all names. The API publishes no install or usage counts, so we cannot measure what a listing is worth.

203 servers mention "weather" only in their description, so a weather search misses them. Another 118 have it in the name.

That gap comes from one line in the API specification: search matches the server name as a substring and reads nothing else. Results come back sorted by name, not by quality. So put the word people search for in the name: /weather beats /wx-tool. It is the same logic as choosing a package name.

Real reach comes from what sits downstream. Aggregators copy the data on a regular but infrequent schedule, such as hourly, and add ratings or curation. GitHub said in 2025 that servers published to the open registry would appear in its own MCP registry, but we did not test that here. Treat the listing as the source record, then check the marketplaces your users open.

Questions about the MCP Registry