Back

How to Publish an MCP Server to the Official MCP Registry

A practical guide to publishing a remote MCP server to the official MCP Registry, covering server.json, namespaces, GitHub, DNS, and HTTP verification, versions, and common submission problems.

Kelis Shekhaliya

SaaS API connected to AI agents through an MCP server

TL;DR

To publish an MCP server to the official MCP Registry, describe it in a server.json file, prove you own the namespace in its name through GitHub, a DNS TXT record, or a file on your domain, and submit it with the mcp-publisher CLI. A remote server lists its public Streamable HTTP URL and any required headers, never secret values. Versions are immutable and listings cannot currently be unpublished, so treat the first submission as a public release.

To publish an MCP server to the official MCP Registry, you describe the server in a server.json file, prove you own the namespace in its name (through GitHub, a DNS TXT record, or a file hosted on your domain), and submit it with the mcp-publisher CLI. For a hosted remote server, the entry points to your public Streamable HTTP URL and lists any headers clients must send, such as an API key, without ever including the secret itself.

This guide is for SaaS founders, CTOs, and API teams who already run a remote MCP server, or are about to, and want it listed where MCP clients and developers look for servers. It covers what the Registry is, how naming and verification work, what a remote server.json looks like, how versions behave, and the mistakes that most often block a submission.


What the official MCP Registry is

The MCP Registry is a public catalog of MCP servers run by the Model Context Protocol project at registry.modelcontextprotocol.io. Each entry is metadata: a name, a description, a version, and either installable packages (npm, PyPI, Docker, and similar) or remote endpoints that clients connect to by URL.

The Registry does not host your server or your code. It stores a description of where the server lives and how to connect to it. Your server still has to run somewhere, stay reachable, and enforce its own authentication.

Two things are worth knowing before you start:

  • It is in preview. The project's documentation says breaking changes or data resets may occur before general availability, so check the current docs when you publish.

  • Listings are public and versions are immutable. Each publish creates a version that cannot be edited afterwards, and there is currently no way to unpublish a listing. Treat the first submission as a public release.


Why a SaaS team would list its MCP server

If your product already has an MCP server, a Registry listing gives it a canonical, verifiable record. The server name is tied to a namespace you have proven you control, which helps users tell your official server apart from unofficial wrappers of your API.

A listing also gives tools that read from the Registry a structured way to show your server, its endpoint, and the credentials it expects. Whether a particular client surfaces Registry entries is up to that client, so a listing complements your own setup documentation rather than replacing it.


Before you publish: a readiness checklist

1. The server is publicly reachable

The Registry's documentation states that a remote server must be publicly accessible at the URL you list. A server behind a VPN, on localhost, or on a private network is not a fit for a remote listing.

2. It uses Streamable HTTP

Remote servers should use the Streamable HTTP transport. SSE is deprecated, and the Registry recommends publishing an SSE remote only to keep existing clients working. If you are still on SSE, move to Streamable HTTP first.

3. Authentication is settled

Decide how clients will authenticate before you publish, because the listing records it. For header-based authentication, the entry declares the header name and marks it as required and secret. Clients supply their own value when they connect. If you have not chosen between API keys, bearer tokens, and OAuth yet, read our guide to API authentication for MCP first.

4. The tool surface is reviewed

A public listing invites strangers to connect. Make sure only reviewed tools are exposed, names and descriptions are clear, and write operations are deliberate. Test discovery and tool calls with a client or MCP Inspector before you list anything.

5. You know which namespace you want

The server name is permanent for that listing, and it decides how users judge who published it. Pick it on purpose, as the next section explains.


Server names and namespaces

Every Registry server name has two parts: a namespace and a server name, written as namespace/server. The namespace you can use depends on how you authenticate when publishing.

