mcpreflight

mcpreflight

指向任意 MCP 或 x402 端点，一条命令即可获取判定。只读：无需 API 密钥、钱包，也不会调用工具。

npx -y @eidonze/mcpreflight schema https://your-mcp-server.example/mcp

Status: PASS | FAIL | UNKNOWN   exit 0 | 1 | 2, so CI can gate on it

当 Agent 客户端、买家或 CI 任务即将依赖某个你无法查看其源代码的端点（包括你不拥有的端点）时，就可以使用它。它只读取端点已向任何匿名调用者发送的内容：initialize 握手、tools/list，以及 HTTP 402 / x402 支付文档。

形式	运行方式	用途
CLI	npx -y @eidonze/mcpreflight ...	临时检查和脚本
GitHub Action	uses: xka0085-byte/mcpreflight@v1	当握手、工具架构或 x402 挑战发生变化时，让 PR 检查失败
stdio MCP 服务	npx -y -p @eidonze/mcpreflight mcpreflight-mcp	让 Agent 在连接端点前先进行检查

无需安装即可试用：在浏览器中免费运行检查，无需注册：check-your-mcp-endpoint

已列入官方 MCP Registry，标识符为 io.github.xka0085-byte/mcpreflight（浏览），也已收录于 GitHub Marketplace。

它是什么

只读的 MCP 和 x402 预检工具：读取 initialize + tools/list 以及 x402 支付文档。无需 API 密钥、钱包或付款，也不会调用工具。

这是端点预检，不是源代码审计。用于读取仓库或模糊测试已启动服务的工具需要代码检出和启动命令；本工具只需一个 URL，因此可以检查 Agent 即将连接的部署，包括你不拥有的部署。

检查你不拥有的端点

每周都会对官方 MCP Registry 中列出的所有远程端点运行同样的只读检查，并以网页和 JSON 的形式发布结果：

• 信任目录 — 35,325 个端点，每个端点一份报告：状态、协议版本、工具数量、检查结果，以及是否需要凭据。
• JSON API — 每个端点对应 /trust/api/{slug}.json，另有批量索引和 JSON Schema。无需密钥、注册或速率限制。
• x402 普查数据集 — 同一轮扫描中的支付数据：35,327 个端点中有 1,583 个声明支持 x402 或 HTTP-402，附带每周数据序列、与整个 Registry 基线对比的状态分布，以及可下载的 CSV/JSON。

引用任何数字前，请先了解相关术语：在 2026-11-02 的扫描中，20,701 个端点匿名响应（PASS），10,236 个端点因按设计要求提供凭据而以 401 拒绝访问（AUTH_GATED），167 个端点可以访问但无效（FAIL），还有 4,223 个端点没有提供匿名握手（UNKNOWN，通常是我们无法穿透的认证墙）。根据这些数据统计“已失效 MCP 服务”的数量会得出错误结论——Registry 中有 41% 的端点完全无法在没有凭据的情况下检查。

将其用作 MCP 服务

stdio 入口点是 bin/mcpreflight-mcp.mjs，并作为同一 npm 包中的 mcpreflight-mcp bin 发布。它实现了客户端所需的 MCP 生命周期：initialize 返回包含包版本的 serverInfo mcpreflight，接受 notifications/initialized，而 tools/list 会返回两个工具。

工具	功能
schema_check	对服务 URL 运行只读预检：initialize 握手、tools/list，然后验证工具输入架构。返回包含检查结果的 PASS/FAIL/UNKNOWN。绝不调用工具，也不读取数据。
x402_inspect	无需付款即可读取 HTTP 402 挑战：验证付款文档结构、accepts[] 条目和发现清单。绝不签名或结算。

将其添加到 MCP 客户端：

{
  "mcpServers": {
    "mcpreflight": {
      "command": "npx",
      "args": ["-y", "-p", "@eidonze/mcpreflight", "mcpreflight-mcp"]
    }
  }
}

这两个工具执行的操作与 CLI 相同，并返回相同的检查结果，因此 Agent 可以在连接端点前检查它。设计上只读：传输层仅向你提供的 URL 发送 GET 和 POST 请求，不持有密钥，也没有钱包。

使用案例

• joxo 提供的 MCP 端点按设计需要通过身份验证。该项目维护者查看了 0.2.0 源码，确认检查只发送了两个普通 POST 请求且没有依赖项，随后运行 npx @eidonze/[email protected] schema https://joxo.ai/api/mcp，针对刻意设置的 OAuth 2.1 验证门得到了 UNKNOWN: MCP initialize returned HTTP 401（#50）。这份报告促使 0.3.0 将 OAuth 挑战归类为 AUTH_GATED，并验证 RFC 9728 资源元数据，而不是将其视为失效端点。他们于 2026-11-01 重新检查并关闭了问题：“该端点仅供登录用户使用，因此不应期待匿名握手。感谢处理 AUTH_GATED；现关闭问题。”（#50）。
• cueframe-mcp 的维护者在修复后重新运行扫描并反馈结果：@eidonze/[email protected]（早期的 npm 名称）现在在其端点上以 0 退出，匿名 tools/list 负载也从 1,399,189 字节降至 550,377 字节，低于扫描器的 1 MiB 限制（#11）。
• 收录于 awesome-mcp-lists 的 MCP 工具包 / 测试工具类别下（#226）。

