willianpinho/mcp-gateway-scan

npm version Glama server License: MIT

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 — 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 (<file:line>), with the value redacted.

---

Install

# one-off
npx mcp-gateway-scan <path>

# or global
pnpm add -g mcp-gateway-scan
mcp-gateway-scan <path>

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:

Verdict	When	Exit
DO-NOT-CONNECT	any S1 (full-compromise-class) dimension is red	1
REVIEW	concrete-or-possible risk (red S2/S3 or any yellow)	1
CONNECT	every dimension green on the static checks	0

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": "<repo or dir>", "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 <path> 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, 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

Dim	Checks for
D1 Tool-access / RBAC	Authorization expressed in prompts; absence of a gateway policy layer
D2 Fail-close	catch/except blocks that return allow/true/ok/pass; missing timeouts
D3 Onboarding / supply chain	:latest, @main, npx -y …@, unpinned images; rewards sha256: / integrity
D4 Observability	Presence/absence of OTel / traceparent / spans; raw prompts in logs
D5 Routing / cost	Missing max_tokens / budget / rate-limit / quota
D6 Secrets / identity	Inline secret literals (location only, value redacted); rewards op:// / vault: / process.env; IDP/OIDC
D7 Prod-readiness	Missing kill-switch / feature-flag, 429 / rate-limit, eval / red-team gate

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.

	This scanner (free, MIT)	Full MCP Gateway Readiness Audit (paid)
Method	static pattern checks	read-only review of your live codebase
Live tests	—	fault-injection (F1–F5), trace verification
Evidence	matched line	per-finding file:line in an evidence index
Output	7-dimension score	cited gap matrix + severity + sequenced 90-day roadmap
Delivery	instant, automated	expert engagement + live review session

Need the full audit? This scanner is a free heuristic wedge. The Provenwright MCP Gateway Readiness 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: [email protected]

License

MIT © Willian Pinho