X402 Payment Gated Http

x402-mcp

x402 プロトコル用の MCP サーバーです。AI エージェント（Claude、Cursor など）が、支払いが必要な HTTP API を自動的に検出して呼び出せるようにします。

リポジトリ： merkleworks/x402-mcp

---

MCP サーバー

このリポジトリは、AI エージェントが x402 プロトコルを使用して、支払いが必要な HTTP API を呼び出せるようにする Model Context Protocol（MCP） サーバーを提供します。

公開されるツール：

• x402_http_request — x402 プロトコルによる支払いが必要な API に HTTP リクエストを実行します。サーバーが 402 を返した場合、ツールはチャレンジを解析して支払いを作成し、支払いの証明を添えて再試行し、最終的なレスポンスを返します。

エージェントのフロー例：

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 はリクエストごとにサトシ単位で課金できます。

---

この MCP サーバーの機能

このサーバーは Model Context Protocol（MCP） ツールを公開し、AI エージェントが次の操作を行えるようにします。

• 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 を検証します。

エージェントは、単一の「この URL を呼び出し、402 が返った場合は支払う」ステップに paid_http_request を使用します。

---

インストール

単一のコマンドで実行（推奨）：

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

---

使用例

エージェント → ツール呼び出し → x402_http_request → x402 フロー（402 の場合）→ API レスポンス

1. エージェントが 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 サーバーはこのフローを実装しているため、エージェントは手動操作なしで API 呼び出しの支払いを行えます。

---

設定

• pay_x402_endpoint（および、支払いを行う場合の paid_http_request）では、デフォルトでデリゲーターにリクエスト URL と同じオリジンを使用します。pay_x402_endpoint を直接使用する場合は、delegator_url / broadcast_url で上書きできます。
• 検出マニフェストの形式: プロトコル仕様 および /.well-known/x402。

---

例

• example_agent_call.json — エージェント向けの 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