Prepare docs for modelcontextprotocol.io (#728)
This PR reorganizes and extends the existing documentation in preparation for publishing on https://modelcontextprotocol.io/. The current plan is for docs to remain in this repo, and be synced to the `modelcontextprotocol/modelcontextprotocol` whenever necessary (e.g., accompanying a release of the registry). I have included a script in https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1725 (`bin/pull-registry-docs.sh`) that can be run manually to perform the sync. If we later decide to permanently move the docs to the `modelcontextprotocol/modelcontextprotocol` repo, that also works. This PR puts all https://modelcontextprotocol.io/ docs into `docs/modelcontextprotocol-io/`. Docs outside that subdirectory, such as `docs/administration/admin-operations.md`, are intended to be accessible solely via this repo. One major exception is the `docs/reference/server-json/` subdirectory, which will depend on the resolution of https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1649. However, I think we could address that in a follow-up PR. --------- Co-authored-by: Adam Jones <adamj+git@anthropic.com> Co-authored-by: Claude <noreply@anthropic.com>
This commit is contained in:
Jonathan Hefner
GitHub
parent
3d3337942b
commit
43d41a242e
1 changed files with 1606 additions and 1397 deletions
289
docs/modelcontextprotocol-io/quickstart.mdx
Normal file
289
docs/modelcontextprotocol-io/quickstart.mdx
Normal file
|
|
@ -0,0 +1,289 @@
|
|||
---
|
||||
title: "Quickstart: Publish an MCP Server to the MCP Registry"
|
||||
sidebarTitle: "Quickstart: Publish a Server"
|
||||
---
|
||||
|
||||
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](https://www.npmjs.com) account.
|
||||
- **GitHub account** — The MCP Registry supports [multiple authentication methods](./authentication.mdx). authentication. For simplicity, this tutorial will use GitHub-based authentication, so you will need a [GitHub](https://github.com/) 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](https://github.com/modelcontextprotocol/quickstart-resources) to follow along with this tutorial:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```diff package.json
|
||||
{
|
||||
- "name": "mcp-quickstart-ts",
|
||||
- "version": "1.0.0",
|
||||
+ "name": "@my-username/mcp-weather-server",
|
||||
+ "version": "1.0.1",
|
||||
"main": "index.js",
|
||||
```
|
||||
|
||||
```diff package.json
|
||||
"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`:
|
||||
|
||||
```diff 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:
|
||||
|
||||
```bash
|
||||
# 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](https://docs.npmjs.com/creating-and-publishing-scoped-public-packages). In particular, you will probably need to run the following commands:
|
||||
|
||||
```bash
|
||||
# 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](https://brew.sh):
|
||||
|
||||
<CodeGroup>
|
||||
|
||||
```bash macOS/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/
|
||||
```
|
||||
|
||||
```powershell Windows
|
||||
$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
|
||||
```
|
||||
|
||||
```bash
|
||||
brew install mcp-publisher
|
||||
```
|
||||
|
||||
</CodeGroup>
|
||||
|
||||
Verify that `mcp-publisher` is correctly installed by running:
|
||||
|
||||
```bash
|
||||
mcp-publisher --help
|
||||
```
|
||||
|
||||
You should see output like:
|
||||
|
||||
```text Output
|
||||
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`:
|
||||
|
||||
```bash
|
||||
mcp-publisher init
|
||||
```
|
||||
|
||||
Open the generated `server.json` file, and you should see contents like:
|
||||
|
||||
```json server.json
|
||||
{
|
||||
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/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:
|
||||
|
||||
```diff server.json
|
||||
{
|
||||
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/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:
|
||||
|
||||
```bash
|
||||
mcp-publisher login github
|
||||
```
|
||||
|
||||
You should see output like:
|
||||
|
||||
```text Output
|
||||
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:
|
||||
|
||||
```text Output
|
||||
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:
|
||||
|
||||
```bash
|
||||
mcp-publisher publish
|
||||
```
|
||||
|
||||
You should see output like:
|
||||
|
||||
```text Output
|
||||
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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```text Output
|
||||
{"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
|
||||
|
||||
- Learn about [support for other package types](./package-types.mdx).
|
||||
- Learn about [support for remote servers](./remote-servers.mdx).
|
||||
- Learn how to [use other authentication methods](./authentication.mdx), such as [DNS authentication](./authentication.mdx#dns-authentication) which enables custom domains for server name prefixes.
|
||||
- Learn how to [automate publishing with GitHub Actions](./github-actions.mdx).
|
||||
Loading…
Reference in a new issue