← Back to Blog
tutorialversioningmaintenance

Managing MCP Tool Versions Like a Pro

Understand semver in MCP tools, upgrade safely, pin versions, and handle breaking changes with confidence.

·3 min read·xapable

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:

<span class="hljs-punctuation">{</span>
  <span class="hljs-attr">&quot;packages&quot;</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">&quot;weather-mcp&quot;</span><span class="hljs-punctuation">:</span> <span class="hljs-string">&quot;2.1.0&quot;</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">&quot;database-explorer&quot;</span><span class="hljs-punctuation">:</span> <span class="hljs-string">&quot;~1.5.0&quot;</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">&quot;github-assistant&quot;</span><span class="hljs-punctuation">:</span> <span class="hljs-string">&quot;^0.9.0&quot;</span>
  <span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">}</span>

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:

<span class="hljs-comment"># Test the new version</span>
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
<span class="hljs-comment"># Test thoroughly</span>
<span class="hljs-comment"># Then update the rest</span>

Rolling Back

mcpm-dev update weather-mcp@2.1.0

This downgrades (or upgrades) to the specified version.

Automating Updates

Add to CI/CD:

<span class="hljs-comment"># .github/workflows/mcp-updates.yml</span>
<span class="hljs-bullet">-</span> <span class="hljs-attr">name:</span> <span class="hljs-string">Check</span> <span class="hljs-string">MCP</span> <span class="hljs-string">updates</span>
  <span class="hljs-attr">run:</span> <span class="hljs-string">|
    mcpm-dev outdated --json &gt; outdated.json
    # Alert if major updates available</span>

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

← Back to all posts