Managing MCP Tool Versions Like a Pro

MCP tools evolve. New features, bug fixes, breaking changes. This tutorial covers version management on mcpm.

Understanding MCP Versioning

mcpm follows semantic versioning (semver):

1.2.3
│ │ │
│ │ └─ Patch: bug fixes, no behavior change
│ └─── Minor: new features, backward compatible
└───── Major: breaking changes

Checking Your Installed Versions

mcpm-dev list

Output:

weather-mcp        v2.1.0
database-explorer  v1.5.2
github-assistant   v0.9.1
slack-bot          v3.0.0

Checking for Updates

mcpm-dev outdated

Output:

Package             Current  Latest  Type
weather-mcp         2.1.0    2.1.1   patch
database-explorer   1.5.2    2.0.0   major ⚠️
github-assistant    0.9.1    0.9.1   up to date
slack-bot           3.0.0    3.1.0   minor

Updating Tools

Update Everything (Safe)

mcpm-dev update

This updates all tools to their latest compatible version (patch and minor bumps only — no breaking changes).

Update a Specific Tool

mcpm-dev update weather-mcp

Force Update (Including Major)

mcpm-dev update database-explorer --force

Use with caution — major versions may break your agent workflows.

Pinning Versions

Need stability? Pin a specific version:

mcpm-dev add weather-mcp@2.1.0

Or in your project's .mcpmrc:

{
  "packages": {
    "weather-mcp": "2.1.0",
    "database-explorer": "~1.5.0",
    "github-assistant": "^0.9.0"
  }
}

Version ranges:

• 2.1.0 — exact version only
• ~1.5.0 — patch updates (1.5.x)
• ^0.9.0 — minor updates (0.x.x)
• * — always latest (not recommended)

Handling Breaking Changes

When a tool has a major update:

1. Read the Changelog

mcpm-dev info database-explorer --changelog

2. Test in Isolation

Update in a test environment first:

# Test the new version
npx -y database-explorer@2.0.0

3. Check Your Agent Configs

If the tool's API changed, update your agent prompts and configurations.

4. Update Gradually

mcpm-dev update database-explorer --force
# Test thoroughly
# Then update the rest

Rolling Back

mcpm-dev update weather-mcp@2.1.0

This downgrades (or upgrades) to the specified version.

Automating Updates

Add to CI/CD:

# .github/workflows/mcp-updates.yml
- name: Check MCP updates
  run: |
    mcpm-dev outdated --json > outdated.json
    # Alert if major updates available

Best Practices

1. Pin in production — exact versions for reliability
2. Test updates — don't blindly update all
3. Read changelogs — before every major bump
4. Automate patch updates — they're safe
5. Commit .mcpmrc — version control your tool dependencies

Version management isn't glamorous, but it keeps your AI agents reliable.

#MCP #Tutorial #Versioning #mcpm #DevOps