MCP x402 - Evidence-Backed Web Verification

MCP x402 — 为 AI Agent 提供有证据支持的网页验证

在 Agent 执行操作前验证卖家、产品、报价、政策或声明

向 AI Agent 提供一个公开的 HTTP(S) 页面和 1 至 10 条具体条件。verificar_condicoes 工具会针对每条条件返回基于证据的判定：

• confirmado — 页面明确支持该条件。
• rejeitado — 页面明确与该条件相矛盾。
• incerto — 页面现有证据不足。

每次验证都会包含最终来源 URL、页面标题、时间戳、逐条条件说明、可用时引用的证据、唯一的 verificationId，以及 SHA-256 pageHash。

适用场景

• AI 采购 Agent；
• 卖家、产品和报价验证；
• 购买前尽职调查；
• 政策和条款检查；
• 执行操作前要求提供证据的商业自动化。

简单的 x402 集成

• 付款前免费进行预检验证。
• Base 主网上每次验证收费 $0.05 USDC。
• 无需账户或订阅。
• 可通过 MCP 和 HTTP 使用。
• 此仓库包含可直接运行的买家。
• 付费 HTTP 和 MCP 接口已启用 Bazaar 发现元数据。

在线接口

• MCP：https://mcp-x402-production.up.railway.app/mcp
• 免费 MCP 预检：POST https://mcp-x402-production.up.railway.app/preflight/mcp
• 免费验证预检：POST https://mcp-x402-production.up.railway.app/preflight/verify-conditions
• 付费验证：POST https://mcp-x402-production.up.railway.app/verify-conditions
• 健康检查：GET https://mcp-x402-production.up.railway.app/health

该服务还通过 analisar_url 和 consultar_ia 提供付费公开 URL 分析和通用 AI 咨询。

在线服务

• 基础 URL：https://mcp-x402-production.up.railway.app
• 健康检查：GET /health
• MCP 接口：POST /mcp
• 付费 URL 分析：POST /analyze
• 价格：每次付费请求 $0.05 USDC
• 网络：Base 主网（eip155:8453）

生产状态

• 已在 Railway 上部署生产环境
• x402 v2 支付流程
• Base 主网支付（eip155:8453）
• 付费 HTTP 接口会返回包含 Bazaar 元数据的有效 x402 支付质询
• 已确认 MCP 和 HTTP 的支付、执行、结算与交付均在链上完成
• MCP Bazaar 元数据会公布公开的 HTTPS MCP 服务 URL
• 尚未声称已确认 CDP 原生 MCP 目录索引；上游跟踪：coinbase/cdp-sdk#764

MCP 工具

决策验证

verificar_condicoes — $0.05 USDC

面向 Agent 的付费决策验证工具。

提供一个公开 URL 和一项或多项具体条件。工具仅依据从该页面提取的证据返回决策：

• confirmado — 页面明确证明了该条件。
• rejeitado — 页面明确与该条件相矛盾。
• incerto — 页面没有提供足够证据。

每项结果都包含最终来源 URL、页面标题、验证时间戳、逐项条件说明，以及可用时的简短引文作为证明。

条件示例：

• “页面标明了卖家身份。”
• “该产品在葡萄牙有售。”
• “页面显示了以欧元计价的价格。”
• “文档说明该服务支持 x402。”

此工具专为需要在采取下一步行动前，基于证据做出决策的 Agent 设计。

工具	描述	价格
consultar_ia	向 OpenAI Responses API 发送提示词。	$0.02 USDC
analisar_url	获取并分析公开的 HTTP 或 HTTPS 页面。	$0.05 USDC
verificar_condicoes	验证公开页面上的具体条件，并返回基于证据的决策。	$0.05 USDC

技术

• Node.js 和 TypeScript
• Express
• Model Context Protocol
• OpenAI Responses API
• x402 payments
• viem
• Cheerio
• Railway

安全

• 由 Railway 提供 HTTPS
• Helmet 安全标头
• 每 15 分钟最多 100 个请求
• 带有唯一请求 ID 的结构化请求日志
• 主机验证和 Railway 健康检查支持
• 受限的 OpenAI API 密钥，仅可访问 /v1/responses
• 环境文件和密钥已从 Git 中排除

环境变量

服务端

