Publishing Updates to Your MCP Tool on mcpm

Your tool is live. Now users depend on it. This guide covers updating responsibly.

Before You Publish an Update

1. Determine the Bump Type

Change	Version	Command
Bug fix	Patch (1.0.0 → 1.0.1)	mcpm-dev publish
New feature	Minor (1.0.0 → 1.1.0)	mcpm-dev publish --minor
Breaking change	Major (1.0.0 → 2.0.0)	mcpm-dev publish --major

2. Update package.json

{
  "name": "weather-mcp",
  "version": "1.1.0",
  "description": "Get weather data — now with severe weather alerts"
}

3. Write a Changelog

Create CHANGELOG.md:

# Changelog

## 1.1.0 (2026-07-07)

### Added
- New `get_alerts` tool for severe weather alerts
- Support for airport weather codes (ICAO)
- Celsius/Fahrenheit conversion in all tools

### Fixed
- City names with special characters now work correctly
- Improved error messages for invalid API keys

### Changed
- Default forecast days reduced from 5 to 3 (less API usage)

4. Update README

Add new tools, update examples, refresh the description. mcpm reads your README on every publish.

Publishing

# Patch (bug fix)
mcpm-dev publish
# → 1.0.0 → 1.0.1

# Minor (new feature)
mcpm-dev publish --minor
# → 1.0.0 → 1.1.0

# Major (breaking change)
mcpm-dev publish --major
# → 1.0.0 → 2.0.0

What Happens on Publish

1. CLI reads your package.json and README.md
2. New version is pushed to mcpm.dev
3. Old versions remain available (users can pin to them)
4. Users see update notifications: mcpm-dev outdated

Communicating with Users

For Patch Updates

No communication needed. Users get the fix automatically on next update.

For Minor Updates

Update your README. Consider a short post on your tool's mcpm page.

For Major Updates

Warn users before breaking changes:

1. Add deprecation notices in the previous minor version

   // In your tool handler
   if (args.oldParam) {
     console.error("⚠️ 'oldParam' is deprecated. Use 'newParam' instead.");
   }
   

2. Write a migration guide

   ## Migrating from v1 to v2
   
   ### Parameter changes
   - `oldParam` → renamed to `newParam`
   - `city` is now `location` (supports city names AND coordinates)
   
   ### New required config
   - `API_VERSION=2` must be set in env vars
   

3. Keep old versions available
   Users can stay on v1: mcpm-dev add weather-mcp@1.9.0

Release Checklist

Before every publish:

• package.json version updated
• CHANGELOG.md has this version's entries
• README.md reflects current features
• All tests pass: npm test
• Manual test with real MCP client
• Breaking changes have migration guide
• Deprecated features logged with warnings

Rollback Plan

If an update causes issues:

# Revert to previous version
mcpm-dev publish --version 1.0.0

This republishes the old version as the latest. Users can then:

mcpm-dev update weather-mcp

Automating with GitHub Actions

# .github/workflows/publish.yml
name: Publish to mcpm
on:
  push:
    tags:
      - 'v*'

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm ci
      - run: npm test
      - run: npx mcpm-dev publish
        env:
          MCPM_TOKEN: ${{ secrets.MCPM_TOKEN }}

Tag a release on GitHub, and it auto-publishes to mcpm.

Publishing is a conversation with your users. Be thoughtful, be transparent, and keep your changelog honest.

#MCP #Tutorial #Publishing #Versioning #mcpm