{
  "markdown": "# mcp-gateway-scan\n\n[![npm version](https://img.shields.io/npm/v/mcp-gateway-scan.svg)](https://www.npmjs.com/package/mcp-gateway-scan)\n[![Glama server](https://glama.ai/mcp/servers/willianpinho/mcp-gateway-scan/badges/score.svg)](https://glama.ai/mcp/servers/willianpinho/mcp-gateway-scan)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n> Read-only static scanner for **MCP / agent-gateway production-readiness anti-patterns.**\n> Point it at a repo, get a 7-dimension red/yellow/green score in seconds.\n\nBuilt by the team behind the **[Provenwright MCP Gateway Readiness Audit](https://provenwright.com/audit)** —\na full cited audit with evidence index, scored gap matrix, and 90-day roadmap.\nFull audit: [provenwright.com/audit](https://provenwright.com/audit)\n\n```bash\nnpx mcp-gateway-scan ./path/to/your/gateway\n```\n\nIt scans your code and config for the failure modes that turn an MCP gateway from a demo\ninto an incident — authorization decided by the model, error handlers that fail _open_,\nunpinned supply chains, dark traces, unbounded spend, inline secrets, and missing\noperational levers — and prints exactly where each one lives.\n\n**100% read-only.** It only _reads_ files. It never executes your code, never makes network\ncalls, and **never prints a secret value** — for inline-secret hits it reports the location\nonly (`<file:line>`), with the value redacted.\n\n---\n\n## Install\n\n```bash\n# one-off\nnpx mcp-gateway-scan <path>\n\n# or global\npnpm add -g mcp-gateway-scan\nmcp-gateway-scan <path>\n```\n\nRequires Node ≥ 18.\n\n## Usage\n\n```\nmcp-gateway-scan <path> [options]\n\nOptions:\n  --json          Machine-readable JSON instead of the terminal report\n  --ci            Compact, no-color output for pipelines; exits 1 on any RED\n  --no-color      Disable ANSI colors\n  -h, --help      Show help\n  -v, --version   Print version\n\nExit codes:\n  0  no red dimensions\n  1  one or more red dimensions\n  2  usage / IO error\n```\n\n## \"Should I connect to this server?\" — the connect verdict\n\nBefore you wire a **third-party** MCP server into an agent that holds real credentials,\npoint `connect` at it and get a single top-line verdict — **CONNECT**, **REVIEW**, or\n**DO-NOT-CONNECT** — over the same 7 dimensions, with the single worst finding surfaced first.\n\n```bash\n# the server's repo checkout\nmcp-gateway-scan connect ./some-mcp-server\n\n# its MCP client config entry (.mcp.json / claude_desktop_config.json)\nmcp-gateway-scan connect ./.mcp.json\n\n# its package manifest\nmcp-gateway-scan connect ./package.json\n```\n\nThe verdict reduces the dimension scores into one decision:\n\n| Verdict            | When                                                | Exit |\n| ------------------ | --------------------------------------------------- | ---- |\n| **DO-NOT-CONNECT** | any **S1** (full-compromise-class) dimension is red | 1    |\n| **REVIEW**         | concrete-or-possible risk (red S2/S3 or any yellow) | 1    |\n| **CONNECT**        | every dimension green on the static checks          | 0    |\n\nSame scan engine, same `--json` / `--ci` flags, same read-only / secret-redaction guarantees —\n`connect` only re-frames the output as a connect/no-connect decision. A green CONNECT is a good\nsignal, not a guarantee: a static scan cannot vouch for the publisher or runtime behavior.\n\n## Run it inside Claude Code / Cursor (MCP server)\n\nThe same package can also run as an **MCP server** so your agent runs the scan\nconversationally — just ask it to \"scan this repo for gateway-readiness\".\n\n**Claude Code** (one command):\n\n```bash\nclaude mcp add gateway-scan -- npx -y mcp-gateway-scan mcp\n```\n\n**Cursor / any MCP client** — add to your `.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"gateway-scan\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-gateway-scan\", \"mcp\"]\n    }\n  }\n}\n```\n\nThen ask your agent to run the **`scan_gateway`** tool:\n\n- Input: `{ \"path\": \"<repo or dir>\", \"ci\": false }` (`ci` optional — adds the CI gate verdict).\n- Output: a per-dimension 🟢🟡🔴 summary + the structured result. Read-only; scans\n  only the path you give it; secret values stay redacted (location only, never the value).\n\n> Same package, two modes — `mcp-gateway-scan mcp` is **the server** (use it from your\n> agent); the default `mcp-gateway-scan <path>` is **the CLI** (run it directly in a terminal\n> or CI). The `mcp` subcommand does not change the CLI behavior.\n\n### Or find it on Glama\n\n`mcp-gateway-scan` is listed on the **[Glama MCP directory](https://glama.ai/mcp/servers/willianpinho/mcp-gateway-scan)**,\nwhere you can inspect its tool schema, **Try it in the browser**, or deploy the containerized\nserver straight from the listing. The build spec and release process are documented in\n[`docs/glama-release.md`](docs/glama-release.md).\n\n## Example output\n\n```\n  [RED] D2 Fail-close / fail-open posture  S1\n        Error handlers on the call path return allow/true/ok or pass — the\n        system fails OPEN. A degraded auth/policy check silently becomes\n        'allow'. Launch blocker.\n        ✗ gateway.ts:23  fail-open on error path  return { allowed: true };\n\n  [GREEN] D6 Security, secrets & identity  S1\n        No inline secrets; credentials referenced from a manager/env and\n        IDP/OIDC identity wiring is present.\n        ✓ docker-compose.yml:7  secret-manager / env reference  DATABASE_URL: op://Production/gateway-db/url\n\n  SCORE\n  ┌────────┬──────────────────────────────────────────┬─────────┬──────────┐\n  │ Dim    │ Title                                      │ Status  │ Severity │\n  ├────────┼──────────────────────────────────────────┼─────────┼──────────┤\n  │ D1     │ Tool-access governance & RBAC              │ RED     │ S1       │\n  │ ...    │ ...                                        │ ...     │ ...      │\n  └────────┴──────────────────────────────────────────┴─────────┴──────────┘\n\n  0 green  0 yellow  7 red\n```\n\n## Wire it into CI\n\n`--ci` prints a compact, greppable summary and **exits non-zero on any red dimension**, so a\nregression (a new fail-open handler, an unpinned image, a committed secret) fails the build:\n\n```yaml\n# .github/workflows/gateway-readiness.yml\n- name: MCP gateway readiness scan\n  run: npx mcp-gateway-scan ./gateway --ci\n```\n\n```\nRED    D2 S1 Fail-close / fail-open posture (findings=1)\nRESULT green=4 yellow=2 red=1\nVERDICT FAIL — red dimension(s) present; see findings above.\n```\n\n## The 7 dimensions\n\n| Dim                              | Checks for                                                                                                       |\n| -------------------------------- | ---------------------------------------------------------------------------------------------------------------- |\n| **D1** Tool-access / RBAC        | Authorization expressed in prompts; absence of a gateway policy layer                                            |\n| **D2** Fail-close                | `catch`/`except` blocks that return `allow`/`true`/`ok`/`pass`; missing timeouts                                 |\n| **D3** Onboarding / supply chain | `:latest`, `@main`, `npx -y …@`, unpinned images; rewards `sha256:` / `integrity`                                |\n| **D4** Observability             | Presence/absence of OTel / `traceparent` / spans; raw prompts in logs                                            |\n| **D5** Routing / cost            | Missing `max_tokens` / budget / rate-limit / quota                                                               |\n| **D6** Secrets / identity        | **Inline secret literals (location only, value redacted)**; rewards `op://` / `vault:` / `process.env`; IDP/OIDC |\n| **D7** Prod-readiness            | Missing kill-switch / feature-flag, 429 / rate-limit, eval / red-team gate                                       |\n\nEach dimension is scored 🟢 green / 🟡 yellow / 🔴 red with a severity tag, plus the matched\nevidence (`file:line`). The methodology behind the rubric maps to OWASP Top 10 for LLM\nApplications, the MCP spec (2025-06-18), and OpenTelemetry GenAI semantic conventions.\n\n## Try it on the bundled fixtures\n\n```bash\nmcp-gateway-scan fixtures/secure      # mostly green\nmcp-gateway-scan fixtures/vulnerable  # mostly red\n```\n\nThe `fixtures/vulnerable` tree contains only **fake, non-functional placeholder secrets**\n(`sk-EXAMPLENOTREAL…`, `AKIAEXAMPLE…`) so you can see the redacted-secret output safely.\n\n## Accuracy\n\nEvery finding is meant to be defensible to a skeptical senior engineer. The scanner\ndistinguishes **prompt content** (a system-message string / YAML prompt field) from **code\nthat merely documents a pattern** — so a doc comment quoting `rg 'only use|if the user is\nadmin'` is **not** flagged as authorization-in-prompt, while the same words inside a real\nsystem prompt **are**. Comment lines and grep-recipe / regex documentation are suppressed\nacross all dimensions, and \"control present\" signals are matched in code/config, not prose.\n\n## What this is (and isn't)\n\nThis is a **fast, free heuristic wedge** — a static pattern scanner. A green score is a good\nsignal, not a guarantee; a red score is a concrete pointer to fix. It does **not** run\nfault-injection, inspect your live IAM/IDP, or read your traces. That depth is what a full\n**MCP Gateway Readiness Audit** provides: a cited Gap Matrix and a sequenced 90-day\nremediation roadmap.\n\n|            | This scanner (free, MIT) | Full MCP Gateway Readiness Audit (paid)                |\n| ---------- | ------------------------ | ------------------------------------------------------ |\n| Method     | static pattern checks    | read-only review of your live codebase                 |\n| Live tests | —                        | fault-injection (F1–F5), trace verification            |\n| Evidence   | matched line             | per-finding `file:line` in an evidence index           |\n| Output     | 7-dimension score        | cited gap matrix + severity + sequenced 90-day roadmap |\n| Delivery   | instant, automated       | expert engagement + live review session                |\n\n> **Need the full audit?** This scanner is a free heuristic wedge.\n> The **[Provenwright MCP Gateway Readiness Audit](https://provenwright.com/audit)** goes deeper:\n> read-only assessment of your live codebase, per-finding evidence (file + line),\n> a cited Gap Matrix, and a sequenced 90-day remediation roadmap.\n>\n> See a sample report: [provenwright.com/sample/](https://provenwright.com/sample/)  \n> Full audit info: [provenwright.com/audit](https://provenwright.com/audit)  \n> Book a 15-min call: [cal.com/willianpinho](https://cal.com/willianpinho)  \n> Email: me@willianpinho.com\n\n## License\n\nMIT © Willian Pinho\n",
  "bytes": 10643,
  "sha": "8d6c7a2d527a1ec7688858d130a8a1e69a8105ff2e8a07bb7e0eb09f35b89684",
  "repo_slug": "willianpinho/mcp-gateway-scan",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_willianpinho_mcp_gateway_scan_7eaad522/readme"
}