Skip to content

Latest commit

 

History

History
293 lines (223 loc) · 9.17 KB

quickstart.mdx

File metadata and controls

293 lines (223 loc) · 9.17 KB
title sidebarTitle
Quickstart: Publish an MCP Server to the MCP Registry
Quickstart: Publish a Server
The MCP Registry is currently in preview. Breaking changes or data resets may occur before general availability. If you encounter any issues, please report them on [GitHub](https://github.com/modelcontextprotocol/registry/issues).

This tutorial will show you how to publish an MCP server written in TypeScript to the MCP Registry using the official mcp-publisher CLI tool.

Prerequisites

  • Node.js — This tutorial assumes the MCP server is written in TypeScript.
  • npm account — The MCP Registry only hosts metadata, not artifacts. Before publishing to the MCP Registry, we will publish the MCP server's package to npm, so you will need an npm account.
  • GitHub account — The MCP Registry supports multiple authentication methods. For simplicity, this tutorial will use GitHub-based authentication, so you will need a GitHub account.

If you do not have an MCP server written in TypeScript, you can copy the weather-server-typescript server from the modelcontextprotocol/quickstart-resources repository to follow along with this tutorial:

git clone --depth 1 git@github.com:modelcontextprotocol/quickstart-resources.git
cp -r quickstart-resources/weather-server-typescript .
rm -rf quickstart-resources
cd weather-server-typescript

And edit package.json to reflect your information:

 {
-  "name": "mcp-quickstart-ts",
-  "version": "1.0.0",
+  "name": "@my-username/mcp-weather-server",
+  "version": "1.0.1",
   "main": "index.js",
   "license": "ISC",
-  "description": "",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/my-username/mcp-weather-server.git"
+  },
+  "description": "An MCP server for weather information.",
   "devDependencies": {

Step 1: Add verification information to the package

The MCP Registry verifies that a server's underlying package matches its metadata. For npm packages, this requires adding an mcpName property to package.json:

 {
   "name": "@my-username/mcp-weather-server",
   "version": "1.0.1",
+  "mcpName": "io.github.my-username/weather",
   "main": "index.js",

The value of mcpName will be your server's name in the MCP Registry.

Because we will be using GitHub-based authentication, mcpName must start with io.github.my-username/.

Step 2: Publish the package

The MCP Registry only hosts metadata, not artifacts, so we must publish the package to npm before publishing the server to the MCP Registry.

Ensure the distribution files are built:

# Navigate to project directory
cd weather-server-typescript

# Install dependencies
npm install

# Build the distribution files
npm run build

Then follow npm's publishing guide. In particular, you will probably need to run the following commands:

# If necessary, authenticate to npm
npm adduser

# Publish the package
npm publish --access public

You can verify your package is published by visiting its npm URL, such as https://www.npmjs.com/package/@my-username/mcp-weather-server.

Step 3: Install mcp-publisher

Install the mcp-publisher CLI tool using a pre-built binary or Homebrew:

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/
$arch = if ([System.Runtime.InteropServices.RuntimeInformation]::ProcessArchitecture -eq "Arm64") { "arm64" } else { "amd64" }; Invoke-WebRequest -Uri "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_windows_$arch.tar.gz" -OutFile "mcp-publisher.tar.gz"; tar xf mcp-publisher.tar.gz mcp-publisher.exe; rm mcp-publisher.tar.gz
# Move mcp-publisher.exe to a directory in your PATH
brew install mcp-publisher

Verify that mcp-publisher is correctly installed by running:

mcp-publisher --help

You should see output like:

MCP Registry Publisher Tool

Usage:
  mcp-publisher <command> [arguments]

Commands:
  init          Create a server.json file template
  login         Authenticate with the registry
  logout        Clear saved authentication
  publish       Publish server.json to the registry

Step 4: Create server.json

The mcp-publisher init command can generate a server.json template file with some information derived from your project.

In your server project directory, run mcp-publisher init:

mcp-publisher init

Open the generated server.json file, and you should see contents like:

{
  "$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.0",
  "packages": [
    {
      "registryType": "npm",
      "identifier": "@my-username/mcp-weather-server",
      "version": "1.0.0",
      "transport": {
        "type": "stdio"
      },
      "environmentVariables": [
        {
          "description": "Your API key for the service",
          "isRequired": true,
          "format": "string",
          "isSecret": true,
          "name": "YOUR_API_KEY"
        }
      ]
    }
  ]
}

Edit the contents as necessary:

 {
   "$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.0",
+  "version": "1.0.1",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@my-username/mcp-weather-server",
-      "version": "1.0.0",
+      "version": "1.0.1",
       "transport": {
         "type": "stdio"
-      },
-      "environmentVariables": [
-        {
-          "description": "Your API key for the service",
-          "isRequired": true,
-          "format": "string",
-          "isSecret": true,
-          "name": "YOUR_API_KEY"
-        }
-      ]
+      }
     }
   ]
 }

The name property in server.json must match the mcpName property in package.json.

Step 5: Authenticate with the MCP Registry

For this tutorial, we will authenticate with the MCP Registry using GitHub-based authentication.

Run the mcp-publisher login command to initiate authentication:

mcp-publisher login github

You should see output like:

Logging in with github...

To authenticate, please:
1. Go to: https://github.com/login/device
2. Enter code: ABCD-1234
3. Authorize this application
Waiting for authorization...

Visit the link, follow the prompts, and enter the authorization code that was printed in the terminal (e.g., ABCD-1234 in the above output). Once complete, go back to the terminal, and you should see output like:

Successfully authenticated!
✓ Successfully logged in

Step 6: Publish to the MCP Registry

Finally, publish your server to the MCP Registry using the mcp-publisher publish command:

mcp-publisher publish

You should see output like:

Publishing to https://registry.modelcontextprotocol.io...
✓ Successfully published
✓ Server io.github.my-username/weather version 1.0.1

You can verify that your server is published by searching for it using the MCP Registry API:

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

You should see your server's metadata in the search results JSON:

{"servers":[{ ... "name":"io.github.my-username/weather" ... }]}

Troubleshooting

{/* prettier-ignore-start */}

Error Message Action
"Registry validation failed for package" Ensure your package includes the required validation information (e.g, mcpName property in package.json).
"Invalid or expired Registry JWT token" Re-authenticate by running mcp-publisher login github.
"You do not have permission to publish this server" Your authentication method doesn't match your server's namespace format. With GitHub auth, your server name must start with io.github.your-username/.

{/* prettier-ignore-end */}

Next Steps