SpecShield MCP Server
The SpecShield MCP Server acts as an API-change deploy gate, letting you analyze API specification changes to determine if they are safe to ship before they reach consumers. All tools are read-only, accept specs as inline content or file paths, and support OpenAPI and Pact formats.
is_change_safe: The primary tool — returns asafeToMergeverdict, risk level, blocking reasons, and recommended action to determine if an API change will break existing consumers.explain_breaking_changes: Details what breaks and why, including developer/consumer impact and suggested migration steps.generate_migration_guide: Produces a markdown migration guide with safe rollout steps, optionally tailored to a specific language (Java, Node, Python, Go, cURL, or generic).generate_release_notes: Creates markdown release notes grouped by breaking changes, additions, and other changes, customized for developer, customer, or internal audiences.compare_specs: Performs a raw diff between two specs, listing breaking changes, additions, modifications, and warnings along with a risk score and compatibility summary.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@SpecShield MCP Server Is it safe to deploy this API change?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
SpecShield MCP Server
The API-change deploy gate for AI coding agents. Ask "is it safe to ship this API change to my consumers?" right inside Claude, Cursor, and other MCP clients — and catch breaking changes before they reach your consumers.
It's a thin adapter over the SpecShield backend. Every tool is read-only / analyze-only — it never modifies your code.
Why not just diff specs? Plenty of tools (including free ones) list breaking changes. SpecShield's job is the decision: can I deploy this? — the deploy gate is the hero tool here.
⚙️ In CI/CD instead of an agent? The
specshieldCLI runs the same breaking-change andcan-i-deploychecks in your pipeline (GitHub Action, exit codes). Same job, two entry points: this server for AI agents, the CLI for CI/CD.
Tools
# | Tool | What it answers |
1 |
| Is this change safe to merge/deploy? Will it break consumers? ( |
2 |
| What breaks, developer & consumer impact, suggested migration |
3 |
| Migration guide (markdown) + safe rollout steps |
4 |
| Release notes for developer / customer / internal |
5 |
| The raw diff (breaking / additions / modifications / warnings) + risk score |
6 |
| API governance ruleset beyond breaking changes (missing operationId, error responses, security scheme, pagination, versioning…) → located findings + suggested fixes. Paid (Team+) |
Tools 1–5 accept specs inline (baseSpecContent / targetSpecContent) or by path
(baseSpecPath / targetSpecPath). run_governance_review reviews a single spec
(specContent / specPath).
🔒 run_governance_review is a paid feature — a FREE API key returns a
payment_required error. Upgrade at specshield.io/pricing.
Full setup, verification & troubleshooting: docs/mcp-server-setup.md.
Related MCP server: genpark-pull-request-breaking-api-change-sentinel-skill
Install
Requires Node.js ≥ 20 and a SpecShield API key (from specshield.io/account).
npx -y specshield-mcp-serverClaude Desktop
claude_desktop_config.json:
{
"mcpServers": {
"specshield": {
"command": "npx",
"args": ["-y", "specshield-mcp-server"],
"env": { "SPECSHIELD_API_KEY": "ss_your_key_here" }
}
}
}Claude Code
claude mcp add specshield --env SPECSHIELD_API_KEY=ss_your_key_here -- npx -y specshield-mcp-serverCursor
~/.cursor/mcp.json (or the project .cursor/mcp.json):
{
"mcpServers": {
"specshield": {
"command": "npx",
"args": ["-y", "specshield-mcp-server"],
"env": { "SPECSHIELD_API_KEY": "ss_your_key_here" }
}
}
}Configuration
Env var | Required | Default | Purpose |
| yes | — | Your SpecShield API key. Store it as a secret; never commit it. |
| no |
| Backend base URL (override for self-hosted/staging). |
| no |
| Per-request timeout. |
| no |
|
|
Example prompts (lead with the deploy gate)
*"Here are my old and new
openapi.yaml— is it safe to ship this API change to my consumers?"*"Compare
v1.yamlandv2.yamland tell me if I can deploy, and why not.""Explain the breaking changes between these two specs and how consumers should migrate."
"Generate customer-facing release notes for this API change."
Security & privacy
API key required. Sent only as the
X-Api-Keyheader to your configured backend.Read-only / analyze-only. No mutation tools, no shell execution, no arbitrary file access (a spec file is read only when you explicitly pass a path).
No secret or spec logging. The server never logs spec content, API keys, or request bodies; error messages are redacted and machine-readable.
Specs are sent to your configured SpecShield backend for analysis.
Local development
npm install
npm run build # tsc → dist/
npm test # vitest (no network)
npm run lint
npm run smoke # boots the server against a stubbed backend and lists tools
npm start # run the built server over stdioLicense
MIT © SpecShield Software Private Limited
Available Tools
5 toolscompare_specsCompare two API specsARead-only
Compares two API specs and lists breaking changes, additions, modifications, and warnings with a risk score and compatibility summary. For a merge/deploy decision prefer is_change_safe. Analyzes API contract compatibility only; it does NOT modify code.
Inputs: specFormat, baseSpecPath, failOnBreaking, targetSpecPath, +2 more.
explain_breaking_changesExplain the breaking changesARead-only
Explains what breaks in an API spec change and why, with developer impact, likely consumer impact, and suggested migration steps. Analyzes API contract compatibility only; it does NOT modify code.
Inputs: baseSpecPath, targetSpecPath, baseSpecContent, targetSpecContent.
generate_migration_guideGenerate a migration guideARead-only
Generates a migration guide (markdown) and safe rollout steps for the breaking changes in an API spec change. Analyzes API contract compatibility only; it does NOT modify code.
Inputs: language, baseSpecPath, targetSpecPath, baseSpecContent, +1 more.
generate_release_notesGenerate release notesARead-only
Generates release notes (markdown) for an API spec change, grouped into breaking changes, additions, and other changes, tailored to an audience. Analyzes API contract compatibility only; it does NOT modify code.
Inputs: audience, baseSpecPath, targetSpecPath, baseSpecContent, +1 more.
is_change_safeIs this API change safe to ship?ARead-only
THE DEPLOY GATE. Analyzes whether an API spec change is safe to merge/deploy — will it break existing consumers? Returns a safeToMerge verdict, a risk level, the exact blocking reasons, and a recommended action. Use this before merging or releasing an API change to catch breaking changes before they reach your consumers. Analyzes API contract compatibility only; it does NOT modify code.
Inputs: specFormat, environment, baseSpecPath, targetSpecPath, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a clear, distinct purpose: compare_specs provides a full diff, explain_breaking_changes offers detailed impact, generate_migration_guide creates migration steps, generate_release_notes writes release notes, and is_change_safe gives a deploy verdict. No two tools overlap in functionality.
Four tools follow a verb_noun pattern (compare_specs, explain_breaking_changes, generate_migration_guide, generate_release_notes), while is_change_safe uses a different verb_phrase structure. The naming is largely consistent and readable, but the one deviation prevents a perfect score.
With 5 tools covering the core workflow of API spec change analysis—from comparison to safety check to documentation generation—the count is well-scoped and appropriate for the server's focused purpose.
The tool set covers the complete lifecycle for API spec change management: comparing specs, explaining breaking changes, generating migration guides and release notes, and providing a safety gate for deployment. No obvious gaps given the server's stated role of analysis without modification.
Maintenance
Related MCP Connectors
Real-time API status & breaking-change oracle for AI agents
Read-only AI coding tools for change verification, release readiness, capacity, and guidance.
Detect breaking changes, generate changelogs, diff, and validate OpenAPI specs.
Scores how well AI agents will use your API, 0-100, from its OpenAPI spec. Free and read-only.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI clients to validate OpenAPI specs, compare versions, detect breaking changes, and generate changelogs.4MIT
- FlicenseNot gradedqualityBmaintenanceAnalyzes Git pull request diffs to detect breaking REST and GraphQL API schema changes, providing deterministic AST-level code review and breaking change alerts for CI/CD workflows.8-
- AlicenseBqualityBmaintenanceLocal OpenAPI contract checks and breaking-change detection between spec versions for AI coding agents.2274 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables agents to analyze OpenAPI contracts for deterministic integration risks, plan auth, sync, action, and webhook candidates, and diff contract versions for likely breaking changes through read-only tools.MIT