这些只是运行该检查的示例，并非背书，也不代表 PASS 就意味着服务安全。

从这里开始

退出代码对 CI 保持稳定：0 表示 PASS，1 表示 FAIL，2 表示 UNKNOWN/网络问题，3 表示用法错误。需要 Node.js 18+。

mode 可以是 schema（MCP 握手加工具架构）、inspect（一次性 x402 预检）、baseline（记录当前 402 挑战结构）或 drift（当该结构偏离已提交的基线时让任务失败）。报告也会附加到任务摘要中，而 steps.<id>.outputs.status 会携带退出代码，供后续步骤据此分支，无需解析日志。

查找合适的指南

• 公开文档站点
• MCP 架构检查器
• x402 端点检查器
• MCP Registry 中的 x402 支付：普查数据集
• MCP 安全 CI
• 故障排除
• OAuth 范围与当前限制

立即运行

检查 MCP 服务，不调用任何工具：

npx @eidonze/mcpreflight schema https://your-mcp-server.example/mcp --json

检查 x402 端点，无需付款：

npx @eidonze/mcpreflight inspect https://your-api.example/paid --method=POST --json
npx @eidonze/mcpreflight inspect https://your-api.example/paid --x402   # payment layer only, one request

需要 Node.js 18+。无需 API 密钥或钱包。

针对在线端点运行架构检查的示例：

$ npx @eidonze/mcpreflight schema https://your-mcp-server.example/mcp

MCP Tool Schema Report
- Status: FAIL
- Endpoint: https://your-mcp-server.example/mcp
- Protocol: 2025-06-18
- Tools: 12

- FAIL REQUIRED_PROPERTY_UNDEFINED: tools[3] requires undeclared property query
- WARN PROPERTY_DESCRIPTION_MISSING: tools[7].limit has no description

对健康服务执行完全相同的检查时，会输出 Status: PASS 并以 0 退出，因此 CI 可以据此设置门禁。

应使用哪个命令？

命令	检查内容	不会执行的操作
schema	MCP initialize、tools/list、工具名称、描述和 JSON 架构	不会调用工具，也无法证明运行时行为
inspect	HTTP 402、x402 v1/v2 支付文档、accepts[]、发现清单、延迟和响应摘要	不会签名、付款、结算、重试或验证交付
inspect --x402	仅检查支付层：一次请求、402 挑战及其 accepts[] 条目，不执行 MCP 握手或发现探测	限制相同，也不会说明支付层之后的 MCP 端点情况

退出代码对自动化保持稳定：0 表示通过，1 表示失败，2 表示未知／网络错误，3 表示用法错误。

不会检查的内容

mcpreflight 是协议和架构层面的预检工具，不是安全审计工具。它不会：

• 检测服务器实现中的恶意代码、提示词注入或供应链风险
• 调用工具，因此无法证明运行时行为、数据处理方式或权限范围
• 绕过、测试或评估身份验证和授权
• 验证 x402 端点的支付结算或交付情况
• 认证其所检查的响应结构之外的任何规范合规性

PASS 表示扫描时观察到的握手和架构格式正确，仅此而已。

GitHub Actions

在拉取请求中添加只读检查：

name: MCP Trust Check
on: [pull_request]

jobs:
  mcp-trust:
    runs-on: ubuntu-latest
    steps:
      - uses: xka0085-byte/mcpreflight@v1
        with:
          endpoint: https://your-mcp-server.example/mcp
          mode: schema
          format: markdown

对 x402 预检使用 mode: inspect。默认情况下，操作在结果为 FAIL 或 UNKNOWN 时失败；若要将其设为信息性检查，请设置 fail-on: false。想在 Marketplace 中查找它？搜索“MCP Trust Preflight”或“mcp server test”，也可以浏览 mcp-trust-preflight 条目。

入门模板

使用已配置好此检查的模板开始新的 MCP 项目：

• 安全 MCP 服务入门模板

该检查为只读，应针对公开的测试端点。请勿在工作流输入中放置私钥或凭据。

报告的含义

PASS 表示观察到的响应符合此版本中的检查要求。它不是安全审计、协议认证、支付成功保证，也不能证明端点安全。UNKNOWN 表示在超时或响应大小限制内无法观察到该端点。

架构检查失败示例：

FAIL REQUIRED_PROPERTY_UNDEFINED tools[0] requires undeclared property query

x402 检查失败示例：

FAIL NO_402 Expected HTTP 402, received 400

存在的原因

这些检查源自构建 ReceiptRail 时观察到的故障模式：阻止 x402 挑战的请求正文验证、采用多种标头／正文结构的支付文档，以及可能隐藏真实 accepts[] 文档的供应商提示标头。

mcpreflight 以一个只读代码库提供三种形式：CLI、GitHub Action，以及 stdio MCP 服务（bin/mcpreflight-mcp.mjs，npm 命令为 mcpreflight-mcp），提供 schema_check 和 x402_inspect。它与 mcpreflight.dev 无关；请确认 npm 作用域为 @eidonze/mcpreflight。

反馈

发现误报或我们应该支持的协议结构？提交问题。请提供命令、脱敏后的输出、Node 版本，以及端点属于 MCP 还是 x402。请勿包含令牌、支付签名或私有 URL。

许可证

MIT