变量	必需	描述
OPENAI_API_KEY	是	OpenAI 项目 API 密钥。
OPENAI_MODEL	否	OpenAI 模型。默认为 gpt-5-mini。
HOST	否	监听主机。默认为 0.0.0.0。
PORT	否	监听端口。默认为 3000。
RAILWAY_PUBLIC_DOMAIN	Railway	由 Railway 自动提供。
PUBLIC_SERVICE_URL	否	用于发现元数据的规范公开 HTTPS 源站。Railway 会根据 RAILWAY_PUBLIC_DOMAIN 自动推导；生产环境 URL 为后备值。
OBSERVABILITY_SALT	建议	稳定的密钥盐，仅用于在重启期间对来源／客户端指纹进行假名化处理。

本地买方

变量	必需	描述
EVM_PRIVATE_KEY	是	Base 主网买方钱包的私钥。切勿提交此值。
JOURNEY_ID	否	要复用的现有关联 ID；否则由买方生成。

本地 .env.test 文件示例：

EVM_PRIVATE_KEY=your_private_key_here

本地开发

安装依赖：

npm install

启动开发服务器：

npm run dev

构建项目：

npm run build

启动编译后的服务器：

npm start

健康检查

健康检查端点公开可用，无需付费：

curl https://mcp-x402-production.up.railway.app/health

Railway 日志诊断

Railway 目前支持通过 --since 获取历史 HTTP 日志，但会拒绝 --until。在 Windows PowerShell 中，无需使用有问题的标志即可导出有界的应用和 HTTP 日志 时间段：

