MCP Gateway Scan

mcp-gateway-scan

Read-only static scanner for MCP / agent-gateway production-readiness anti-patterns.

Point it at a repo, get a 7-dimension red/yellow/green score in seconds.

Built by the team behind the [Provenwright MCP Gateway Readiness Audit](https://provenwright.com/audit) — a full cited audit with evidence index, scored gap matrix, and 90-day roadmap. Full audit: provenwright.com/audit

npx mcp-gateway-scan ./path/to/your/gateway

It scans your code and config for the failure modes that turn an MCP gateway from a demo into an incident — authorization decided by the model, error handlers that fail _open_, unpinned supply chains, dark traces, unbounded spend, inline secrets, and missing operational levers — and prints exactly where each one lives.

100% read-only. It only _reads_ files. It never executes your code, never makes network calls, and never prints a secret value — for inline-secret hits it reports the location only ( ), with the value redacted.

---

Install

# one-off

npx mcp-gateway-scan

or global

pnpm add -g mcp-gateway-scan mcp-gateway-scan

Requires Node ≥ 18.

Usage

mcp-gateway-scan <path> [options]

Options: --json Machine-readable JSON instead of the terminal report --ci Compact, no-color output for pipelines; exits 1 on any RED --no-color Disable ANSI colors -h, --help Show help -v, --version Print version

Exit codes: 0 no red dimensions 1 one or more red dimensions 2 usage / IO error

"Should I connect to this server?" — the connect verdict

Before you wire a third-party MCP server into an agent that holds real credentials, point connect at it and get a single top-line verdict — CONNECT, REVIEW, or DO-NOT-CONNECT — over the same 7 dimensions, with the single worst finding surfaced first.

# the server's repo checkout

mcp-gateway-scan connect ./some-mcp-server

its MCP client config entry (.mcp.json / claude_desktop_config.json)

mcp-gateway-scan connect ./.mcp.json

its package manifest

mcp-gateway-scan connect ./package.json

The verdict reduces the dimension scores into one decision:

Same scan engine, same --json / --ci flags, same read-only / secret-redaction guarantees — connect only re-frames the output as a connect/no-connect decision. A green CONNECT is a good signal, not a guarantee: a static scan cannot vouch for the publisher or runtime behavior.

Run it inside Claude Code / Cursor (MCP server)

The same package can also run as an MCP server so your agent runs the scan conversationally — just ask it to "scan this repo for gateway-readiness".

Claude Code (one command):

claude mcp add gateway-scan -- npx -y mcp-gateway-scan mcp

Cursor / any MCP client — add to your .mcp.json:

{

"mcpServers": { "gateway-scan": { "command": "npx", "args": ["-y", "mcp-gateway-scan", "mcp"] } } }

Then ask your agent to run the `scan_gateway` tool:

• Input: { "path": " ", "ci": false } (ci optional — adds the CI gate verdict).
• Output: a per-dimension 🟢🟡🔴 summary + the structured result. Read-only; scans only the path you give it; secret values stay redacted (location only, never the value).

Same package, two modes — mcp-gateway-scan mcp is the server (use it from your

agent); the default mcp-gateway-scan is the CLI (run it directly in a terminal

or CI). The mcp subcommand does not change the CLI behavior.

Or find it on Glama

mcp-gateway-scan is listed on the [Glama MCP directory](https://glama.ai/mcp/servers/willianpinho/mcp-gateway-scan), where you can inspect its tool schema, Try it in the browser, or deploy the containerized server straight from the listing. The build spec and release process are documented in docs/glama-release.md.

Example output

  [RED] D2 Fail-close / fail-open posture  S1

Error handlers on the call path return allow/true/ok or pass — the system fails OPEN. A degraded auth/policy check silently becomes 'allow'. Launch blocker. ✗ gateway.ts:23 fail-open on error path return { allowed: true };

[GREEN] D6 Security, secrets & identity S1 No inline secrets; credentials referenced from a manager/env and IDP/OIDC identity wiring is present. ✓ docker-compose.yml:7 secret-manager / env reference DATABASE_URL: op://Production/gateway-db/url

SCORE ┌────────┬──────────────────────────────────────────┬─────────┬──────────┐ │ Dim │ Title │ Status │ Severity │ ├────────┼──────────────────────────────────────────┼─────────┼──────────┤ │ D1 │ Tool-access governance & RBAC │ RED │ S1 │ │ ... │ ... │ ... │ ... │ └────────┴──────────────────────────────────────────┴─────────┴──────────┘

0 green 0 yellow 7 red

Wire it into CI

--ci prints a compact, greppable summary and exits non-zero on any red dimension, so a regression (a new fail-open handler, an unpinned image, a committed secret) fails the build:

# .github/workflows/gateway-readiness.yml

• name: MCP gateway readiness scan run: npx mcp-gateway-scan ./gateway --ci

RED D2 S1 Fail-close / fail-open posture (findings=1) RESULT green=4 yellow=2 red=1 VERDICT FAIL — red dimension(s) present; see findings above.

The 7 dimensions

Each dimension is scored 🟢 green / 🟡 yellow / 🔴 red with a severity tag, plus the matched evidence (file:line). The methodology behind the rubric maps to OWASP Top 10 for LLM Applications, the MCP spec (2025-06-18), and OpenTelemetry GenAI semantic conventions.

Try it on the bundled fixtures

mcp-gateway-scan fixtures/secure      # mostly green

mcp-gateway-scan fixtures/vulnerable # mostly red

The fixtures/vulnerable tree contains only fake, non-functional placeholder secrets (sk-EXAMPLENOTREAL…, AKIAEXAMPLE…) so you can see the redacted-secret output safely.

Accuracy

Every finding is meant to be defensible to a skeptical senior engineer. The scanner distinguishes prompt content (a system-message string / YAML prompt field) from code that merely documents a pattern — so a doc comment quoting rg 'only use|if the user is admin' is not flagged as authorization-in-prompt, while the same words inside a real system prompt are. Comment lines and grep-recipe / regex documentation are suppressed across all dimensions, and "control present" signals are matched in code/config, not prose.

What this is (and isn't)

This is a fast, free heuristic wedge — a static pattern scanner. A green score is a good signal, not a guarantee; a red score is a concrete pointer to fix. It does not run fault-injection, inspect your live IAM/IDP, or read your traces. That depth is what a full MCP Gateway Readiness Audit provides: a cited Gap Matrix and a sequenced 90-day remediation roadmap.

Need the full audit? This scanner is a free heuristic wedge.

The [Provenwright MCP Gateway Readiness Audit](https://provenwright.com/audit) goes deeper:

read-only assessment of your live codebase, per-finding evidence (file + line),

a cited Gap Matrix, and a sequenced 90-day remediation roadmap.

See a sample report: provenwright.com/sample/

Full audit info: provenwright.com/audit

Book a 15-min call: cal.com/willianpinho

Email: me@willianpinho.com

License

MIT © Willian Pinho