Purpose

Package an MCP server for distribution so others can install and configure it. Covers npm/PyPI publishing, Docker packaging, MCP registry listing, and writing the installation documentation that hosts need.

When to use this skill

• Publishing an MCP server to npm or PyPI
• Creating a Docker image for a remote MCP server
• Listing a server on the MCP registry (registry.modelcontextprotocol.io)
• Writing installation and configuration documentation for end users
• Packaging a server as a standalone binary

Do not use this skill when

• Building the server itself → use

  mcp-development

  or

  mcp-builder

• Deciding transport/auth → use

  mcp-auth-transports

• The server is project-internal with no distribution need

Operating procedure

Phase 1 — Package for distribution

npm (TypeScript servers)

1. Set

   "bin"

   in

   package.json

   pointing to the compiled entry point:

{
  "name": "@yourorg/mcp-server-myservice",
  "version": "1.0.0",
  "bin": { "mcp-server-myservice": "dist/index.js" },
  "files": ["dist"],
  "engines": { "node": ">=18" }
}

2. Add shebang to entry file:

   #!/usr/bin/env node

3. Build and publish:

   npm run build && npm publish

4. Users install with:

   npx @yourorg/mcp-server-myservice

   or

   npm install -g @yourorg/mcp-server-myservice

Naming convention:

mcp-server-<service>

or

@org/mcp-server-<service>

PyPI (Python servers)

1. Use

   pyproject.toml

   with entry points:

[project.scripts]
mcp-server-myservice = "myservice.server:main"

[project]
name = "mcp-server-myservice"
dependencies = ["mcp>=1.2.0"]

2. Build and publish:

   uv build && uv publish

   (or

   pip install build && python -m build && twine upload dist/*

   )

Docker (remote servers)

FROM node:22-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci --production
COPY dist/ ./dist/
EXPOSE 3000
CMD ["node", "dist/index.js"]

Phase 2 — Write installation docs

The README must include host-specific configuration snippets. Users need copy-paste configs:

## Installation

### Claude Desktop
Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
\```json
{
  "mcpServers": {
    "myservice": {
      "command": "npx",
      "args": ["@yourorg/mcp-server-myservice"],
      "env": { "API_KEY": "your-key" }
    }
  }
}
\```

### VS Code / Copilot
Add to `.vscode/mcp.json`:
\```json
{
  "servers": {
    "myservice": {
      "command": "npx",
      "args": ["@yourorg/mcp-server-myservice"],
      "env": { "API_KEY": "your-key" }
    }
  }
}
\```

Phase 3 — Register on MCP registry

The MCP registry at

registry.modelcontextprotocol.io

is a directory of MCP servers. To list your server:

1. Ensure the server repo is public on GitHub
2. Include a well-structured README with: purpose, tools list, install instructions, host configs
3. Submit via the registry's contribution process (typically a PR to the registry repo)

Phase 4 — Quality checklist

Before publishing, verify:

• All tools have clear

  description

  and

  inputSchema

• tools/list

  returns complete tool definitions in MCP Inspector
• All tools handle errors gracefully (no unhandled exceptions reaching the client)
• Tool annotations (

  readOnlyHint

  ,

  destructiveHint

  ) are set correctly
• README includes install command, host configs, and required environment variables

• package.json

  /

  pyproject.toml

  has correct entry point and dependencies
• No hardcoded paths or machine-specific configuration

Decision rules

• Use

  npx

  in host configs so users don't need global install
• For Python, prefer

  uvx

  or

  pipx

  over

  pip install -g

• Include all required env vars in the documentation with descriptions
• If the server needs API keys, document where to get them
• Semantic versioning: breaking changes to tool schemas = major version bump

Output requirements

1. Publishable package (npm tarball, PyPI wheel, or Docker image)
2. README with tool list, install command, and host config snippets for at least 2 hosts
3. MCP Inspector verification passing
4. Published to registry (npm/PyPI and optionally MCP registry)

Related skills

• mcp-development

  — server development lifecycle

• mcp-host-integration

  — host-specific configuration patterns

• mcp-schema-contracts

  — schema versioning for published servers

• mcp-testing-evals

  — pre-publish quality verification

Failure handling

• If

  npx

  fails to run the package, verify the

  bin

  field in

  package.json

  and the shebang line
• If users report "tool not found", check that

  tools

  capability is declared in

  initialize

  response
• If the server works locally but fails for users, check env var documentation — missing API keys are the #1 issue