Specshield Mcp Server

io.github.specshield-ioPublished by GitHub account specshield-iov1.1.1Updated Oct 24, 2026

The API-change deploy gate for AI coding agents. Read-only breaking-change detection.

VerifiedSTDIODesktop onlyDeveloper ToolsSecurity & Monitoring

Overview

AI-generated overview

Read-only MCP server that checks whether an OpenAPI spec change is safe to deploy, explaining breaking changes and drafting migration guides and release notes.

What you can do
  • Decide whether an API change is safe to merge or deploy, with risk and blocking reasons
  • Explain breaking changes, their developer and consumer impact, and suggested migration
  • Generate migration guides with safe rollout steps and release notes for developer, customer or internal audiences
  • Compare two specs to get the raw diff of breaking changes, additions, modifications and warnings plus a risk score
  • Run an API governance ruleset review on a single spec and get located findings with suggested fixes
When to use it
Use it when an assistant is helping with API changes and you need a go/no-go answer before shipping, or want consumer-facing explanations, migration steps and release notes generated from two spec versions.
Requirements
Runs locally over stdio via npx, requiring Node.js 20 or newer. A SpecShield API key is required in SPECSHIELD_API_KEY. Optional settings: SPECSHIELD_API_URL (backend base URL, default api.specshield.io), SPECSHIELD_TIMEOUT_MS and SPECSHIELD_LOG_LEVEL. Network access to the backend is needed.
Before you install
Specs you pass inline or by path are sent to the configured SpecShield backend for analysis, so avoid confidential schemas unless that is acceptable. The API key is sent as the X-Api-Key header and should be stored as a secret, not committed. The governance review tool is paid and returns a payment_required error with a free key. Tools are read-only, but a spec file is read when you pass a path.

Installation

In SourceWeft

  1. Open Specshield Mcp Server in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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

#ToolWhat it answers
1is_change_safe ⭐Is this change safe to merge/deploy? Will it break consumers? (safeToMerge + risk + blocking reasons)
2explain_breaking_changesWhat breaks, developer & consumer impact, suggested migration
3generate_migration_guideMigration guide (markdown) + safe rollout steps
4generate_release_notesRelease notes for developer / customer / internal
5compare_specsThe raw diff (breaking / additions / modifications / warnings) + risk score
6run_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).

bash
npx -y specshield-mcp-server

Claude Desktop

claude_desktop_config.json:

json
{  "mcpServers": {    "specshield": {      "command": "npx",      "args": ["-y", "specshield-mcp-server"],      "env": { "SPECSHIELD_API_KEY": "ss_your_key_here" }    }  }}

Claude Code

bash
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):

json
{  "mcpServers": {    "specshield": {      "command": "npx",      "args": ["-y", "specshield-mcp-server"],      "env": { "SPECSHIELD_API_KEY": "ss_your_key_here" }    }  }}

Configuration

Env varRequiredDefaultPurpose
SPECSHIELD_API_KEYyes—Your SpecShield API key. Store it as a secret; never commit it.
SPECSHIELD_API_URLnohttps://api.specshield.ioBackend base URL (override for self-hosted/staging).
SPECSHIELD_TIMEOUT_MSno30000Per-request timeout.
SPECSHIELD_LOG_LEVELnoinfodebug | 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

bash
npm installnpm run build      # tsc → dist/npm test           # vitest (no network)npm run lintnpm run smoke      # boots the server against a stubbed backend and lists toolsnpm start          # run the built server over stdio

License

MIT © SpecShield Software Private Limited

Source: README.md at commit f69c1bb

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v1.1.1LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts