Should I use a scoped package name?

Yes if publishing under an organization; use the @yourorg/package-name format so ownership is unambiguous.

How do I handle a breaking change?

Bump the MAJOR version and document the migration path in a changelog entry, since removing or renaming a tool breaks every existing integration silently otherwise.

Can I unpublish a package?

npm allows unpublishing only within a short window after publishing; after that, deprecate the version instead and publish a corrected one.

developmentHowTo

Publishing MCP Servers to npm and GitHub

Package an MCP server with a proper package.json, README, and semantic versioning, then publish it to npm and cut a GitHub release.

Quick Answer / TL;DR

Publish an MCP server like any npm package: a bin entry pointing at the compiled output, a README documenting each tool's parameters, semantic versioning where a MAJOR bump means a removed tool or changed schema, and a GitHub release tagged to match the published npm version.

Key Takeaways

A MAJOR version bump means a removed tool or a breaking schema change; new tools are MINOR; fixes are PATCH.
Document every tool's parameters and a request/response example in the README so integrators do not have to read the source.
Automate publish-on-release in CI so a human never has to run npm publish by hand.

Package metadata and versioning

Point the bin field at the compiled entry point, keep the MCP SDK as a dependency (not a devDependency), and follow semantic versioning: MAJOR for breaking tool or schema changes, MINOR for new tools, PATCH for fixes.

json

{
  "name": "@yourorg/analytics-mcp-server",
  "version": "1.1.0",
  "main": "dist/index.js",
  "bin": { "analytics-mcp": "dist/index.js" },
  "scripts": { "build": "tsc", "prepublishOnly": "npm run build" },
  "engines": { "node": ">=18.0.0" }
}

Automated publish on release

Trigger the publish step from a GitHub release rather than a manual local npm publish, so the published package always matches a tagged, reviewed commit.

text

# .github/workflows/publish.yml
on:
  release:
    types: [created]
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: "20", registry-url: "https://registry.npmjs.org" }
      - run: npm ci && npm run build && npm test
      - run: npm publish --access public
        env: { NODE_AUTH_TOKEN: "${{ secrets.NPM_TOKEN }}" }