x402-list-mcp

x402-list-mcp

通过 MCP 发现 x402 支付 API、检查正常运行时间与定价，并按 facilitator 查看链上验证的结算量。

什么是 x402-list

x402-list 是一个收录接受 x402（HTTP 402 稳定币）支付的服务的目录。它会监控已收录服务的正常运行时间、响应时间和状态，并在链上衡量 facilitator 的结算量。

本包是公开的 x402-list HTTP JSON API 之上的轻量封装。它不持有任何密钥、不接触任何数据库，也不会对目录进行任何写入。它通过 Model Context Protocol 将目录以七个工具的形式暴露给 AI Agent：其中六个是免费且只读的，第七个 x402_assess_services 是唯一付费的工具，它是一个透传工具，会转发由你在客户端自行签名的 x402 支付挑战（本包绝不持有密钥、绝不签名，也绝不结算）。

安装与快速开始

使用 Streamable HTTP 连接到托管服务 https://mcp.x402-list.com/mcp，或在本地通过 stdio 运行 npm 包。本地使用需要 Node.js 20 或更高版本以及 npm；托管连接无需在本地安装 Node.js。

Claude Code

连接到托管服务：

claude mcp add --transport http x402-list https://mcp.x402-list.com/mcp

或改用本地包：

claude mcp add --transport stdio x402-list -- npx -y x402-list-mcp

请选择一种传输方式。有关配置作用域，请参阅 Claude Code MCP 文档。

Cursor

将托管服务添加到 Cursor，然后在 Cursor 中确认安装。

该安装链接所编码的配置，与下面在 .cursor/mcp.json（项目）或 ~/.cursor/mcp.json（全局）中手动添加的条目相同：

{
  "mcpServers": {
    "x402-list": {
      "url": "https://mcp.x402-list.com/mcp"
    }
  }
}

请参阅 Cursor MCP 文档和安装链接格式。

VS Code

将以下条目添加到项目中的 .vscode/mcp.json，然后从编辑器启动服务，并在 Copilot agent mode 中使用它：

{
  "servers": {
    "x402-list": {
      "type": "http",
      "url": "https://mcp.x402-list.com/mcp"
    }
  }
}

有关其他配置位置，请参阅 VS Code MCP 文档。

Codex

使用 Codex 命令行添加托管服务：

codex mcp add x402-list --url https://mcp.x402-list.com/mcp

或将以下条目添加到 ~/.codex/config.toml；命令行与 IDE 扩展共用此配置：

[mcp_servers.x402-list]
url = "https://mcp.x402-list.com/mcp"

请参阅 Codex MCP 文档。

Claude Desktop 和其他本地 stdio 客户端

将以下条目添加到 claude_desktop_config.json，或你的 stdio 客户端的等效配置中，然后重启客户端：

{
  "mcpServers": {
    "x402-list": {
      "command": "npx",
      "args": ["-y", "x402-list-mcp"]
    }
  }
}

有关 Claude Desktop 配置文件的位置，请参阅本地 MCP 连接指南。

客户端启动的命令与你可以在终端中运行的命令相同：

npx -y x402-list-mcp

自托管 Streamable HTTP

要在 POSIX shell 中运行你自己的 HTTP 实例：

MCP_HTTP_PORT=3000 npx -y x402-list-mcp --http

将客户端连接到 http://localhost:3000/mcp。位于 http://localhost:3000/healthz 的健康探测会返回 {"status":"ok"}。

环境变量

变量	默认值	用途
X402_LIST_BASE_URL	https://x402-list.com	API 基础 URL。会自动追加 /api/v1 前缀。
X402_LIST_TIMEOUT_MS	15000	每个请求的超时时间，单位为毫秒。
MCP_HTTP_PORT / PORT	3000	HTTP 端口。设置 MCP_HTTP_PORT 会选择 HTTP 传输。
MCP_ALLOWED_ORIGINS	（空，宽松）	HTTP 模式下允许的 CORS 来源的逗号分隔列表。
MCP_ALLOWED_HOSTS	（空，关闭）	逗号分隔列表，用于在 HTTP 模式下启用 DNS 重绑定防护。

工具

