Specshield Mcp Server

io.github.specshield26Published by GitHub account specshield26v1.0.2Updated 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

Lets an AI coding agent check whether an API spec change is safe to deploy, and explains breaking changes and migration steps.

What you can do
A read-only adapter to the SpecShield backend that answers deploy-gate questions about API changes. Its main tool, is_change_safe, reports whether a change is safe to merge plus risk and blocking reasons. Other tools explain breaking changes, generate migration guides and release notes, compare two specs, and run a paid governance review against an API ruleset. Specs can be passed inline or by file path.
When to use it
Use it when an assistant is reviewing an OpenAPI or similar API change and you want a deploy decision rather than a raw diff. It fits pre-merge and pre-release checks in an agent workflow; the same checks are available as a CLI for CI/CD pipelines.
Requirements
Runs locally over stdio via npx, so Node.js 20 or newer is needed. A SpecShield API key is required in SPECSHIELD_API_KEY; optional settings are SPECSHIELD_API_URL, SPECSHIELD_TIMEOUT_MS and SPECSHIELD_LOG_LEVEL. Network access to the configured backend is required, and the governance review tool needs a paid plan.
Before you install
The API key in SPECSHIELD_API_KEY is sent as the X-Api-Key header to the configured backend, so keep it secret and never commit it. Spec content passed to the tools is sent to that backend for analysis. The governance review tool is paid and returns a payment_required error with a free key. Tools are described as read-only and analyze-only, with no mutation or shell execution.

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.0.2LatestSep 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