Register MCP reference and docs servers in the official server registry

[olaservo]

Overview

This document tracks the registration of all official MCP reference servers and the documentation server in the MCP Server Registry.

Goal: Register all 8 servers to promote discoverability through the official registry as we deprecate README-based server listings.

Important: This document provides guidance and checklists, but always refer to the official registry documentation for the most up-to-date and accurate information.

Key Requirements (From Official Docs)

Based on official registry documentation:

1. NPM packages: mcpName in package.json MUST match server name in server.json
2. PyPI packages: mcp-name: marker in README MUST match server name in server.json (can be in HTML comment)
3. Remote servers: MUST be publicly accessible at specified URL
4. Namespace: For GitHub auth, must use io.github.[org-name]/[server-name] format
5. Schema: server.json should include $schema property pointing to official schema
6. Version matching: Versions in server.json should match published package versions

Server Inventory

NPM Packages (4 servers)

1. everything - @modelcontextprotocol/server-everything

   • Description: Test server exercising all MCP protocol features
   • Version: 0.6.2
   • Location: src/everything/

2. filesystem - @modelcontextprotocol/server-filesystem

   • Description: Filesystem operations (read/write/search)
   • Location: src/filesystem/

3. memory - @modelcontextprotocol/server-memory

   • Description: Knowledge graph-based persistent memory
   • Location: src/memory/

4. sequentialthinking - @modelcontextprotocol/server-sequential-thinking

   • Description: Structured problem-solving with dynamic thinking
   • Location: src/sequentialthinking/

PyPI Packages (3 servers)

5. fetch - mcp-server-fetch

   • Description: Web content fetching with HTML to markdown conversion
   • Version: 0.6.3
   • Location: src/fetch/

6. git - mcp-server-git

   • Description: Git repository interaction and automation
   • Location: src/git/

7. time - mcp-server-time

   • Description: Time and timezone conversion capabilities
   • Location: src/time/

Remote Server

8. docs - MCP Documentation Server
   • URL: https://modelcontextprotocol.io/mcp
   • Description: Official MCP protocol documentation
   • Type: Remote server
   • Transport: Streamable HTTP

Registration Process

Based on the MCP Registry documentation, here's the workflow:

Prerequisites

• Install mcp-publisher CLI tool

  # macOS/Linux - see https://github.com/modelcontextprotocol/registry/blob/main/docs/modelcontextprotocol-io/quickstart.mdx for exact command
  # Windows - see registry docs for PowerShell command

• Ensure packages are published to npm/PyPI
• GitHub account for authentication

For Each Server

See the Publisher Quickstart for the complete official process.

1. Update Package Metadata

   • NPM: Add mcpName property to package.json (must match server name in server.json)
   • PyPI: Add mcp-name: $SERVER_NAME to README (can be in HTML comment)

2. Verify Package Publication

   • Ensure latest version is published to npm/PyPI
   • Confirm package is publicly accessible

3. Create server.json

   cd src/[server-name]
   mcp-publisher init

   Follow the interactive prompts to generate the file. The tool will create the correct structure.

4. Authenticate

   mcp-publisher login github

   • Follow GitHub device flow
   • Must authenticate as modelcontextprotocol organization member

5. Publish to Registry

   mcp-publisher publish

6. Verify Registration

   • Check https://registry.modelcontextprotocol.io/
   • Search for the server by name

Technical Requirements

NPM Packages

Required Changes to package.json:

The mcpName property MUST match the server name from server.json.

{
  "mcpName": "io.github.modelcontextprotocol/server-everything",
  "repository": {
    "type": "git",
    "url": "https://github.com/modelcontextprotocol/servers.git"
  }
}

Reference: Package Types - npm

PyPI Packages

Required Addition to README.md:

The README must contain an mcp-name: $SERVER_NAME string where $SERVER_NAME MUST match the server name from server.json. This can be placed in an HTML comment:

<!-- mcp-name: io.github.modelcontextprotocol/server-fetch -->

Or as plain text near the top of the README.

Reference: Package Types - PyPI

server.json Templates

Note: Use mcp-publisher init to generate the correct structure. The examples below are for reference.

Reference: Publisher Quickstart - server.json structure

For Package-based Servers (NPM/PyPI)

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json",
  "name": "io.github.modelcontextprotocol/server-[name]",
  "description": "Server description here",
  "repository": {
    "url": "https://github.com/modelcontextprotocol/servers",
    "source": "github"
  },
  "version": "0.6.x",
  "packages": [{
    "registryType": "npm",
    "identifier": "@modelcontextprotocol/server-[name]",
    "version": "0.6.x",
    "transport": {
      "type": "stdio"
    }
  }]
}

For PyPI packages, change:

• "registryType": "pypi"
• "identifier": "mcp-server-[name]"

For Remote Servers

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json",
  "name": "io.github.modelcontextprotocol/docs",
  "description": "Official MCP protocol documentation",
  "repository": {
    "url": "https://github.com/modelcontextprotocol/servers",
    "source": "github"
  },
  "version": "1.0.0",
  "remotes": [{
    "url": "https://modelcontextprotocol.io/mcp",
    "type": "streamable-http"
  }]
}