工具	功能
x402_search_services	按查询词、类别、网络、状态和 signable（最近观测到的 402 envelope 是否携带标准 x402 客户端签名所需的 EIP-712 域参数）搜索和筛选目录；可按 newest/uptime/cheapest/endpoints 排序。
x402_get_service	按 slug 获取单个服务的完整详情：端点、每个端点的 USD 定价、uptime 窗口、网络、结算资产。
x402_find_best_service	针对某项需求的服务端（GET /api/v1/best）计算出的排序推荐。排序主要依据可靠性、x402 合规性和价格（状态、verified、uptime、响应时间、USD 价格），并对每个服务的链上 traction 附加约 10% 的小权重，该权重永远不会压过前三项。读取结果中的 ranking_version 以确认其评分配置代（见下文），并读取其 units 映射以了解评分注意事项。
x402_check_health	实时状态，可针对整个目录或单个服务（uptime 快照、连续失败次数）。
x402_facilitator_volumes	按 facilitator 统计的链上验证结算量（今日 UTC/7d/30d/all），以 USD 计，附交易笔数和链上 vs 挂牌标志。*_24h 字段覆盖今日（UTC）至今，而不是过去滚动 24 小时窗口。
x402_change_events	免费、只读的监控信息流，展示监控在挂牌服务上观测到的变更，最新在前，且仅包含三种事件类型（payto_changed、price_changed、schema_changed）。可按 service（挂牌 slug：参数名为 service，不是 slug）、type 和 days（1 到 365，默认 90）筛选；用 page / per_page 分页（每页最多 100 条）。每个事件都带有观测时间戳、diff 摘要以及变更前后的 402 快照。事件中的价格是原子代币数量，绝不是美元，并且 API 返回的每个 payout 地址都会被掩码处理：该信息流只报告 payTo 发生了变更，从不报告地址本身。
x402_assess_services	付费（Base 上 $0.25 USDC，x402）。针对某项需求，对一小组挂牌服务进行按需的全新 AI 对比。透传：它从不持有密钥、从不签名、也从不结算。不带 payment_signature_b64 调用可获得原样的 x402 challenge，在客户端侧签名，然后带上签名重试以获取报告。可选地添加 probe 目标 { slug, endpoint_path? }，以便同时实测一个挂牌服务：价格变为 $0.25 加上该端点价格 X（不可退款），报告中会新增一个 probe_report 块，包含结论和截断摘录，绝不包含第三方原文。

评分配置代

x402_find_best_service 会在 ranking_version 中返回其评分配置代。仅在同一代内比较分数。以下变更解释了为什么不同代之间的分数存在差异：

• 第 2 代在观测到某个服务的 EVM 路由中至少有一条缺少标准 x402 客户端签名付款所需的 EIP-712 域参数（extra.name、extra.version）时，将合规项上限设为 0.6，即 C 档的下限。这是关于线上 envelope 的事实，而不是对服务价值的评判。
• 第 3 代对 traction 项新增了反刷量规则：30d 结算量 $10 的绝对下限，低于该值时该项得分为 0，因为低于下限的结算量与灰尘无异，绝不能影响排名；当 payout 集中于单一买家时进行折减，若单一买家贡献了全部结算量，最多折减 traction 项的一半，因为一个买家只是一段关系，而不是该项旨在奖励的广泛需求；以及不再对无可映射 payTo 的服务重新归一化权重，而是该项直接得分为 0，因此隐藏 payout 地址不再优于提供可测量的地址。

单位说明

所有货币金额均为十进制美元，并原样传递。任何地方都没有美分换算。每个端点的 pricing[].price 字段是原始链上代币原子数量（一个 uint256 字符串），不是美元；只有 price_usd 才是美元数字。

诚实性说明

有两种不同的链上交易量信号；不要将它们混为一谈。Facilitator 交易量（x402_facilitator_volumes）是生态系统层面的头条数据，按 facilitator 聚合。单服务吸引力（每个服务上的 traction 区块，在 x402_find_best_service 内权重约为 10%）是通过可识别的结算方在该服务自身 payTo 上衡量的结算量——这是一种刻意为之的保守低估，而非估算：未归属的结算会被直接排除，绝不进行放大。当某个 payTo 被多个服务共享时（shared_payout: true），只有结算交易量会按比例归属，即该地址上的运营方级别交易量按共享该地址的服务进行分摊，这是一种声明的约定，而非单独观测到的度量；而交易数量和唯一买家数仍保持为运营方级别的完整整数；一个位于尚未被衡量的网络上的服务，或一个其探测一直失败的分摊收益成员，完全不携带吸引力项，剩余权重会在其基础上重新归一化。绝不要将共享的、按比例分摊的或未衡量的交易量解读为某个服务的收入。若要问“哪些 facilitator 拥有真实的链上交易量”，请使用 x402_facilitator_volumes 并读取 verification 标志。

来源

源代码：mcccsm/x402-list-mcp。本仓库在 MCP 包发布时对其进行镜像。公开 REST API 的文档位于 x402-list.com/api。

许可证

MIT