MCP Gateway Scan

mcp-gateway-scan

用于检测 MCP / Agent 网关生产就绪度反模式的只读静态扫描器。 扫描代码仓库，数秒内即可获得涵盖 7 个维度的红／黄／绿评分。

由 Provenwright MCP Gateway Readiness Audit 背后的团队打造 — 这是一份完整的审计报告，包含引用来源索引、评分差距矩阵和 90 天路线图。 完整审计报告：provenwright.com/audit

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

它会扫描代码和配置，查找那些会让 MCP 网关从演示变成事故的失效模式——由模型决定授权、错误处理器故障时默认放行（fail open）、供应链依赖未固定、追踪信息不可见、支出不受限制、内联密钥以及缺少运维控制手段——并准确指出每项问题的位置。

100% 只读。它只会_读取_文件。绝不会执行你的代码、发起网络请求，也绝不会输出密钥值——对于内联密钥问题，只会报告位置（<file:line>），并对密钥值进行脱敏。

---

安装

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

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

需要 Node ≥ 18。

使用方法

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

“我应该连接到这个服务吗？”——连接判定

在将第三方 MCP 服务接入持有真实凭据的 Agent 前，将其交给 connect 扫描，即可在相同的 7 个维度上获得单一的总体判定——CONNECT、REVIEW 或 DO-NOT-CONNECT——并优先显示最严重的问题。

# 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

判定会将各维度的评分汇总为一个决策：

判定	条件	退出码
DO-NOT-CONNECT	任一 S1（完全失陷级别）维度为红色	1
REVIEW	存在明确或潜在风险（S2/S3 为红色，或任一维度为黄色）	1
CONNECT	静态检查中所有维度均为绿色	0

使用相同的扫描引擎、相同的 --json / --ci 标志，以及相同的只读和密钥脱敏保证 — connect 只会将输出重新组织为是否连接的决策。CONNECT 绿色是一个良好的信号，而非保证：静态扫描无法为发布者或运行时行为背书。

在 Claude Code / Cursor 中运行（MCP 服务）

同一软件包也可以作为 MCP 服务运行，让你的 Agent 以对话方式执行扫描——只需让它“扫描此代码仓库的网关就绪度”。

Claude Code（一条命令）：

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

Cursor / 任意 MCP 客户端 — 添加到你的 .mcp.json 中：

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

然后让你的 Agent 运行 scan_gateway 工具：

• 输入：{ "path": "<repo or dir>", "ci": false }（ci 可选——启用 CI 门禁判定）。
• 输出：按维度汇总的 🟢🟡🔴 结果 + 结构化结果。只读；仅扫描你指定的路径；密钥值会保持脱敏（仅显示位置，绝不显示值）。

同一软件包，两种模式——mcp-gateway-scan mcp 是服务（供你的 Agent 使用）；默认的 mcp-gateway-scan <path> 是 CLI（直接在终端或 CI 中运行）。mcp 子命令不会改变 CLI 的行为。

或在 Glama 上查找

mcp-gateway-scan 已列入 Glama MCP directory， 你可以在此查看其工具架构、在浏览器中试用，或直接从列表部署容器化服务。构建规范和发布流程见 docs/glama-release.md。

输出示例

  [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

将其接入 CI

--ci 会输出简洁、便于 grep 的摘要，并且只要任一维度为红色，就以非零状态退出，因此回归问题（新增的默认放行处理程序、未固定版本的镜像、提交的密钥）会导致构建失败：

# .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.

7 个维度

维度	检查内容
D1 工具访问 / RBAC	在提示词中表达授权要求；缺少网关策略层
D2 默认拒绝	返回 allow/true/ok/pass 的 catch/except 块；缺少超时设置
D3 入门配置 / 供应链	:latest、@main、npx -y …@、未固定版本的镜像；奖励 sha256: / integrity
D4 可观测性	OTel / traceparent / spans 的存在或缺失；日志中的原始提示词
D5 路由 / 成本	缺少 max_tokens / 预算 / 速率限制 / 配额
D6 密钥 / 身份	内联密钥字面量（仅显示位置，值已隐去）；奖励 op:// / vault: / process.env；IDP/OIDC
D7 生产就绪度	缺少紧急停用开关 / 功能开关、429 / 速率限制、评估 / 红队门槛

每个维度都会评为 🟢 绿色 / 🟡 黄色 / 🔴 红色，并附带严重性标签和匹配到的证据（文件:行号）。评分标准的方法论依据包括 OWASP Top 10 for LLM Applications、MCP 规范（2025-06-18）和 OpenTelemetry GenAI 语义约定。

在附带的测试样例上试用

mcp-gateway-scan fixtures/secure      # mostly green
mcp-gateway-scan fixtures/vulnerable  # mostly red

fixtures/vulnerable 目录树仅包含虚构且无法使用的占位密钥（sk-EXAMPLENOTREAL…、AKIAEXAMPLE…），你可以安全地查看密钥值已隐去的输出。

准确性

每条发现都应当经得起持怀疑态度的资深工程师审视。扫描器会区分提示词内容（系统消息字符串 / YAML 提示词字段）和仅用于说明某种模式的代码——因此，引用 rg 'only use|if the user is admin' 的文档注释不会被标记为提示词中的授权要求，而相同的文字出现在真实的系统提示词中则会。所有维度都会忽略注释行和 grep 操作示例 / 正则表达式文档；“控制机制已启用”的信号则会从代码 / 配置中匹配，而非从说明文字中匹配。

适用范围（及不适用范围）

这是一个快速、免费的启发式初筛工具——用于静态扫描模式。绿色评分是积极信号，但不是保证；红色评分则会明确指出需要修复之处。它不会运行故障注入测试、检查你正在使用的 IAM/IDP，也不会读取你的跟踪记录。要进行这样的深度审查，可以选择完整的 MCP Gateway Readiness Audit，它会提供附有引用的差距矩阵，以及按顺序排列的 90 天整改路线图。

	此扫描器（免费，MIT）	完整的 MCP Gateway Readiness Audit（付费）
方法	静态模式检查	对你正在使用的代码库进行只读审查
实时测试	—	故障注入（F1–F5）、跟踪验证
证据	匹配的行	证据索引中每项发现对应的 file:line
输出	7 个维度的评分	附有引用的差距矩阵 + 严重性 + 按顺序排列的 90 天路线图
交付方式	即时、自动化	专家参与 + 实时审查会议

需要完整审计？ 此扫描器是一款免费的启发式初筛工具。 Provenwright MCP Gateway Readiness Audit 会进行更深入的审查： 对你正在使用的代码库进行只读评估，提供每项发现的证据（文件 + 行）， 附有引用的差距矩阵，以及按顺序排列的 90 天整改路线图。

查看示例报告：provenwright.com/sample/
完整审计信息：provenwright.com/audit
预约 15 分钟通话：cal.com/willianpinho
电子邮件：[email protected]

许可证

MIT © Willian Pinho