Authentication methodName formatExample
GitHubio.github.username/* or io.github.orgname/*io.github.alice/weather
DNS or HTTP (domain)Reverse-DNS of your domain, such as com.example/*com.example/weather

For a SaaS product with its own domain, a domain namespace is usually the better choice. A name like com.yourproduct/api signals that the listing comes from the company that owns yourproduct.com, while a GitHub namespace only proves control of a GitHub account.

One subtlety matters here. The Registry verifies that you control the namespace, not that you control the remote URL. A server named com.example/weather proves ownership of example.com, but the Registry does not check that the endpoint is on that domain. Serving your MCP endpoint from a subdomain of the same domain, such as mcp.example.com, keeps the name and the URL visibly consistent for users.


Writing server.json for a remote server

A remote-only server uses a remotes array instead of packages. Because there is no package, the package ownership checks do not apply. A minimal entry looks like this:

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
  "name": "com.example/acme-api",
  "title": "Acme API",
  "description": "Manage Acme projects, invoices, and customers from AI agents.",
  "version": "1.0.0",
  "remotes": [
    {
      "type": "streamable-http",
      "url": "https://mcp.example.com/mcp",
      "headers": [
        {
          "name": "X-API-Key",
          "description": "Your Acme API key",
          "isRequired": true,
          "isSecret": true
        }
      ]
    }
  ]
}

Check the $schema URL against the current Registry quickstart before you publish, since the schema is versioned.

Keep the description to 100 characters

The Registry limits description to 100 characters and rejects longer values. Say what the server lets an agent do, not what your company does.

Declare headers, never values

The headers list tells clients which header to send and whether it is required or secret. It must not contain a real key. Anything in server.json becomes public.

Use URL variables for multi-tenant endpoints

If each customer has their own endpoint, the Registry supports template variables in the URL, such as https://{tenant_id}.example.com/mcp, with a description, a required flag, and optional defaults or a fixed list of choices. Clients ask the user for the value and resolve the URL.


How to publish, step by step

Step 1: Install mcp-publisher

The official mcp-publisher CLI is available as a prebuilt binary from the Registry's GitHub releases and through Homebrew (brew install mcp-publisher). Run mcp-publisher --help to confirm it works.

Step 2: Create server.json

Run mcp-publisher init in your project to generate a template. For a remote-only server, the template still includes a packages entry, so replace it with a remotes array like the example above.

Step 3: Authenticate

Pick the method that matches your namespace:

  • GitHub: mcp-publisher login github starts a device sign-in flow. It grants your personal namespace. The Registry's docs note that this interactive flow currently cannot publish to an organization namespace; for that, use GitHub Actions or a personal access token that can read your organization role, and you must be an organization owner.

  • DNS: generate a key pair, publish the public key as a TXT record of the form v=MCPv1; k=ed25519; p=... on the apex of your domain, then run mcp-publisher login dns --domain example.com with the private key.

  • HTTP: serve the same proof record as plain text at https://example.com/.well-known/mcp-registry-auth, then run mcp-publisher login http --domain example.com with the private key.

Keep the private key out of your repository and treat it like any other signing credential.

Step 4: Publish

Run mcp-publisher publish, or pass a path if server.json lives elsewhere. The CLI validates the file against the schema, and the Registry checks your namespace authentication before accepting it.

Step 5: Verify the listing

Search the Registry for your server name and confirm the endpoint, headers, and description are what you expect. Then connect from a real client, using only the information in the listing, to make sure a new user could get started from it.


Versions and updates

Every successful publish creates a new, immutable version. Changing the description, the URL, or the declared headers means publishing a new version, not editing the old one. Because listings cannot currently be unpublished, removing your server or changing domains later does not remove the existing public entry.

This makes your MCP endpoint a long-lived public contract. Keep the URL stable, and handle tool changes behind it with the same care you give API changes. Our guide to MCP server versioning and safe updates covers how to change tools without breaking connected clients.


Common problems and how to fix them

The DNS TXT record is under a selector

The proof record must sit on the apex of the domain, such as example.com, not on a name like _mcp-auth.example.com. A record in the wrong place fails with a signature error. Check it with dig TXT example.com +short.

A stale key is still published

If you rotated keys, remove the old proof record. Compare the Expected proof record line printed by the login command with what is actually published.

HTTP verification fails with a 401

The Registry fetches the well-known file from its own cloud infrastructure, so a request that works from your laptop can still fail. Its docs list the usual causes: a WAF or bot rule that blocks non-browser clients, a redirect (redirects are not followed), an unreachable IPv6 address, or an HTML error page returned with a 200 status. Allow plain HTTPS requests to that path and serve it without redirects.

The description is rejected

Shorten it to 100 characters or fewer.

The organization namespace is not granted

Use GitHub Actions or a personal access token with permission to read your organization role, and make sure you are an owner of that organization.


Publishing a hosted server with 0mcp

If your MCP server is hosted on 0mcp, you can submit it to the official Registry from the server's settings instead of writing server.json and running the CLI yourself. Registry publishing is available on the Pro plan and needs a verified custom domain with active HTTPS, a published server revision, a running server, and tools that use one supported scheme: no authentication, an API key header, or a bearer header. OAuth and mixed authentication are not supported for Registry submission yet.

0mcp generates and locks the Registry name from your custom domain and server slug, so mcp.example.com with the slug weather becomes com.example.mcp/weather. You edit the title, the description, and the website, repository, and icon URLs, review readiness checks, and submit. The first submission is version 1.0.0, and each later submission creates the next patch version. Secret values are never included in the entry. See the 0mcp MCP Registry guide for the full requirements, and how to connect a remote MCP server to Claude and ChatGPT for what users do after they find your server.


Final checklist before you publish

  • The endpoint is public and served over Streamable HTTP.

  • You chose a namespace that matches your company's domain, or a GitHub namespace on purpose.

  • The description is 100 characters or fewer and says what agents can do.

  • Required headers are declared as secret, with no real values in the file.

  • Only reviewed tools are exposed, and discovery and calls are tested.

  • You are ready for the listing to be public and permanent.

  • You have a plan for keeping the URL stable and shipping tool changes safely.

FAQ

01Does the MCP Registry host my MCP server?+

No. The Registry stores metadata about your server, such as its name, description, version, and remote URL or packages. Your server still has to run somewhere, stay publicly reachable, and enforce its own authentication.

02Can I publish a remote MCP server without an npm or Docker package?+

Yes. A remote-only server uses a <code>remotes</code> array in <code>server.json</code> instead of <code>packages</code>, and the package ownership checks do not apply. The listed URL must be publicly accessible.

03Should I use GitHub or domain authentication?+

For a SaaS product with its own domain, domain authentication through DNS or HTTP is usually better, because the server name then reflects your company's domain, such as <code>com.example/api</code>. GitHub authentication gives a name like <code>io.github.username/server</code>, which only proves control of a GitHub account.

04Can I put my API key in server.json?+

No. Everything in <code>server.json</code> is public. Declare the header name and mark it as required and secret; each client supplies its own value when it connects.

05Can I edit or remove a listing after publishing?+

Each publish creates an immutable version, so changes mean publishing a new version. The Registry currently does not support unpublishing, so an existing listing stays public even if you take the server down.

06Why does DNS verification fail with a signature error?+

The most common cause is a TXT record placed under a selector such as <code>_mcp-auth.example.com</code> instead of the domain apex. A stale record from a rotated key can also cause failures, so remove old proof records.