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.

Tools

| # | 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      # 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 stdio

License

MIT © SpecShield Software Private Limited