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.
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.
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.
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 migrationgenerate_migration_guide
— a migration guide for consumersgenerate_release_notes
— release notes from the diffcompare_specs
— the raw diff, if you just want everythingIt'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?"
A few things I want to be straight about, because I hate MCP posts that oversell:
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.