Your AI coding agent will happily ship a breaking API change. I built an MCP server to catch it.

Last month I watched Cursor confidently rename a field across an entire API, commit it, and open a PR. Clean diff, tests green, looked great. It had also just broken a mobile client and a partner integration that were still reading the old field name — and neither Cursor nor I noticed until much later.

That's the thing about AI coding agents and APIs: they're fast, they're fearless, and they have zero awareness of your API contract. An agent will drop an endpoint, make a request field required, or change a response type without any sense that a real consumer out there depends on the old shape. The code compiles. Your tests pass (your tests — not the consumer's). The breakage is completely silent until someone downstream feels it, usually in production, usually from an angry message rather than a failing build.

We keep giving agents more power to write API changes and nothing to tell them whether a change is safe to ship. So I built that missing piece as an MCP server.

The gap: there's no "is this safe?" step in the loop

Think about how you'd catch this manually. You'd diff the old and new OpenAPI spec, look for removed endpoints, removed response fields, tightened request contracts, enum narrowing — the classic breaking changes — and decide whether it's safe to merge or whether you need a version bump and a heads-up to consumers.

An agent never does that. It has the code in context, not the contract implications. And "did I just break a consumer?" is exactly the kind of question it should be asking before it hands you a diff.

Enter MCP

If you haven't used it yet: the Model Context Protocol is a standard way to give AI agents tools — little capabilities they can call. Claude, Cursor, and others all speak it. Instead of the agent guessing, it can call a tool and get a real answer.

So the fix is simple to state: give the agent a tool that answers "is this API change safe to ship to my consumers?" — and have it call that before it proposes the change.

That's the hero tool in the MCP server I published (specshield-mcp-server). It's called is_change_safe, and it's a thin wrapper over a deploy-gate check: given the old and new spec, it returns a verdict, a risk level, and the exact reasons.

What it looks like

Take that field rename. You ask the agent something like "rename status to paymentStatus across the Orders API — and check it's safe to ship first." With the tool available, it calls is_change_safe and gets back:

{
  "safeToMerge": false,
  "riskLevel": "CRITICAL",
  "blockingReasons": [
    "Response field 'status' removed from GET /orders/{id}",
    "Response field 'status' removed from GET /orders"
  ],
  "recommendedAction": "Do not merge as-is. Removing 'status' breaks existing consumers — keep it as a deprecated alias, or ship behind a new API version and coordinate migration."
}

Now the agent tells you, before the commit: this is a breaking change, here's who it breaks, here's how to do it safely. The rename that would've sailed through and blown up two weeks later gets caught while you're still typing.

The other tools follow the same idea — all read-only:

• is_change_safe — the deploy gate (above)
• explain_breaking_changes — plain-language impact + suggested migration
• generate_migration_guide — a migration guide for consumers
• generate_release_notes — release notes from the diff
• compare_specs — the raw diff, if you just want everything

Setting it up

It's on npm and the official MCP registry. You'll need an API key (it talks to a backend that runs the actual analysis). Then it's one block of config.

Claude Desktop / Cursor (claude_desktop_config.json or ~/.cursor/mcp.json):

{
  "mcpServers": {
    "specshield": {
      "command": "npx",
      "args": ["-y", "specshield-mcp-server"],
      "env": { "SPECSHIELD_API_KEY": "your_key_here" }
    }
  }
}

Claude Code:

claude mcp add specshield --env SPECSHIELD_API_KEY=your_key_here -- npx -y specshield-mcp-server

Restart the client and the tools show up. Then just ask, in plain English: "here are my old and new openapi specs — is it safe to ship this change to my consumers?"

Being honest about what it is (and isn't)

A few things I want to be straight about, because I hate MCP posts that oversell:

• It's analyze-only. It reads two specs and returns a verdict. It never edits your code, runs commands, or reads files you didn't point it at.
• It doesn't prevent anyone from shipping a breaking change. It makes the risk impossible to miss at the right moment — guardrail, not a lock.
• The breaking-change detection itself isn't magic; tools like oasdiff have done spec diffing for years. What I care about is the decision — "can I deploy this?" — living inside the agent loop instead of in a CI step you see after you've already moved on.

The bigger idea: shift the deploy gate left, into the agent

We spent years moving checks "left" — from production, to CI, to pre-commit hooks. AI agents are a new "left" that most of our safety tooling hasn't caught up to yet. The agent is where the change is authored now, so that's where the "wait, is this safe?" question belongs.

An MCP server turned out to be a surprisingly clean way to do that: the agent already has the two specs in context, it just needed something to ask.

If you want to try it, the package is specshield-mcp-server on npm and the repo is on GitHub. And if you've built MCP tools that add guardrails to agents, I'd genuinely like to hear what you're doing — that "the agent should check before it acts" pattern feels like it has a lot more in it than just API diffs.