SpecShield MCP server
✓ VerifiedAllows AI coding agents to detect breaking API changes and evaluate deployment safety using OpenAPI specifications.
Also known as specshield26/specshield-mcp-server
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 1.0.2
- Last commit
- Aug 16, 2026
- License
- MIT
What is SpecShield MCP?
SpecShield allows AI coding agents to detect breaking API changes and evaluate deployment safety using OpenAPI specifications.
Summary generated from the project's README
About SpecShield MCP server
SpecShield MCP Server acts as a deployment gate for AI coding agents by analyzing OpenAPI specifications to identify breaking changes. It functions as a read-only adapter for the SpecShield backend, allowing developers to evaluate if an API update is safe to ship directly within clients like Claude, Cursor, or Claude Code. Users must provide a SpecShield API key via environment variables to connect the server to the analysis engine.
The server provides several specialized tools including is_change_safe for deployment decisions, explain_breaking_changes for impact analysis, and generate_migration_guide for creating markdown documentation. It also includes compare_specs for raw diffing and risk scoring. For users on the Team+ plan, the run_governance_review tool can check for compliance with rules regarding pagination, security schemes, and versioning. This setup ensures that AI agents can assist in maintaining API stability without ever modifying the underlying source code.
What you can do with it
- 1Evaluate deployment safetyAsk the AI if a specific API modification will break existing consumer integrations before merging.
- 2Analyze breaking changesRequest a detailed explanation of what will break and how developers should migrate to the new version.
- 3Automate release documentationHave the agent create professional release notes for customers or internal stakeholders based on spec differences.
- 4Perform governance auditsCheck a single specification against organizational rules for security schemes and error responses.
Written from the project's README. Every use case is checked against a quote from it.
How to install SpecShield MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall SpecShield MCP in Claude Code
$ claude mcp add --env 'SPECSHIELD_API_KEY=<YOUR_SPECSHIELD_API_KEY>' specshield-mcp-server -- npx -y specshield-mcp-serverInstall SpecShield MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"specshield-mcp-server": {
"command": "npx",
"args": [
"-y",
"specshield-mcp-server"
],
"env": {
"SPECSHIELD_API_KEY": "<YOUR_SPECSHIELD_API_KEY>"
}
}
}
}Install SpecShield MCP in VS Code
.vscode/mcp.json
{
"servers": {
"specshield-mcp-server": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"specshield-mcp-server"
],
"env": {
"SPECSHIELD_API_KEY": "<YOUR_SPECSHIELD_API_KEY>"
}
}
}
}Install SpecShield MCP in VS Code CLI
$ code --add-mcp '{"name":"specshield-mcp-server","type":"stdio","command":"npx","args":["-y","specshield-mcp-server"],"env":{"SPECSHIELD_API_KEY":"<YOUR_SPECSHIELD_API_KEY>"}}'Install SpecShield MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"specshield-mcp-server": {
"command": "npx",
"args": [
"-y",
"specshield-mcp-server"
],
"env": {
"SPECSHIELD_API_KEY": "<YOUR_SPECSHIELD_API_KEY>"
}
}
}
}Install SpecShield MCP in Codex
$ codex mcp add specshield-mcp-server --env 'SPECSHIELD_API_KEY=<YOUR_SPECSHIELD_API_KEY>' -- npx -y specshield-mcp-serverInstall SpecShield MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.specshield-mcp-server] command = "npx" args = ["-y", "specshield-mcp-server"] [mcp_servers.specshield-mcp-server.env] SPECSHIELD_API_KEY = "<YOUR_SPECSHIELD_API_KEY>"
Install SpecShield MCP in Gemini CLI
$ gemini mcp add -s user -e 'SPECSHIELD_API_KEY=<YOUR_SPECSHIELD_API_KEY>' specshield-mcp-server npx -- -y specshield-mcp-serverInstall SpecShield MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"specshield-mcp-server": {
"command": "npx",
"args": [
"-y",
"specshield-mcp-server"
],
"env": {
"SPECSHIELD_API_KEY": "<YOUR_SPECSHIELD_API_KEY>"
}
}
}
}Configuration
SPECSHIELD_API_KEYRequiredSecretSpecShield API key
SPECSHIELD_API_URLBackend base URL
SPECSHIELD_LOG_LEVELdebug|info|warn|error
SPECSHIELD_TIMEOUT_MSPer-request timeout (ms)
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablespecshield26/specshield-mcp-server is public and reachablegithub.com/specshield26/specshield-mcp-server ↗Pass
- Package names this repository as its sourcespecshield-mcp-server names specshield26/specshield-mcp-server as sourcenpmjs.com/package/specshield-mcp-server ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for specshield-mcp-servernpmjs.com/package/specshield-mcp-server/v/1.0.2#provenance ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-08-16github.com/specshield26/specshield-mcp-server ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from specshield-mcp-serverPass
- No critical advisory in the package or its dependencies99 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubSpecShield 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
specshieldCLI runs the same breaking-change andcan-i-deploychecks 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.yamlandv2.yamland 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-Keyheader 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
SpecShield MCP questions
How do I add SpecShield MCP to Claude Code?
Run claude mcp add --env 'SPECSHIELD_API_KEY=<YOUR_SPECSHIELD_API_KEY>' specshield-mcp-server -- npx -y specshield-mcp-server in your terminal. Add --scope user to make it available in every project.
How do I add SpecShield MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Does this server modify my code?
No, all tools are read-only and analyze-only, ensuring your code remains untouched.
Is the governance review tool free?
No, the run_governance_review tool is a paid feature available for Team+ users.