Skip to main content
Glama
SpecShield MCP Server

SpecShield MCP Server

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.

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

Available Tools

5 tools
compare_specsCompare two API specsA
Read-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 changesA
Read-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 guideA
Read-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 notesA
Read-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?A
Read-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

    A4.2/5.0

    Scored across 5 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers