# How to publish an MCP server to the MCP Registry

Level 4: Build · 10 min · Updated 19 November 2026 · Path: Build MCP servers

By the end 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](https://ai-powered.com/academy/glossary/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.

*Diagram: 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](https://ai-powered.com/academy/build-mcp-servers/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

```shell
brew install mcp-publisher
```

Or download a release binary on macOS or Linux:

```shell
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:

```json
{
  "$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`:

```json
"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

```shell
mcp-publisher login github
mcp-publisher publish
```

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

**Try it**

Check that your server is listed, straight from the registry's API:

```shell
curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.my-username/weather"
```

## 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.

## Key takeaways

- 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

- Go through the [security checklist](https://ai-powered.com/academy/build-mcp-servers/mcp-server-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.

## Sources

Official documentation, checked on 19 November 2026:

- [Quickstart: Publish an MCP server to the MCP Registry (modelcontextprotocol.io)](https://modelcontextprotocol.io/registry/quickstart)
- [Package types (modelcontextprotocol.io)](https://modelcontextprotocol.io/registry/package-types)
- [Publishing remote servers (modelcontextprotocol.io)](https://modelcontextprotocol.io/registry/remote-servers)
- [Registry authentication (modelcontextprotocol.io)](https://modelcontextprotocol.io/registry/authentication)

Next lesson: [Remote MCP servers and sign-in: OAuth, CIMD and enterprise login](https://ai-powered.com/academy/build-mcp-servers/remote-server-sign-in)
