convez.ai
MCP ServerDevOps & InfraestruturaIntermediário
willianpinho

MCP Gateway Scan

willianpinho/mcp-gateway-scan

Scanner de produção-readiness para MCP gateways em 7 dimensões

Ver no GitHub
InicialPluginScore · de 0 a 100

Scanner estático de produção para gateways MCP que detecta anti-padrões críticos de segurança e confiabilidade. Analisa seu código em 7 dimensões (autorização, tratamento de erros, supply chain, rastreamento, gastos, secrets, operacionalidade) e retorna um score visual RED/YELLOW/GREEN sem executar código ou fazer chamadas externas.

Instalação

$npx convez-ai willianpinho/mcp-gateway-scan

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 4 meses
Versão
v0.2.0
Issues abertas
0
Contribuidores
1

Casos de uso

  • Auditar gateways MCP antes de deployment em produção
  • Validar segurança e conformidade em pipelines CI/CD
  • Identificar falhas de fail-close vs fail-open em controladores de autorização
  • Detectar inline secrets e configurações perigosas em repositórios

Veredito

Ferramenta essencial para times que deployam MCP gateways em produção. O scanner é conservador, lê-only, seguro, e fornece feedback estruturado com localização exata das falhas — seu maior valor está em pipelines CI/CD para bloquear deploys inseguros antes que saiam do forno.

README

A tradução para o português deste README ainda está na fila.

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: willianpinho.com/mcp-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

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

DimChecks for
D1 Tool-access / RBACAuthorization expressed in prompts; absence of a gateway policy layer
D2 Fail-closecatch/except blocks that return allow/true/ok/pass; missing timeouts
D3 Onboarding / supply chain:latest, @main, npx -y …@, unpinned images; rewards sha256: / integrity
D4 ObservabilityPresence/absence of OTel / traceparent / spans; raw prompts in logs
D5 Routing / costMissing max_tokens / budget / rate-limit / quota
D6 Secrets / identityInline secret literals (location only, value redacted); rewards op:// / vault: / process.env; IDP/OIDC
D7 Prod-readinessMissing 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)
Methodstatic pattern checksread-only review of your live codebase
Live tests—fault-injection (F1–F5), trace verification
Evidencematched lineper-finding file:line in an evidence index
Output7-dimension scorecited gap matrix + severity + sequenced 90-day roadmap
Deliveryinstant, automatedexpert 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: willianpinho.com/mcp-audit
Book a 15-min call: cal.com/willianpinho
Email: me@willianpinho.com

License

MIT © Willian Pinho

Ver o original no GitHub

Bom para

Relacionados