three.ws Agent Payments

@three-ws/agentcore-payments-mcp

three.ws Agent Payment Sessions 用の MCP サーバーです。秘密鍵を公開せずに、エージェントの x402 支出を管理します。

コンセプト

エージェントはウォレットを保持しません。支出を提案します。ガバナンスがポリシーを適用します。

Payment Session は、three.ws クレジットから一度だけ入金する予算枠です。セッションのベアラートークンをエージェントに渡すと、エージェントはこのサーバー経由で有料の x402 エンドポイントを呼び出します。すべてのトランザクションには、プラットフォームのウォレットが署名します。セッションの許可リスト、1 トランザクションあたりの上限額、合計予算はサーバー上でアトミックに適用されるため、エージェントが予算を超過することはありません。

クイックスタート

# Configure
export THREE_WS_SESSION="<the value of your __Host-sid cookie>"
export PAYMENT_SESSION_TOKEN="pss_<session-id>_<random>"

# Run
npx @three-ws/agentcore-payments-mcp

MCP クライアントの設定（~/.cursor/mcp.json、Claude Desktop など）：

{
  "mcpServers": {
    "three-ws-payments": {
      "command": "npx",
      "args": ["-y", "@three-ws/agentcore-payments-mcp"],
      "env": {
        "THREE_WS_SESSION": "<the value of your __Host-sid cookie>",
        "PAYMENT_SESSION_TOKEN": "pss_..."
      }
    }
  }
}

環境変数

変数	必須	説明
THREE_WS_SESSION	セッション管理ツールで必要	セッションの作成／一覧表示／キャンセルに使用する、ブラウザー Cookie __Host-sid の値（__Host-sid= のプレフィックスは不要です。サーバーが Cookie を送信します）
PAYMENT_SESSION_TOKEN	pay_with_session のデフォルト値として必要	セッション作成時に返されるベアラートークンです。インラインでトークンが指定されない場合に、デフォルト値として渡されます
THREE_WS_BASE	いいえ	ベース URL（デフォルト：https://three.ws）
THREE_WS_TIMEOUT_MS	いいえ	リクエストのタイムアウト（ミリ秒、デフォルト：30000）

ツール

create_payment_session

クレジットから入金して新しいセッションを作成します。

{
  "budget_usd": 10.00,
  "label": "Research agent — June sprint",
  "expiry_seconds": 86400,
  "max_per_tx_usd": 0.50,
  "allowed_hosts": ["api.example.com", "data.provider.io"],
  "network": "solana"
}

{ session, token } を返します。トークンは一度しか表示されないため、すぐに保存してください。

pay_with_session

セッショントークンを使用して x402 エンドポイントに支払います。プラットフォームのウォレットが署名し、セッションのポリシーが適用されます。

{
  "url": "https://api.example.com/data",
  "method": "GET",
  "session_token": "pss_...",
  "idempotency_key": "run-42-fetch-data"
}

トランザクションハッシュ、エクスプローラーのリンク、更新後の予算を含む { ok, paid, result, payment, session } を返します。

session_token が省略された場合は、PAYMENT_SESSION_TOKEN 環境変数が使用されます。

check_payment_session

セッションの予算、ステータス、最近の支払いを確認します。

{ "session_id": "...", "include_executions": true }

list_payment_sessions

認証済みユーザーのすべてのセッションを、集計統計とともに一覧表示します。

{ "status": "active", "limit": 20 }

cancel_payment_session

セッションをキャンセルし、未使用の予算をクレジットに払い戻します。

{ "session_id": "..." }

ネットワークのサポート

セッションの network	プラットフォームの支払元	USDC コントラクト
solana（デフォルト）	X402_AGENT_SOLANA_SECRET_BASE58	Solana メインネット USDC
base	X402_EVM_AGENT_PRIVATE_KEY	Base メインネット USDC（0x8335…）

@three-ws/x402-mcp との統合

@three-ws/x402-mcp の既存の pay_and_call ツールが、session_token を直接受け取れるようになりました。

{
  "url": "https://api.example.com/endpoint",
  "session_token": "pss_...",
  "confirm": true
}

これにより、ローカルで署名する代わりに、/api/pay/execute 経由で支払いが行われ、セッションのガバナンスポリシーが適用されます。

例

実行可能で、支払いを伴わない例は examples/ にあります。

node examples/list-tools.mjs       # every tool with its schema and safety annotations
node examples/plan-a-session.mjs   # read live x402 prices, print the policy to authorize

どちらの例もウォレットを保持したり、認証情報を読み取ったり、pay_with_session を呼び出したりしないため、署名も支出も発生しません。plan-a-session.mjs はぜひ参考にしたい習慣を示しています。承認する予算を決める前に、エンドポイントの実際の料金を確認してください。examples/README.md を参照してください。

セッションのライフサイクル

create (budget debited from credits)
  └─ active → pay_with_session calls spend against budget
       ├─ exhausted (budget fully consumed)
       ├─ expired (TTL elapsed — cron refunds remaining budget)
       └─ cancelled (manual — remaining budget refunded immediately)

プログラムからの使用

パッケージのエントリーポイントは、すべてのツール定義（name、title、description、inputSchema、annotations、handler）を含む TOOLS と、トランスポートを接続せずに完全に登録された McpServer を返す buildServer() をエクスポートします。インポート時に副作用はなく、認証情報も必要ありません。そのため、独自のホストにこれらのツールをマウントしたり、オフラインで機能を確認したりできます。認証情報が必要になるのは、ハンドラーが実際に実行されたときだけです。

// run with: THREE_WS_SESSION=<your __Host-sid value> node this-file.mjs
import { TOOLS, buildServer } from '@three-ws/agentcore-payments-mcp';

for (const tool of TOOLS) {
	const kind = tool.annotations.readOnlyHint ? 'read ' : 'write';
	console.log(`${kind} ${tool.name}`);
}

// A tool handler is a plain async function against the live API.
const list = TOOLS.find((t) => t.name === 'list_payment_sessions');
console.log(await list.handler({ limit: 3 }));

// Or hand the whole registered server to your own MCP transport.
buildServer();

セキュリティ特性

• キーの非公開：セッショントークンは、有効期限付きの HMAC 署名済み許可証です。これが侵害された場合、攻撃者が使用できるのは、許可されたホストで残りの予算までです。それ以上はできません。
• 予算のアトミックな適用：同時に発生した支払いでは、SQL の UPDATE … WHERE remaining >= amount RETURNING を使用するため、2 つの同時リクエストが合計で予算を超過することはありません。
• 許可リスト：allowed_hosts が設定されている場合、ゲートウェイは署名する前に、リストにないホストへのリクエストを拒否します。
• 1 回あたりの上限：max_per_tx_usd により、1 回の高額な支払いで予算全額が消費されることを防ぎます。
• SSRF 対策：すべての x402 対象 URL は、支払いの署名前に公開 IP アドレスの許可リストと照合して検証され、サーバー側で DNS 解決されます。