MCP API Guardian

io.github.petrovicistefanv0.1.1Updated Oct 9, 2026

Local OpenAPI contract and breaking-change checks for AI agents.

VerifiedSTDIODesktop onlyDeveloper ToolsSecurity & Monitoring

Overview

AI-generated overview

Lets an AI coding agent audit OpenAPI 3.0.x/3.1.x specs and compare two versions for breaking contract changes, entirely locally.

What it does
Provides two tools over stdio: audit_openapi checks a parsed OpenAPI document for selected contract errors, references, operation IDs, required path parameters, public operations and risky authentication declarations; compare_openapi diffs a before and after document to detect removed operations, changed operation IDs, added inline required parameters, newly required request bodies, removed response codes and changed authentication requirements. It is a targeted linter rather than a complete OpenAPI validator, and reports state their coverage.
When to use it
Useful when an assistant is editing or reviewing an API specification and you want a quick contract check or a breaking-change diff between two versions. It fits local development workflows where specs are already parsed as JSON objects.
Requirements
Runs locally as a Node.js 22+ process over stdio, typically started with npx mcp-api-guardian; no account, API key or network access is needed for the local server. Specs must be passed as parsed JSON OpenAPI 3.0.x or 3.1.x objects; YAML parsing, filesystem access, external reference fetching and live HTTP probes are not implemented.
Before you install
The local server needs no credentials and keeps documents inside the process. A separate optional hosted path exists: it processes OpenAPI documents on the hosted host, requires an Authorization Bearer key, enforces quotas, and returns 429 when over quota; its control-plane requests carry only product, requestId and units. That hosted path is described as a reference integration, not a published multi-tenant deployment, and successful consumption is not refunded. Warnings are not proof of a…

Installation

In SourceWeft

  1. Open MCP API Guardian 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

MCP API Guardian

Local OpenAPI contract checks for AI coding agents. MVP 0.1.0, no runtime dependencies, Node.js 22+.

Transport: newline-delimited JSON-RPC over stdio, with the initialize-based MCP protocol family through 2025-11-25. The newer 2026-07-28 stateless protocol is not implemented. Test with your target client before deployment. Protocol reference: https://modelcontextprotocol.io/specification/2025-11-25/basic/transports

Install in your AI client

Works with any MCP client over stdio; no account or API key needed for the local server.

Claude Code

sh
claude mcp add api-guardian -- npx -y mcp-api-guardian

Codex CLI

sh
codex mcp add api-guardian -- npx -y mcp-api-guardian

Claude Desktop, Cursor, Windsurf, Cline, Gemini CLI — add to the client's MCP config (claude_desktop_config.json, ~/.cursor/mcp.json, ~/.codeium/windsurf/mcp_config.json, Cline MCP settings, ~/.gemini/settings.json):

json
{  "mcpServers": {    "api-guardian": {      "command": "npx",      "args": [        "-y",        "mcp-api-guardian"      ]    }  }}

VS Code / GitHub Copilot — .vscode/mcp.json:

json
{  "servers": {    "api-guardian": {      "type": "stdio",      "command": "npx",      "args": [        "-y",        "mcp-api-guardian"      ]    }  }}

Zed — settings.json:

json
{  "context_servers": {    "api-guardian": {      "command": "npx",      "args": [        "-y",        "mcp-api-guardian"      ]    }  }}

Run from source

sh
npm testnpm start

Add to an MCP client's configuration, replacing the absolute path:

json
{"mcpServers":{"api-guardian":{"command":"node","args":["/absolute/path/mcp-api-guardian/src/server.js"]}}}

Tools

  • audit_openapi({spec}): checks selected contract errors, references, operation IDs, required path parameters, public operations and risky authentication declarations.
  • compare_openapi({before, after}): detects removed operations, changed operation IDs, added inline required parameters, newly required request bodies, removed response codes and changed authentication requirements.

Pass parsed JSON OpenAPI 3.0.x or 3.1.x documents as objects. YAML parsing, filesystem access, external reference fetching and live HTTP probes are not implemented. No credentials or source documents leave the process.

This is a targeted linter, not a complete OpenAPI validator. Schema compatibility (including request versus response variance), composed schemas and referenced parameter comparisons require a later release. Public endpoints may be intentional; warnings are not proof of a vulnerability. Reports explicitly state coverage.

Packaging

sh
npm run checknpm testnpm pack

Clients can use npx -y mcp-api-guardian.

Hosted path (quotas via control plane)

The local stdio MCP server above stays fully useful without an account or network. Quotas are enforced only by a separate hosted HTTP process that reserves units on mcp-control-plane before running the same analysis core.

sh
# Terminal 1 — control plane (see its README for ADMIN_TOKEN)node --env-file=.env src/server.js   # in mcp-control-plane
# Terminal 2 — hosted api-guardiancp .env.example .env                 # set CONTROL_PLANE_URLnpm run start:hosted

Bootstrap a customer key with the control-plane admin API (POST /v1/admin/accounts, POST /v1/admin/keys). Then:

MethodPathBody
GET/healthLiveness
POST/v1/audit{ "requestId": "scan-1", "units": 1, "spec": { … } }
POST/v1/compare{ "requestId": "diff-1", "before": { … }, "after": { … } }

Customer routes require Authorization: Bearer mcp_…. On success the response includes report and usage. Over quota returns 429 with { "error": "quota_exceeded" } and does not run analysis. Default bind: 127.0.0.1:3100. Production needs an HTTPS reverse proxy.

Privacy: OpenAPI documents are processed on the hosted host only. Control-plane requests carry solely product (api-guardian), requestId, and units — never specs, reports, or credentials. Successful consume has no refund in the control-plane MVP.

This hosted path is a reference integration, not a published multi-tenant deploy. README prices remain hypotheses until billing is live.

Roadmap and commercial model

  1. Add full schema compatibility tests and local reference resolution.
  2. Add explicit opt-in live response validation, target allowlists, limits and secret redaction.
  3. Validate demand with API teams using real release diffs.
  4. Offer managed history, CI integration, shared policies and team reporting as Pro (hosted path above is the quota hook).

A local MIT package cannot reliably enforce paid quotas; those belong to an authenticated hosted service. Keep the useful local tool free.

Source: README.md at commit 93e0bb2

Tools

0
Tool metadata has not been indexed yet.

Version history

1
  1. v0.1.1LatestOct 9, 2026