SpecShield MCP Server

The API-change deploy gate for AI coding agents. Ask "is it safe to ship thisAPI 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 toolis read-only / analyze-only — it never modifies your code.

Why not just diff specs? Plenty of tools (including free ones) list breakingchanges. SpecShield's job is the decision: can I deploy this? — the deploygate 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 apayment_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 (fromspecshield.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 arbitraryfile 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, orrequest 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

SpecShield MCP Server