Skip to content

Publish an MCP server

Last reviewed October 23, 2026

Publishing an MCP server is three jobs. Put the package where people install software from, list it in the MCP Registry so clients and directories can find it, and write the README section people will copy from. People decide whether to try a server from its README, so the last job is not the least.

Publish the package first

A local server is something people install, so it needs to live on a package registry: npm for TypeScript, PyPI for Python, or NuGet, crates.io, a container registry or an MCPB bundle for the rest. For an npm package that people run with npx, give it a bin entry and start server.mjs with the line #!/usr/bin/env node:

package.json
{
  "name": "@you/add-numbers-mcp",
  "version": "1.0.0",
  "type": "module",
  "bin": { "add-numbers-mcp": "server.mjs" },
  "mcpName": "io.github.you/add-numbers"
}

The mcpName field is for the registry, below. A Python package does the same job with a console script in [project.scripts] of pyproject.toml, so people can run it with uvx or pipx.

Publish from CI if you can. On npm, npm publish --provenance from GitHub Actions records where the package was built, and anyone can check it (npm provenance). For a program that runs on someone's machine with their credentials, that check is worth more than any badge.

List it in the MCP Registry

The official MCP Registry records your server's name, what it does and where to get it. It holds metadata, never your code, and clients and directories read from it. It is still in preview, so expect the odd breaking change (about the registry).

You publish with the mcp-publisher command (registry quickstart):

shell
brew install mcp-publisher
mcp-publisher init           # writes server.json
mcp-publisher login github   # proves you own io.github.<you>/
mcp-publisher publish

init writes a server.json for you to fill in. Signing in with GitHub gives you the namespace io.github.<your-username>/; to publish under your own domain instead, sign in with login dns or login http (namespaces).

server.json
{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
  "name": "io.github.you/add-numbers",
  "description": "Adds two numbers. A minimal example server.",
  "repository": { "url": "https://github.com/you/add-numbers-mcp", "source": "github" },
  "version": "1.0.0",
  "packages": [
    {
      "registryType": "npm",
      "identifier": "@you/add-numbers-mcp",
      "version": "1.0.0",
      "transport": { "type": "stdio" }
    }
  ]
}

A remote server lists a remotes entry with type streamable-http and its URL instead of packages (remote servers).

Prove the package is yours

The registry will not list a package it cannot tie to you, so each package carries your server's registry name (package types):

  • npm: "mcpName": "io.github.you/add-numbers" in package.json, as above.
  • PyPI and NuGet: a line mcp-name: io.github.you/add-numbers in the README, which becomes the package's description. An HTML comment works and keeps it out of sight.
  • crates.io: the same line, but visible, because crates.io strips HTML comments.
  • Containers: LABEL io.modelcontextprotocol.server.name="io.github.you/add-numbers". MCPB bundles: a fileSha256 in server.json.

Give each client its install snippet

Put a section in your README with the exact lines for each client. People copy, they do not translate, and every client wants something slightly different.

Claude Code (docs) and Codex (docs):

shell
claude mcp add add-numbers -- npx -y @you/add-numbers-mcp
codex mcp add add-numbers -- npx -y @you/add-numbers-mcp

Cursor (.cursor/mcp.json, docs), Claude Desktop (claude_desktop_config.json) and Gemini CLI (settings.json, docs) read an mcpServers block:

mcpServers
{
  "mcpServers": {
    "add-numbers": { "command": "npx", "args": ["-y", "@you/add-numbers-mcp"] }
  }
}

VS Code is the odd one out. Its .vscode/mcp.json uses the key "servers", and each entry names its type (docs). Give VS Code users their own snippet rather than the mcpServers block.

.vscode/mcp.json
{
  "servers": {
    "add-numbers": { "type": "stdio", "command": "npx", "args": ["-y", "@you/add-numbers-mcp"] }
  }
}

If your server needs an API key, show where it goes in each snippet: -e for Claude Code, --env for Codex, an env object in the JSON forms. Claude Desktop also needs a restart after its file changes.

Other directories

Many directories copy the official registry, so publishing there reaches them too. Glama copies everything in it, and lets you claim your listing with a glama.json at the root of the repository. Smithery no longer takes new servers: its hosting closed on 31 October 2026 and smithery.ai carries on as a plain directory run by Arcade (Apideck). And submit the repository here (submit a listing), where people find it with a safety rating next to it.

Release from CI, every time

Keep the version in package.json (or pyproject.toml) and server.json the same, and let one CI job publish both the package and the registry entry on each release tag. A registry entry that lags the package by three versions is how people end up installing something you already fixed.

Building something else? See the guides to a skill and a plugin or marketplace.