.\scripts\export-railway-window.ps1 `
  -StartUtc "2026-08-22T16:31:22.401228537Z" `
  -EndUtc "2026-08-23T06:21:18.045229877Z" `
  -OutputPrefix "railway-diagnostic"

脚本从下限开始获取日志，并在本地使用序数 ISO-8601 比较应用 UTC 上限，从而保留 Railway 的纳秒 时间戳。脚本会写入原始捕获文件，以及有界的 app 和 http NDJSON 文件。

分析这两个有界文件，同时逐行读取并验证每一条物理行：

npm run logs:analyze -- \
  --since "2026-08-22T16:31:22.401228537Z" \
  --pretty \
  --out railway-diagnostic-report.json \
  railway-diagnostic-app.ndjson railway-diagnostic-http.ndjson

报告包含每个文件的覆盖情况、空行／有效行／无效行的数量、时间戳范围、 Diogo-*、RailwayHealthcheck、已知探测或索引器与潜在外部流量的区分、行程重建和漏斗 停滞点。报告会将应用中的 railwayRequestId 值与 Railway HTTP 中的 requestId 值关联，识别 HTTP clientUa，按指纹和时间接近程度对服务器生成的行程 ID 分组，并且只统计经过接受和规范化的 反馈。报告有意不将孤立的 402 视为购买意向，也不会根据请求元数据推断用户身份或动机。

可立即运行的 x402 买家

此仓库提供可立即运行的应用和 AI Agent 买家。MCP 买家连接到在线服务，根据 Base 主网 USDC 和最高 $0.05 的付款额验证 x402 付款要求，签署付款，重试同一个工具调用，并打印结算凭证和结果。

克隆并准备买家：

git clone https://github.com/Diogoup26/mcp-x402.git
cd mcp-x402
npm install

在项目根目录中创建本地 .env.test 文件：

EVM_PRIVATE_KEY=0xYOUR_64_HEX_CHARACTER_PRIVATE_KEY

切勿提交 .env.test 或泄露私钥。

构建项目：

npm run build

以下命令会在 Base 主网上授权真实的 x402 付款：

• consultar_ia：$0.02 USDC
• analisar_url：$0.05 USDC
• verificar_condicoes：$0.05 USDC

HTTP URL 分析

npm run analyze -- "https://example.com" "Summarize this page."

HTTP 决策验证

npm run verify -- "https://example.com" "The page identifies the seller."

MCP URL 分析

npm run mcp:analyze -- "https://example.com" "Summarize this page."

MCP AI 咨询

npm run mcp:consult -- "Reply only with: MCP OK"

MCP 决策验证

npm run mcp:verify -- "https://example.com" "The page identifies the seller."

MCP 付款成功时会打印：

• PAGAMENTO MCP: success
• 结算凭证
• 工具响应

MCP 买家绝不会打印私钥，并会拒绝任何符合以下情况的付款：

• 不在 Base 主网上；
• 未使用已配置的 Base USDC 合约；
• 超过 $0.05 USDC。

机器可读的付款后续步骤

GET /.well-known/x402 发现文档和每个成功的免费预检响应都会发布完整的后续操作 序列。兼容的 Agent 无需再推断首次未付款请求后该怎么做：

1. 执行免费预检并保留其 x-journey-id；
2. 发送经过验证但不带付款签名的请求；
3. 读取并验证 payment-required 要求；
4. 仅授权预期的网络、资产、金额和收款方；
5. 使用 x402 付款载荷重试完全相同的请求；
6. 验证交付结果和结算凭证。

REST 元数据建议使用 @x402/fetch；MCP 元数据建议使用 @x402/mcp。 付费响应还会通过 x-payment-instructions 链接回发现说明。此外，响应还会发布符合 RFC 8288 的 Link 标头，其中包含已注册的 payment 和 help 关系，使通用 HTTP Agent 无需依赖项目专属标头， 也能发现相同的机器可读后续步骤和可选反馈路径。此流程绝不会索取私钥、Railway 或 GitHub 凭证， 也不会索取 OpenAI 密钥。

可选转换反馈

每个付费 HTTP 或 MCP 响应都会公布 x-feedback-endpoint 以及允许使用的规范化原因、阶段和意图值。免费预检响应会在 feedback 区块中包含相同信息。反馈通过 POST /feedback 提交，不包含自由文本，也绝不会包含私钥、提示词、URL、页面内容或付款载荷。

三个买家接受：

--feedback-reason <research_only|no_wallet|unsupported_network|insufficient_funds|spending_not_authorized|price|insufficient_value|integration_error|other>
--feedback-stage <discovery|preflight|payment|execution|delivery>
--feedback-intent <research|analyze_page|verify_conditions|general_question|evaluate_service|other>

如果提供了 --feedback-reason，但未提供 --feedback-stage，阶段默认为 payment，且买家不会授权付款。HTTP 买家会先收到未签名的 402 挑战，提交明确反馈后停止。MCP 买家则会在免费预检后停止，并提交明确反馈，无需钱包。

示例：报告价格导致评估中止，不付款：

npm run analyze -- "https://example.com" "Summarize this page." --feedback-reason price --feedback-intent evaluate_service

若要在交付完成后提交明确反馈，请选择该阶段：

npm run mcp:consult -- "Reply only with: MCP OK" --feedback-reason other --feedback-stage delivery --feedback-intent general_question

买家只会自动提交 integration_error，且仅限客观检测到的技术故障，例如发现或预检失败、HTTP 5xx 结果、付费 MCP 工具错误，或付款后缺少结算凭证。它们绝不会推断 price、research_only、no_wallet 或其他人为或商业动机。

受控冒烟测试（不付款）

部署后，验证发现、预检、OpenAPI 反馈契约、规范化反馈提交、HTTP 402 挑战和反馈标头、HTTP 方法处理、MCP 初始化、工具发现以及 MCP x402 挑战：

npm run build
npm run smoke

使用 SERVICE_URL 指向其他部署。测试会使用一个持久的 x-journey-id，发送 User-Agent: Diogo-Smoke/1.2.9，验证 MCP x402 挑战公布的公共 HTTPS 端点具有 type=mcp 和正确的 toolName，并且绝不会创建或签署付款。

三个付款买家现在都会在付费请求前执行发现和免费预检，并在整个过程中使用相同的持久旅程 ID。设置 JOURNEY_ID 可复用现有旅程；否则，每个买家都会创建并打印一个旅程 ID。MCP 买家还要求广告中的价格、Base USDC、Base 主网以及配置的服务接收方完全匹配，之后才能签名。

漏斗可观测性

服务器会针对 MCP 工具尝试、x402 挑战、付款验证、执行、结算和最终工具结果发出结构化事件。它不会记录工具参数或付款载荷。结算日志会包含公开网络和交易标识符，以便统计并去重已完成的购买。

被拒绝的 MCP 请求会包含安全的协议诊断信息，例如方法、内容类型、Accept、JSON-RPC 结构以及 SDK 错误分类。所有事件都会在可用时包含请求和旅程关联字段。对已知付费工具的调用如果未能到达其付款包装器，还会额外发出 mcp_pre_payment_rejection，分类为无效方法、内容类型、JSON-RPC 封套、参数、传输/协议拒绝，或处理程序未被触发。参数值和付款载荷绝不会被记录。 OpenAI 使用事件会沿用相同的请求、旅程、客户端和来源关联信息。系统还会记录 Railway 的 X-Railway-Request-Id、边缘 POP 和请求开始时间，而客户端来源指纹则使用 Railway 稳定的 X-Real-IP 值，并通过 OBSERVABILITY_SALT 进行假名化处理。

部署

main 分支已连接到 Railway。每次成功推送都会触发新部署。Railway 使用：

npm run build
npm start

部署健康检查路径为 /health。

许可证

ISC