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 specshield CLI runs the same breaking-change and can-i-deploy checks in your pipeline (GitHub Action, exit codes). Same job, two entry points: this server for AI agents, the CLI for CI/CD.
| # | Tool | What it answers |
|---|
| 1 | is_change_safe ⭐ | Is this change safe to merge/deploy? Will it break consumers? (safeToMerge + risk + blocking reasons) |
| 2 | explain_breaking_changes | What breaks, developer & consumer impact, suggested migration |
| 3 | generate_migration_guide | Migration guide (markdown) + safe rollout steps |
| 4 | generate_release_notes | Release notes for developer / customer / internal |
| 5 | compare_specs | The raw diff (breaking / additions / modifications / warnings) + risk score |
| 6 | run_governance_review 🔒 | 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.
Install
Requires Node.js ≥ 20 and a SpecShield API key (from
specshield.io/account).
npx -y specshield-mcp-server
Claude 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-server
Cursor
~/.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 |
|---|
SPECSHIELD_API_KEY | yes | — | Your SpecShield API key. Store it as a secret; never commit it. |
SPECSHIELD_API_URL | no | https://api.specshield.io | Backend base URL (override for self-hosted/staging). |
SPECSHIELD_TIMEOUT_MS | no | 30000 | Per-request timeout. |
SPECSHIELD_LOG_LEVEL | no | info | debug | info | warn | error (logs go to stderr). |
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.yaml and v2.yaml and 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-Key header 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
npm test
npm run lint
npm run smoke
npm start
License
MIT © SpecShield Software Private Limited