{"slug": "your-ai-coding-agent-will-happily-ship-a-breaking-api-change-i-built-an-mcp-to", "title": "Your AI coding agent will happily ship a breaking API change. I built an MCP server to catch it.", "summary": "A developer built an MCP server called SpecShield that gives AI coding agents the ability to check whether an API change is safe to ship before proposing it. The tool catches breaking changes like removed fields or tightened contracts that agents would otherwise silently introduce, preventing downstream breakage in production.", "body_md": "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.\n\nThat'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.\n\nWe 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.\n\nThink 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.\n\nAn 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.\n\nIf you haven't used it yet: the [Model Context Protocol](https://modelcontextprotocol.io) 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.\n\nSo 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.\n\nThat's the hero tool in the MCP server I published (`specshield-mcp-server`\n\n). It's called `is_change_safe`\n\n, 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.\n\nTake 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\n\n`is_change_safe`\n\nand gets back:\n\n```\n{\n  \"safeToMerge\": false,\n  \"riskLevel\": \"CRITICAL\",\n  \"blockingReasons\": [\n    \"Response field 'status' removed from GET /orders/{id}\",\n    \"Response field 'status' removed from GET /orders\"\n  ],\n  \"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.\"\n}\n```\n\nNow 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.\n\nThe other tools follow the same idea — all read-only:\n\n`is_change_safe`\n\n— the deploy gate (above)`explain_breaking_changes`\n\n— plain-language impact + suggested migration`generate_migration_guide`\n\n— a migration guide for consumers`generate_release_notes`\n\n— release notes from the diff`compare_specs`\n\n— the raw diff, if you just want everythingIt's on npm and the [official MCP registry](https://registry.modelcontextprotocol.io). You'll need an API key (it talks to a backend that runs the actual analysis). Then it's one block of config.\n\n**Claude Desktop / Cursor** (`claude_desktop_config.json`\n\nor `~/.cursor/mcp.json`\n\n):\n\n```\n{\n  \"mcpServers\": {\n    \"specshield\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"specshield-mcp-server\"],\n      \"env\": { \"SPECSHIELD_API_KEY\": \"your_key_here\" }\n    }\n  }\n}\n```\n\n**Claude Code:**\n\n```\nclaude mcp add specshield --env SPECSHIELD_API_KEY=your_key_here -- npx -y specshield-mcp-server\n```\n\nRestart 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?\"*\n\nA few things I want to be straight about, because I hate MCP posts that oversell:\n\nWe 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.\n\nAn 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.\n\nIf you want to try it, the package is `specshield-mcp-server`\n\non npm and the repo is [on GitHub](https://github.com/specshield26/specshield-mcp-server). 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.", "url": "https://wpnews.pro/news/your-ai-coding-agent-will-happily-ship-a-breaking-api-change-i-built-an-mcp-to", "canonical_source": "https://dev.to/deepaksatyam/your-ai-coding-agent-will-happily-ship-a-breaking-api-change-i-built-an-mcp-server-to-catch-it-5dal", "published_at": "2026-07-10 18:40:53+00:00", "updated_at": "2026-07-10 19:17:23.919234+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "ai-safety"], "entities": ["SpecShield", "Cursor", "Claude", "Model Context Protocol", "OpenAPI"], "alternates": {"html": "https://wpnews.pro/news/your-ai-coding-agent-will-happily-ship-a-breaking-api-change-i-built-an-mcp-to", "markdown": "https://wpnews.pro/news/your-ai-coding-agent-will-happily-ship-a-breaking-api-change-i-built-an-mcp-to.md", "text": "https://wpnews.pro/news/your-ai-coding-agent-will-happily-ship-a-breaking-api-change-i-built-an-mcp-to.txt", "jsonld": "https://wpnews.pro/news/your-ai-coding-agent-will-happily-ship-a-breaking-api-change-i-built-an-mcp-to.jsonld"}}