Reference: Remote Servers Documentation

Detailed Checklist

1. everything (NPM)

• Add mcpName to src/everything/package.json
• Verify npm publication status
• Run mcp-publisher init in src/everything/
• Review generated server.json
• Authenticate with GitHub
• Run mcp-publisher publish
• Verify in registry

2. filesystem (NPM)

• Add mcpName to src/filesystem/package.json
• Verify npm publication status
• Run mcp-publisher init in src/filesystem/
• Review generated server.json
• Authenticate with GitHub (if needed)
• Run mcp-publisher publish
• Verify in registry

3. memory (NPM)

• Add mcpName to src/memory/package.json
• Verify npm publication status
• Run mcp-publisher init in src/memory/
• Review generated server.json
• Authenticate with GitHub (if needed)
• Run mcp-publisher publish
• Verify in registry

4. sequentialthinking (NPM)

• Add mcpName to src/sequentialthinking/package.json
• Verify npm publication status
• Run mcp-publisher init in src/sequentialthinking/
• Review generated server.json
• Authenticate with GitHub (if needed)
• Run mcp-publisher publish
• Verify in registry

5. fetch (PyPI)

• Add mcp-name: marker to src/fetch/README.md
• Verify PyPI publication status
• Run mcp-publisher init in src/fetch/
• Review generated server.json
• Authenticate with GitHub (if needed)
• Run mcp-publisher publish
• Verify in registry

6. git (PyPI)

• Add mcp-name: marker to src/git/README.md
• Verify PyPI publication status
• Run mcp-publisher init in src/git/
• Review generated server.json
• Authenticate with GitHub (if needed)
• Run mcp-publisher publish
• Verify in registry

7. time (PyPI)

• Add mcp-name: marker to src/time/README.md
• Verify PyPI publication status
• Run mcp-publisher init in src/time/
• Review generated server.json
• Authenticate with GitHub (if needed)
• Run mcp-publisher publish
• Verify in registry

8. docs (Remote Server)

• Create server.json with remote configuration
  • URL: https://modelcontextprotocol.io/mcp
  • Transport: Streamable HTTP
• Verify remote server is publicly accessible
• Run mcp-publisher init and configure as remote
• Review generated server.json
• Authenticate with GitHub (if needed)
• Run mcp-publisher publish
• Verify in registry

Resources

Registry Documentation

• Publisher Quickstart
• Package Types
• Remote Servers
• Registry Home

Tools

• mcp-publisher CLI: Available via curl, PowerShell, or Homebrew
• Registry API: For verification after publication

Authentication Methods

• GitHub OAuth (recommended for manual registration)
• GitHub OIDC (for CI/CD automation)
• DNS verification (for domain ownership)
• HTTP verification (for domain ownership)

Notes

Namespace Ownership

• All servers should use namespace: io.github.modelcontextprotocol
• Requires authentication as the modelcontextprotocol GitHub organization
• Organization members with appropriate permissions can publish

Version Management

• Ensure server.json versions match published packages
• Consider setting up GitHub Actions for automated publishing
• Future releases should include registry updates in release process

Docker Images

Several servers have Docker images (mcp/fetch, mcp/git, etc.). These could potentially be registered as OCI packages using the io.modelcontextprotocol.server.name annotation in Dockerfiles.

Reference: Package Types - Docker/OCI Images

Special Considerations

• Documentation server (docs) is registered as a remote server using the streamable HTTP transport
• Remote servers MUST be publicly accessible at their specified URL (per Remote Servers docs)
• The remotes and packages properties can coexist in the same server.json, allowing users to choose their preferred installation method
• Some servers support multiple transports; these can be registered with multiple entries in the packages or remotes arrays

Next Steps

1. Install mcp-publisher CLI tool
2. Authenticate with GitHub as modelcontextprotocol org member
3. Work through checklist for each server
4. Document any issues or special cases encountered
5. Update release process to include registry publication
6. Consider automating via GitHub Actions for future releases

---

(originally generated by Claude and edited)

[thoorp]

Remote docs MCP has no authentication and it does not fall into npm or pypi category. Curious, how that is supposed to work.

[olaservo]

Remote docs MCP has no authentication and it does not fall into npm or pypi category. Curious, how that is supposed to work.

I believe that remote servers can be registered with just a URL and transport type?

The auth mentioned in the issue I created may be confusing (it means auth for the mcp publisher)

[CNX402]

Just published io.github.x402node/x402-mcp to the MCP Registry following the new flow (https://registry.modelcontextprotocol.io/?search=x402node). Sharing as an example for third-party migration:

• Server type: stdio
• Distribution: npm (x402node-mcp@0.1.1)
• Use case: Auto-discovers 100+ x402-paid HTTP APIs from Coinbase CDP Bazaar and exposes them as MCP tools (USDC micropayments on Base).
• Namespace authentication: GitHub org membership (had to publicize org membership for io.github.{org}/* namespace ownership verification)

Worked smoothly with mcp-publisher CLI after fixing 2 gotchas:

1. description field must be ≤100 chars (validation error otherwise)
2. GitHub org membership must be public for org-namespaced publishes

Hopefully helpful for others migrating from the deprecated README list.