How to Publish to the Official MCP Registry: server.json, Namespaces and mcp-publisher
To publish to the official MCP Registry at registry.modelcontextprotocol.io, you write a server.json, authenticate with mcp-publisher login (GitHub gives you io.github.<username>/*, DNS or HTTP auth gives you a reverse-DNS namespace like com.example/*), and run mcp-publisher publish. A remote-only server needs a remotes entry and no package. The registry stores metadata only, versions are immutable, and it is still in preview.
The official MCP Registry is a metadata catalog that MCP clients and sub-registries can read. It is not a review queue like Claude's or ChatGPT's directories, and listing there does not list you in Claude: Anthropic says its directory is independent of the open MCP Registry. It is still worth doing so other clients and aggregators can find your server. mcplisted is not affiliated with the registry maintainers.
Before you start
- The registry is in preview. Its docs warn that breaking changes or data resets may occur before general availability.
- It hosts metadata only, not code. Package-based servers must already be published to npm, PyPI, NuGet, Docker/OCI, or as MCPB releases.
- Publishing does not happen through a pull request to the registry repo. Use the
mcp-publisherCLI.
Step 1: Pick your namespace
Your server name is namespaced, and the namespace depends on how you authenticate:
| Authentication | Name format | Example |
|---|---|---|
| GitHub | io.github.username/* or io.github.orgname/* |
io.github.alice/weather-server |
| DNS (TXT record on the apex domain) | Reverse DNS of your domain | com.example/weather |
HTTP (/.well-known/mcp-registry-auth) |
Reverse DNS of your domain | com.example/weather |
If your remote URL is on a domain you control, the docs suggest DNS or HTTP auth so the name and URL show the same publisher.
One known limitation: mcp-publisher login github cannot currently publish to an organization namespace. The docs say to use GitHub Actions (OIDC) or a personal access token with org read permission, and you must be an Owner of the org.
Step 2: Install mcp-publisher
brew install mcp-publisher
mcp-publisher --help
Pre-built binaries are also on the registry's GitHub releases page. The CLI has init, login, logout, publish, status, and validate commands.
Step 3: Write server.json
Run mcp-publisher init for a template. For a remote-only server, replace the generated packages array with remotes:
{
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
"name": "com.example/acme-analytics",
"title": "ACME Analytics",
"description": "Real-time business intelligence and reporting",
"version": "2.0.0",
"remotes": [
{ "type": "streamable-http", "url": "https://analytics.example.com/mcp" }
]
}
Rules from the docs:
descriptionis limited to 100 characters; longer descriptions fail validation.- A remote MUST be publicly accessible at its URL.
- Use
"type": "streamable-http". The docs say to publish"sse"only to support existing clients. - Remotes can declare URL template variables such as
https://{tenant_id}.example.com/mcpand requiredheaderssuch as an API key.
Step 4: Prove package ownership (package-based servers only)
For npm, add mcpName to package.json and make it equal the server name. For PyPI and NuGet, the docs say to put an mcp-name: <server-name> line in the package README. A remote-only server skips this step.
Note what is not verified: the registry checks that you control the namespace, not that you control the remote URL. Several names can point at the same URL.
Step 5: Log in and publish
mcp-publisher login github
mcp-publisher publish
curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.my-username/weather"
For DNS auth, add a TXT record like example.com. IN TXT "v=MCPv1; k=ed25519; p=<public key>" on the apex (not a selector subdomain), then run mcp-publisher login dns --domain example.com. The docs note Ed25519 key generation needs OpenSSL 3; macOS's default LibreSSL fails.
Versioning rules
versionis required and MUST be unique per publication. Published metadata can't be changed.- Semantic versioning is recommended. Version ranges like
^1.2.3or1.xare prohibited. - For remote servers with an API version, align the server version with it.
- For metadata-only updates, the docs suggest prerelease versions like
1.2.3-1, but warn these sort before1.2.3.
More on change management in versioning and updating a listed server.
Custom metadata and removal
Only _meta under io.modelcontextprotocol.registry/publisher-provided is kept, up to 4KB of JSON; other keys are silently dropped. To unpublish, mcp-publisher status --status deleted hides a version or all versions, but metadata is never permanently removed.
What gets removed
The moderation policy is permissive. It removes illegal content, malware, spam (including servers stuffed with marketing copy), and non-functioning servers. It does not remove low-quality or buggy servers, or servers with security vulnerabilities.
Troubleshooting
| Error | Fix |
|---|---|
| Registry validation failed for package | Add mcpName (npm) or the mcp-name: README line |
| Invalid or expired Registry JWT token | Run mcp-publisher login again |
| You do not have permission to publish this server | Name doesn't match your auth namespace |
Before publishing the remote URL anywhere, run a free check to make sure it answers Streamable HTTP, and compare registry fields with directory listing fields in the cross-directory checklist.
Run a free check on your MCP server →Paste your URL and see what Claude, ChatGPT and Gemini reviewers will flag.
FAQ
Does the MCP Registry review my server?
No review queue is described. The registry validates server.json and namespace ownership, and its moderation policy only removes illegal content, malware, spam, and non-functioning servers.
Will publishing to the registry get me into Claude's directory?
No. Anthropic says the Claude directory is independent of the MCP Registry and you must submit through its own portal.
Can I edit a published version?
No. Version metadata is immutable. Publish a new server.json with a new, unique version string.
Can I publish a remote server without npm or PyPI?
Yes. A remote-only server.json uses a remotes entry and can omit packages, so package ownership verification does not apply.
Sources
- Quickstart: Publish an MCP Server to the MCP Registry
- MCP Registry: Authentication
- MCP Registry: Publishing Remote Servers
- MCP Registry: Versioning Published MCP Servers
- MCP Registry: FAQ
- MCP Registry: Moderation Policy
- Official Registry server.json requirements (GitHub)
- Directory connectors vs custom connectors (Claude docs)
Rules change. If something here is out of date, email hello@mcplisted.com and we'll fix it. See our editorial policy.