“So it happened, Scott. An MCP server I use in one of my workflows shipped a breaking API change, and my entire workflow broke.”

The False Promise of Dynamic Discovery

Remember when they sold you on the dream? “Oh, you think you’re a genius with your auto-discovering, fully dynamic MCP server, huh? Add a new tool! Change a description! No updates needed!”

It sounded so cool. Right up until someone writes a prompt depending on that tool, and “someone” decides to rename it…

Boom.

Your entire workflow is now a smoking crater.

The MCP Gold Rush

Everybody wants to provide an MCP server now, and for good reason. It’s unlocking systems and data, creating a relatively low-friction way to integrate them into AI workflows. For the nerds among us, it’s like getting an API without spending days pouring over documentation just to make something simple work. It’s a powerful construct.

But don’t forget Uncle Ben: with great power comes great responsibility.

Lessons from the Golden Era

Luckily, those of us who were around in the “Golden Era of REST APIs” remember sitting on barstools, debating the finer points of API versioning strategies. While I’m not here to write the obituary for REST APIs in an MCP era (you can read that elsewhere), let’s recall what made a good REST API versioning strategy.

The Ten Commandments of API Versioning

1. Thou Shalt Version Your API from Day One Start with versioning even if you think your API is “simple” or “internal only.” Adding versioning later is exponentially harder than building it in from the start.

2. Thou Shalt Use Semantic Versioning Follow semantic versioning principles: MAJOR.MINOR.PATCH. Breaking changes require major version bumps, new backwards-compatible features warrant minor bumps, and bug fixes get patch bumps.

3. Thou Shalt Include Version in the URL or Header Choose one approach and stick with it:

  • URL versioning: /api/v1/users
  • Header versioning: Accept: application/vnd.api+json; version=1

4. Thou Shalt Never Break Backwards Compatibility in Minor Versions Adding new fields or endpoints is fine. Removing fields, changing data types, or altering behavior breaks trust and systems.

5. Thou Shalt Deprecate Gracefully Provide clear deprecation notices with:

  • Timeline for sunsetting (minimum 6-12 months)
  • Migration guides
  • Deprecation headers in responses
  • Regular communication to consumers

6. Thou Shalt Support Multiple Versions Simultaneously Run at least 2-3 major versions concurrently. This gives consumers time to migrate without forcing emergency updates.

7. Thou Shalt Document Version Differences Clearly Maintain comprehensive changelogs and migration guides. Each version should have clear documentation about what changed and how to adapt.

8. Thou Shalt Version Your SDKs and Client Libraries Keep SDK versions aligned with API versions. Make it obvious which SDK version works with which API version.

9. Thou Shalt Test Version Compatibility Maintain test suites for each supported version. Test that old clients still work correctly with new API deployments.

10. Thou Shalt Plan Your Versioning Strategy Before Implementation Decide upfront:

  • How you’ll handle versioning (URL, header, query parameter)
  • How long you’ll support old versions
  • How you’ll communicate changes
  • What constitutes a breaking change in your context

The MCP Versioning Dilemma

So how is this supposed to work in an MCP world?

Frankly, this needs to be addressed at the MCP framework level. Right now, we’re basically handing clients URLs and telling them to figure it out—great for onboarding, terrible for server developers. We need a solution that works beyond the “chat with an AI” use case.

But until that framework-level solution arrives, here are three strategies based on my personal battle scars:

Strategy #1: Just Don’t Break Your API

Easy, right? Just don’t do it.

You can ship incremental improvements, but you must maintain backwards compatibility. If you add a parameter, ensure it has a sensible default so that a client with hard-coded “Use this tool with X params” doesn’t break.

Must Have: Tests that reflect the parameters from prior versions of the server.

Strategy #2: Catch Breaking Changes Early, Version Your Tools

If you must break an API in your MCP server, catch it with a pre-commit hook first. Bad dog! No breaking changes for you!

If you absolutely NEED to do this, create a new version of the tool and update the old one with a deprecation warning. Yes, this might confuse an AI. But users can disable the old tool on their side, so it’s not as catastrophic as you might think.

Still sounds like a lot of work? Maybe just make it backward compatible instead.

Strategy #3: Implement Graceful Deprecation

When you create a new tool version, you must communicate that users should consider the newer version. This means:

  • Append deprecation warnings to tool responses
  • Update the tool description itself
  • Track how often the old version is invoked
  • Set a clear sunset date

In theory, the client will start picking up the new version automatically (happy path!). Otherwise, it’ll likely see that deprecation warning and pass it through to your user.

Pro tip: Don’t rely solely on AI to communicate these changes. Set up email notifications for deprecated tool usage—you have no idea how that warning will bubble up to the user through the AI layer.

For structured outputs, include a deprecations or warnings field in your payload.

The New Reality: Your Users Aren’t Developers

Here’s the paradigm shift you need to internalize: Your APIs are no longer being used by some backend developer who grudgingly puts up with your breaking changes, lack of documentation, and inadequate changelog.

It’s the actual end user incorporating your data into their workflow.

Developers were the kingmakers you once had to court while building APIs. Now YOU’RE the developer, and you need to build an MCP server worthy of your kingdom.

The stakes are higher. The tolerance for breaking changes is lower. And the need for thoughtful versioning strategies has never been more critical.

Welcome to the brave new world of MCP servers. May your versions be semantic and your breaking changes be few.