X402 Payment Gated Http

x402-mcp

面向 x402 protocol 的 MCP 服务。让 AI Agent（Claude、Cursor 等）自动发现并调用需要付款才能使用的 HTTP API。

仓库： merkleworks/x402-mcp

---

MCP 服务

此仓库提供一个 Model Context Protocol（MCP） 服务，使 AI Agent 能够使用 x402 protocol 调用需要付款才能使用的 HTTP API。

提供的工具：

• x402_http_request — 向需要通过 x402 protocol 付款的 API 发起 HTTP 请求。如果服务返回 402，此工具会解析挑战、构建付款、携带证明重试，并返回最终响应。

Agent 工作流示例：

agent → tool call → x402_http_request → 402 challenge → payment → retry → response

自动发现： MCP 感知框架无需手动提交到注册表即可发现此服务：

• 仓库描述文件： 仓库根目录下的 mcp.json（名称、描述、install: npx x402-mcp、工具）。
• npm： 使用 npx x402-mcp 运行；软件包关键词包括 mcp、model-context-protocol、ai-tools、x402。
• Well-known： 可将 .well-known/mcp.json 托管在 https://demo.x402.merkleworks.io/.well-known/mcp.json，以便基于域名发现。

---

x402 概述

x402 是一种通过 HTTP 402 Payment Required 要求为 HTTP API 支付小额费用的协议：

1. 请求 — 客户端调用 API。
2. 402 挑战 — 服务返回 402 Payment Required，并附带 X402-Challenge 标头（nonce UTXO、价格、收款方、过期时间）。
3. 付款 — 客户端构建 BSV 交易，可选择委托支付手续费，然后广播交易。
4. 重试 — 客户端携带 X402-Proof 标头重试请求。
5. 响应 — 服务验证证明并返回 API 响应。

此工作流让 API 无需预先注册或银行卡，即可按请求收取 satoshi 费用。

---

此 MCP 服务的功能

此服务提供 Model Context Protocol（MCP） 工具，供 AI Agent 使用：

• paid_http_request — 发送 HTTP 请求；如果服务返回 402，则运行完整的 x402 工作流（解析挑战 → 付款 → 携带证明重试），并返回最终响应。用于调用需要付款才能使用的 API 的主要工具。
• discover_x402_api — 列出可付费端点（从 /.well-known/x402 获取，或通过探测 402 响应发现）。
• pay_x402_endpoint — 以完整控制方式（方法、请求体、标头、委托方）调用已知的 x402 端点。
• parse_x402_challenge — 解码 X402-Challenge 标头。
• verify_x402_proof — 根据挑战和请求检查 X402-Proof。

Agent 使用 paid_http_request，即可完成单步操作：“调用此 URL；如果返回 402，则付款”。

---

安装

使用单条命令运行（推荐）：

npx x402-mcp

或全局安装：

npm install -g x402-mcp
x402-mcp

从源代码安装：

git clone https://github.com/merkleworks/x402-mcp.git
cd x402-mcp
npm install
npm run build
npm start

---

使用示例

Agent → 工具调用 → x402_http_request → x402 工作流（如果返回 402）→ API 响应

1. Agent 使用 url、method 以及可选的 headers 和 body 调用工具。
2. 服务发送 HTTP 请求。
3. 如果响应为 402，服务会解析挑战、构建付款、委托支付手续费或广播交易，然后携带证明重试。
4. 工具返回最终响应（状态、请求体，以及已付款时的付款交易 ID）。

---

工具调用示例

工具： x402_http_request

输入架构：

字段	类型	必填	描述
url	string	是	API 端点的完整 URL
method	string	否	HTTP 方法（默认：GET）
headers	object	否	可选的 HTTP 标头（键值字符串）
body	string or object	否	可选的请求正文（字符串或 JSON 对象）

示例（GET）：

{
  "tool": "x402_http_request",
  "input": {
    "url": "https://demo.x402.merkleworks.io/v1/expensive",
    "method": "GET"
  }
}

示例（带 JSON 正文的 POST）：

{
  "tool": "x402_http_request",
  "input": {
    "url": "https://api.example.com/v1/query",
    "method": "POST",
    "headers": { "Content-Type": "application/json" },
    "body": { "query": "example" }
  }
}

更多示例：examples/，包括 example_agent_call.json。

---

从 AI 客户端连接

Cursor

添加到 .cursor/mcp.json：

{
  "mcpServers": {
    "x402": {
      "command": "npx",
      "args": ["@merkleworks/x402-mcp"]
    }
  }
}

或使用本地构建：

{
  "mcpServers": {
    "x402": {
      "command": "node",
      "args": ["/path/to/x402-mcp/dist/server.js"]
    }
  }
}

Claude Desktop / Claude Code

添加到 MCP 配置中（例如 claude_desktop_config.json）：

{
  "mcpServers": {
    "x402": {
      "command": "npx",
      "args": ["@merkleworks/x402-mcp"]
    }
  }
}

通用 MCP 客户端（Node.js）

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "npx",
  args: ["@merkleworks/x402-mcp"],
});

const client = new Client({ name: "my-agent", version: "1.0.0" });
await client.connect(transport);

const result = await client.callTool("paid_http_request", {
  url: "https://demo.x402.merkleworks.io/v1/expensive",
  method: "GET",
});
console.log(result);

---

工具参考

工具	描述
paid_http_request	执行 HTTP 请求；如果返回 402，则运行 x402 流程并返回最终响应
discover_x402_api	发现可付费端点（/.well-known/x402 或探测）
pay_x402_endpoint	调用 x402 端点并完全控制（委托方、广播 URL 等）
parse_x402_challenge	解码 X402-Challenge 标头
verify_x402_proof	根据质询和请求验证 X402-Proof

---

协议摘要

1. 客户端请求受保护的端点。
2. 服务返回带有 X402-Challenge 的 402。
3. 客户端构建 BSV 交易，可选择使用委托方支付费用，然后广播。
4. 客户端使用 X402-Proof 重试。
5. 服务验证并返回响应。

此 MCP 服务实现了该流程，因此 Agent 无需手动操作即可为 API 调用付费。

---

配置

• pay_x402_endpoint（以及在付费时调用的 paid_http_request）默认使用请求 URL 的同源地址作为委托方。直接使用 pay_x402_endpoint 时，可通过 delegator_url / broadcast_url 覆盖。
• 发现清单格式：协议规范和 /.well-known/x402。

---

示例

• example_agent_call.json — 面向 Agent 的 paid_http_request 调用示例。
• discover-and-pay — 发现端点，然后为第一个端点付费并调用。运行：npx tsx examples/discover-and-pay.ts https://your-x402-api.example.com

---

MCP 注册表（mcp.json）

此仓库包含供 MCP 注册表（例如 mcp.so）使用的 mcp.json：名称、描述、仓库、安装命令和工具列表。

---

许可证

Apache-2.0