Skip to main content
Glama
specshield-io

SpecShield MCP Server

by specshield-io
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

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: swagger-mcp

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
specFormatNo
baseSpecPathNoPath to the base (old) spec file.
failOnBreakingNoIf true, the header flags when any breaking change is present.
targetSpecPathNoPath to the target (new) spec file.
baseSpecContentNoInline base (old) spec content.
targetSpecContentNoInline target (new) spec content.

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds that the tool 'does NOT modify code' and 'analyzes API contract compatibility only,' which is consistent but slightly redundant. No contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences: first defines the function, second gives usage guidance. No wasted words, front-loaded with key information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite no output schema, the description lists the output components (breaking changes, additions, modifications, warnings, risk score, compatibility summary). Parameters are well-documented in the input schema. All necessary context is present for correct tool invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 83% (5 of 6 parameters have descriptions). The tool description does not add any additional parameter details beyond what the schema provides, so it meets the baseline for high coverage but does not enhance understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool compares two API specs and lists breaking changes, additions, modifications, and warnings with a risk score and compatibility summary. It also distinguishes from sibling tool 'is_change_safe' by noting that for merge/deploy decisions the latter is preferred.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear guidance: 'For a merge/deploy decision prefer is_change_safe.' This tells the agent when to use this tool versus an alternative, and it also clarifies that the tool analyzes but does not modify code.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
baseSpecPathNoPath to the base (old) spec file.
targetSpecPathNoPath to the target (new) spec file.
baseSpecContentNoInline base (old) spec content.
targetSpecContentNoInline target (new) spec content.

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnlyHint and non-destructive. The description adds that the tool analyzes compatibility only and returns impact and migration steps, providing useful context beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with purpose, no wasted words. Concisely conveys what the tool does and its constraints.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description explains return content (developer impact, consumer impact, migration steps). It could mention input constraints like required parameter combinations, but overall adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and each parameter has a clear description. The description does not add additional meaning beyond what the schema provides, so baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Explains what breaks in an API spec change and why' and lists specific outputs. It also distinguishes from siblings by noting it does not modify code.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for analyzing API contract compatibility and explicitly states it does not modify code, but lacks explicit guidance on when to choose this over siblings like compare_specs or generate_migration_guide.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
languageNo
baseSpecPathNoPath to the base (old) spec file.
targetSpecPathNoPath to the target (new) spec file.
baseSpecContentNoInline base (old) spec content.
targetSpecContentNoInline target (new) spec content.

TDQS

A3.8/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds clarity by stating it 'analyzes API contract compatibility only' and 'does NOT modify code', which reinforces the non-destructive nature and provides additional behavioral context beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences long, front-loaded with the key purpose, and contains no unnecessary words. Every sentence contributes to understanding the tool's function and constraints.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that there is no output schema, the description conveys that the output is a markdown guide and safe rollout steps. It also clarifies the scope (API contract compatibility only). This is sufficient for a tool with moderate complexity. A higher score would require more detail on parameter relationships or output structure.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is high (80%), so the baseline is 3. The description does not add extra meaning to the parameters; it does not explain when to use file paths versus inline content. The language enum is mentioned but not elaborated. The description adds marginal value over the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool generates a migration guide (markdown) and safe rollout steps for breaking changes in an API spec change. It distinguishes itself from siblings like compare_specs or explain_breaking_changes by specifying the output format and the focus on safe rollout steps.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not provide explicit guidance on when to use this tool versus its siblings. It does not mention prerequisites, alternatives, or when not to use it, leaving the agent to infer usage context from the purpose alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
audienceNo
baseSpecPathNoPath to the base (old) spec file.
targetSpecPathNoPath to the target (new) spec file.
baseSpecContentNoInline base (old) spec content.
targetSpecContentNoInline target (new) spec content.

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint=true and destructiveHint=false. Description reinforces no code modification and adds scope (API contracts only). This is consistent and adds context beyond annotations, though it could mention openWorldHint (e.g., no side effects besides reading).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence of 29 words, front-loaded with action and outcome. No unnecessary details, every part adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only tool with 5 parameters, high schema coverage, and no output schema, the description adequately explains output (markdown, grouped) and purpose. It could mention that output is returned as markdown string, but overall sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 80% (4/5 parameters documented). The description does not add further explanation beyond what the schema provides, such as clarifying the 'audience' enum values. Baseline 3 is appropriate as schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool generates release notes in markdown from API spec changes, grouped into breaking/additions/other, tailored to audience. It explicitly says it does not modify code, distinguishing it from sibling tools like compare_specs or generate_migration_guide.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Description states it analyzes API contract compatibility only and does not modify code, providing implicit guidance on when to use (for release notes) and when not (for actual code changes). However, it does not explicitly name alternative tools or provide when-not-to-use conditions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
specFormatNo
environmentNoOptional target environment, e.g. staging or production.
baseSpecPathNoPath to the base (old) spec file.
targetSpecPathNoPath to the target (new) spec file.
baseSpecContentNoInline base (old) spec content.
targetSpecContentNoInline target (new) spec content.

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, indicating a safe, read-only operation. The description adds value by stating it analyzes API contract compatibility only and returns a verdict, risk level, reasons, and action. It does not contradict annotations and provides useful context beyond them.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is highly concise, front-loading the core purpose ('THE DEPLOY GATE') and then succinctly covering what it does, what it returns, when to use it, and what it does not do. Every sentence serves a clear function with no waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description explains the return values (verdict, risk level, reasons, action) adequately since there is no output schema. The parameters are well-documented in the schema. Sibling tools are listed but not explicitly differentiated. Overall, the context is complete for the tool's intended use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 6 parameters with 83% description coverage, so the schema already documents most parameters well. The tool description does not add additional meaning or syntax details beyond what the schema provides. Baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it is a deploy gate that analyzes API spec changes for safety, and it lists the specific outputs (safeToMerge verdict, risk level, etc.). However, it does not explicitly differentiate itself from siblings like compare_specs or explain_breaking_changes, which could cause confusion about when to use this tool over others.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says 'Use this before merging or releasing an API change,' providing clear when-to-use guidance. It also states it does not modify code, implying a read-only analysis. However, it does not mention when not to use it or alternative tools for different needs.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.2/5.0
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

ActivityMaintained
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/specshield-io/specshield-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server