Skip to content

How to publish an MCP server to the MCP Registry

Level 4: Build. About 10 min. Checked on 19 November 2026 against MCP Registry (preview), server.json schema 2025-12-11.
Stage 4 of 4: Build

In this lesson you'll write a valid server.json, prove you own the namespace and package, and publish your server to the official MCP Registry.

You've built a server that works on your machine. Now you want other people to find it without you posting the link in five places. The official MCP Registry is where apps, directories and other registries look for MCP servers, and getting listed takes one small file and two commands.

The registry stores metadata only: your server's name, description, version and where to get it. The code stays on npm, PyPI, NuGet, a container registry or your own host. This directory, for one, discovers new servers from it.

As of 19 November 2026 the registry is in preview: its docs say breaking changes or data resets may happen before general availability.

Buildan MCP SDKTestMCP InspectorSecurethe checklistPublishMCP Registry
From code to a server people can find. Build a server with an MCP SDK, test it with the MCP Inspector, check it against the security list, then publish its metadata to the MCP Registry.

Before you start

  • A working server (see Build your first MCP server).
  • For a package-based server: the package published to its registry first, for example with npm publish --access public.
  • A GitHub account, for the simplest sign-in, or a domain you control.

1. Choose your server's name

Names are namespace/server, and how you sign in decides the namespace. The registry checks that you control it:

  • GitHub: io.github.<your-username>/…, for example io.github.my-username/weather. An organization namespace (io.github.<org>/…) needs you to be an owner of the organization, and as of 19 November 2026 the interactive mcp-publisher login github can't publish to one; the docs point to GitHub Actions or a personal access token with read:org instead.
  • Your domain: reverse-DNS names such as com.example/weather, proven with a DNS TXT record on the domain or a file at https://example.com/.well-known/mcp-registry-auth.

2. Prove you own the package

The registry checks that the package points back at your server name:

  • npm: add "mcpName": "io.github.my-username/weather" to package.json, then publish a new version of the package.
  • PyPI and NuGet: put a line mcp-name: io.github.my-username/weather (or the same in an HTML comment) in the package README.
  • Other types: see the package types page in the sources below.

3. Install mcp-publisher

brew install mcp-publisher

Or download a release binary on macOS or Linux:

curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher && sudo mv mcp-publisher /usr/local/bin/

Check it with mcp-publisher --help.

4. Write server.json

Run mcp-publisher init in your project to generate a template, then edit it. A package-based server:

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
  "name": "io.github.my-username/weather",
  "description": "An MCP server for weather information.",
  "repository": {
    "url": "https://github.com/my-username/mcp-weather-server",
    "source": "github"
  },
  "version": "1.0.1",
  "packages": [
    {
      "registryType": "npm",
      "identifier": "@my-username/mcp-weather-server",
      "version": "1.0.1",
      "transport": { "type": "stdio" }
    }
  ]
}
  • name must match mcpName in package.json exactly.
  • description is limited to 100 characters; longer ones fail validation. Say what the server does.
  • If the server needs keys, list them under environmentVariables with isRequired and isSecret, so apps and directories can show them. This directory uses them to build its install snippets.

For a remote-only server, replace packages with remotes:

"remotes": [
  { "type": "streamable-http", "url": "https://weather.example.com/mcp" }
]

The URL must be publicly reachable. Note that the registry verifies your namespace, not that you control the URL.

Run mcp-publisher validate to check the file without publishing.

5. Sign in and publish

mcp-publisher login github
mcp-publisher publish

login github prints a code; enter it at https://github.com/login/device.

When it fails

  • "Registry validation failed for package": the ownership marker is missing (mcpName for npm, the mcp-name: README line for PyPI and NuGet), or you published the package before adding it.
  • "You do not have permission to publish this server": the name doesn't match your sign-in, for example a GitHub sign-in with a name outside io.github.<your-username>/.
  • "Invalid or expired Registry JWT token": run mcp-publisher login github again.

To publish new versions automatically, the registry docs have a guide for GitHub Actions.

In short

  • Publish the package first, with your server name in it (mcpName for npm, an mcp-name: README line for PyPI and NuGet).
  • server.json describes the server; the description is 100 characters at most.
  • mcp-publisher login, then mcp-publisher publish, then check the API.

What to try next

Share this lesson
  • Go through the security checklist before your first public version.
  • List your server's keys under environmentVariables, so directories like this one can show people what to fill in.

Lesson 4 of 6 in this path

Words used in this lesson

Sources

Official documentation, checked on 19 November 2026. Products change: if a step differs, the source has the current version.

Get the next lesson

New Academy lessons are announced in the weekly AI-Powered email.