drain-mcp

DRAIN MCP サーバー

AI エージェントのための決済 — API キーも、クレジットカードも、サブスクリプションも不要です。

Handshake58 AI Marketplace 向けの MCP サーバーです。エージェントはサービスプロバイダーを検索し、自動的に支払いを行って、LLM 推論、ウェブスクレイピング、画像生成、検索など、あらゆるサービスを呼び出します。

2 つの決済プロトコルに対応しています。

• DRAIN — Polygon 上のペイメントチャネルです。一度開けば、複数のリクエストを送信でき、完了したら閉じられます。
• MPP — Tempo 経由のリクエストごとの決済です。各リクエストに対して個別に支払います。チャネルは不要です。

	DRAIN	MPP
セットアップ	チャネルを開く（ガス代 $0.02）	不要
リクエストごと	$0.0001–$0.01	プロバイダーによって異なります
最適な用途	大量のリクエストを行うセッション	単発のリクエスト、REST API
決済	Polygon 上の USDC	Tempo チェーン上の USDC

使用する場面

次のような場合は drain-mcp を使用してください。

• API キーなしで、あらゆるサービス（LLM、検索、スクレイピング、画像生成など）を呼び出す場合
• サブスクリプションやクレジットカードを使わず、USDC でリクエストごとに支払う場合
• 単一の統合インターフェースを通じて、30 以上のプロバイダーにアクセスする場合

次のような場合は drain-mcp を使用しないでください。

• 必要なサービスの API キーをすでに持っている場合
• タスクで外部サービスを必要としない場合

---

TL;DR - 最小限の実用ワークフロー

MPP プロバイダー（リクエストごと、チャネル不要）

1. drain_providers(protocol: "mpp")  → Find MPP providers
2. drain_provider_info(id)           → Read docs (essential for REST APIs)
3. mpp_chat(provider, messages)      → LLM providers (auto-pay via Tempo)
   — OR —
   mpp_request(url, body)            → REST API providers (auto-pay via Tempo)
4. drain_feedback(providerId, outcome) → Optional: report success/failure

DRAIN プロバイダー（ペイメントチャネル）

1. drain_providers(protocol: "drain") → Find DRAIN providers
2. drain_provider_info(id)            → Get provider details + usage docs
3. drain_balance()                    → Check USDC + POL
4. drain_approve()                    → Approve USDC spending (once)
5. drain_open_channel(...)            → Deposit USDC, get channelId
6. drain_chat(...)                    → Send requests (repeat as needed)
7. drain_cooperative_close(...)       → Close early, instant refund (when done)
   — OR after expiry —
8. drain_close_channel(...)           → Reclaim funds (after expiry)

---

チャネルを閉じるタイミング

• タスクが完了しましたか？ → drain_cooperative_close(channelId) を使用します。 未使用のデポジットが即座に返金されます。完了したら必ず実行してください。

• 近いうちにさらにリクエストを行う予定ですか？ → チャネルを開いたままにします。 閉じて開き直す必要はありません。ガス代を $0.04 節約できます。

• チャネルの期限が切れましたか？ → drain_close_channel(channelId) を使用します。 期限のタイムスタンプ後に、未使用の USDC を回収します。 資金は自動では返金されません。

目安： タスクが完了したら閉じます。作業中は開いたままにします。

---

すでに 402 が返されましたか？

MPP プロバイダー： drain-mcp は mppx/Tempo 経由で 402 を自動的に処理します。mpp_chat または mpp_request を使用するだけで、支払いは透過的に処理されます。

DRAIN プロバイダーは、支払いバウチャーが送信されない場合、ヘッダーとともに 402 Payment Required を返します。

ヘッダー	値
X-Payment-Protocol	drain-v2
X-Payment-Provider	プロバイダーのウォレットアドレス（ここにチャネルを開きます）
X-Payment-Contract	DRAIN コントラクトアドレス
X-Payment-Chain	137（Polygon Mainnet）
X-Payment-Signing	EIP-712 署名パラメーターの URL
X-Payment-Docs	プロバイダーのドキュメントエンドポイント

DRAIN のフロー：

1. プロバイダーのエンドポイントを呼び出す（バウチャーなし）→ ヘッダーとともに 402 を取得します
2. drain-mcp をインストールするか、X-Payment-Signing URL の署名 API を使用します
3. X-Payment-Provider アドレス宛てにチャネルを開きます
4. X-DRAIN-Voucher ヘッダーを付けてリクエストを再試行します

必要な情報はすべて 402 レスポンスに含まれています。事前登録は不要です。

---

ツールのリファレンス

検索

drain_providers

サービスプロバイダーを検索します。モデル名、カテゴリ、オンライン状態で絞り込めます。

{
  "model": "gpt-4o",
  "category": "scraping",
  "onlineOnly": true
}

カテゴリ：llm、image、audio、code、scraping、vpn、multi-modal、other

drain_provider_info

利用手順（ドキュメント）など、プロバイダーの詳細を取得します。ドキュメントでは、そのプロバイダーへのリクエストの形式について説明しています。

{ "provider": "hs58-openai" }

ウォレット

drain_balance

ウォレットの USDC 残高、ガス代用の POL、および DRAIN コントラクトの使用許可を確認します。

drain_approve

DRAIN コントラクトによる USDC の使用を承認します。チャネルを開く前に、一度実行する必要があります。

{ "amount": "100" }

チャネル

drain_open_channel

ペイメントチャネルを開きます。指定した期間、USDC をロックします。

{
  "provider": "hs58-openai",
  "amount": "5.00",
  "duration": "24h"
}

チャネル ID、有効期限、プロバイダーの利用ドキュメントを返します。

drain_channel_status

チャネルのデポジット、支出額、残高、有効期限を確認します。

drain_channels

ステータス（active/expired/closed）とともに、把握しているすべてのチャネルを一覧表示します。閉じる必要がある、期限切れのチャネルを見つけられます。

使用方法（DRAIN）

drain_chat

DRAIN チャネルを通じて有料リクエストを送信します。すべての DRAIN プロバイダータイプで利用できます。

• LLM プロバイダー： 標準的なチャットメッセージ
• 非 LLM プロバイダー： ユーザーメッセージのコンテンツに JSON ペイロードを指定します（プロバイダーのドキュメントを確認してください）

{
  "channelId": "0x...",
  "model": "gpt-4o",
  "messages": [{"role": "user", "content": "Hello"}]
}

使用方法（MPP）

mpp_chat

MPP LLM プロバイダーにチャットリクエストを送信します。Tempo によって自動的に決済されるため、チャネルもセットアップも必要ありません。

{
  "provider": "provider-id-or-url",
  "messages": [{"role": "user", "content": "Hello"}],
  "model": "optional-model-id"
}

mpp_request

MPP REST API サービス（Tavily、Brave、Wolfram など）にリクエストを送信します。Tempo によって自動的に決済されます。

{
  "url": "https://tavily.mpp.paywithlocus.com/tavily/search",
  "body": {"query": "AI agents", "max_results": 5}
}

正しいエンドポイントパスとリクエスト形式を確認するため、まずプロバイダーのドキュメント（drain_provider_info）を読んでください。

品質フィードバック

drain_feedback

プロバイダー（DRAIN または MPP）の利用後に、成功または失敗を報告します。マーケットプレイスの品質スコアリングシステムに反映されます。

{
  "providerId": "provider-id",
  "outcome": "success",
  "reason": "accurate_result"
}

決済

drain_cooperative_close

プロバイダーの同意を得てチャネルを早期に閉じます。タスクが完了したらこれを使用してください。未使用のデポジットが即時に返金されます。有効期限まで待つ必要はありません。

{ "channelId": "0x..." }

drain_close_channel

期限切れのチャネルを閉じて、未使用の USDC を回収します。チャネルの有効期限のタイムスタンプを過ぎている場合に使用してください。

{ "channelId": "0x..." }

---

経済性の例

GPT-4o チャネルを開設する場合：

Gas to open channel:     $0.02   (one-time)
Deposit:                 $0.50   (refundable remainder)
Per request:            ~$0.001755
Requests possible:      ~285

Cost for 10 requests:    $0.02 gas + $0.01755 usage = $0.04
Refund after close:      $0.50 - $0.01755 = $0.48
Gas to close:            $0.02

• プロトコル手数料：プロバイダーへの請求額に対して 2％（オンチェーン）
• セッション手数料：なし
• リアルタイムの料金：GET https://handshake58.com/api/mcp/providers

---

プロバイダーのカテゴリ

プロバイダーは LLM チャットに限定されません。各プロバイダーには category フィールドがあり、リクエスト形式を説明するドキュメントのエンドポイントが用意されています。

カテゴリ	説明	メッセージ形式
llm	言語モデル（GPT-4o、Claude、Grok、Gemini）	標準的なチャットメッセージ
image	画像生成	ユーザーコンテンツ内の JSON（ドキュメントを参照）
audio	音声／TTS／STT	ユーザーコンテンツ内の JSON（ドキュメントを参照）
code	コード生成	標準的なチャットまたは JSON（ドキュメントを参照）
scraping	ウェブスクレイピング、データ抽出	ユーザーコンテンツ内の JSON（ドキュメントを参照）
vpn	VPN サービス	ユーザーコンテンツ内の JSON（ドキュメントを参照）
multi-modal	マルチモーダルモデル	標準的なチャットメッセージ
other	その他すべて	必ずドキュメントを確認してください

ルール：llm 以外のカテゴリでは、まず drain_provider_info を呼び出してドキュメントを読んでください。

---

判断フロー

プロトコルの選択

What provider do I want?
├── MPP provider (protocol="mpp")
│   ├── mppType="llm" → mpp_chat(provider, messages)
│   └── mppType="rest" → mpp_request(url, body)
│   └── Done. Payment was automatic.
│
└── DRAIN provider (protocol="drain")
    └── See DRAIN flow below

DRAIN セッションの開始

Do I have an active channel?
├── YES → Use drain_chat() with existing channelId
└── NO →
    ├── drain_balance() → Do I have USDC?
    │   ├── NO → Cannot proceed. Need USDC on Polygon.
    │   └── YES →
    │       ├── drain_providers() → Find provider
    │       │   ├── NO providers → Cannot proceed.
    │       │   └── Found provider →
    │       │       ├── drain_approve() → First time only
    │       │       └── drain_open_channel() → Get channelId
    │       │           └── drain_chat() → Send requests

DRAIN セッションの終了

Am I done with this task?
├── YES → drain_cooperative_close(channelId) → Instant refund
└── NO →
    ├── More requests soon? → Keep channel open
    └── Channel expired? → drain_close_channel(channelId) → Reclaim funds

金額と期間の選択

用途	金額	期間
簡単なテスト／単一のクエリ	$0.50 - $1	1h
短いタスク（少数のクエリ）	$2 - $5	4h
長時間のセッション	$5 - $20	24h
長時間稼働するエージェント	$20 - $100	7d

エラーへの対処

"Insufficient balance"
→ Need more USDC. Check drain_balance().

"Insufficient allowance"
→ Run drain_approve().

"Channel not found"
→ channelId is wrong or channel was closed. Open new channel.

"Channel expired"
→ For drain_chat: Open a new channel.
→ For drain_close_channel: Expected. Proceed with close.

"Insufficient channel balance"
→ Channel deposit used up. Open new channel with more funds.

"Provider offline"
→ Use drain_providers() to find alternative provider.

---

セットアップ

1. インストール

npm install -g drain-mcp

2. ウォレットの作成（ローカル）

自分のマシンでキーを生成します。ネットワーク経由で送信されることはありません。

node -e "const w=require('ethers').Wallet.createRandom();console.log('Address:', w.address, '\nKey:', w.privateKey)"

3. ウォレットへの入金

ウォレットアドレスに Polygon Mainnet 上の $1–5 USDC を送金してください。 少額専用のウォレットを使用し、メインのウォレットは決して使用しないでください。

POL は不要です。ウォレットに $5 以上の USDC があれば、ガス代が無料で提供されます。

curl -X POST https://handshake58.com/api/gas-station \
  -H "Content-Type: application/json" \
  -d '{"address": "0x_your_wallet_address"}'

0.1 POL（約 1 万件のトランザクション）が付与されます。送信されるのは公開アドレスのみです。

4. MCP クライアントの設定

{
  "mcpServers": {
    "drain": {
      "command": "drain-mcp",
      "env": { "DRAIN_PRIVATE_KEY": "0x..." }
    }
  }
}

環境変数

変数	必須	デフォルト	説明
DRAIN_PRIVATE_KEY	はい	—	Polygon ウォレットの秘密鍵（MPP／Tempo にも使用）
DRAIN_CHAIN_ID	いいえ	137	137（Polygon）または 80002（Amoy テストネット）
DRAIN_RPC_URL	いいえ	Public RPC	カスタム Polygon RPC エンドポイント
DRAIN_MPP_MAX_DEPOSIT	いいえ	1	MPP セッションのデポジットあたりの最大 USDC 額

---

セキュリティとプライバシー

キーの取り扱い

DRAIN_PRIVATE_KEY はローカルの MCP プロセスによってメモリに読み込まれます。以下の用途に使用されます。

1. DRAIN チャネルの EIP-712 バウチャーへの署名（オフチェーン、ネットワーク呼び出しなし）
2. オンチェーントランザクションへの署名（ローカルで署名し、署名のみをブロードキャスト）
3. MPP リクエストの Tempo 支払いへの署名（mppx が処理し、ローカルで署名）

キーがサーバーに送信されることはありません。プロバイダーはオンチェーンの状態と照合して署名を検証します。

支出限度額

DRAIN： スマートコントラクトによってエクスポージャーが上限設定されます。

• 最大支出額＝チャネルのデポジット（任意の金額を設定できます）
• チャネルには固定の有効期間があります（任意に設定できます）
• 有効期限後、未使用の資金は drain_close_channel で回収できます

MPP： 各リクエストは、プロバイダーが提示する料金で個別に支払われます。事前のデポジットは不要です。

どちらのプロトコルも、継続的な請求や保存済みの支払い方法はありません。

お使いのマシンから送信されるデータ

• handshake58.com への公開 API クエリ（プロバイダー一覧、設定、チャネルの状態）
• プロバイダーへのリクエストメッセージ（プロバイダーの apiUrl に送信され、Handshake58 には送信されません）
• 署名済みの支払いバウチャー（暗号署名が含まれ、キーは含まれません）
• 署名済みオンチェーントランザクション（Polygon RPC にブロードキャスト）

ローカルに保持されるデータ

• 秘密鍵（送信されることはありません）
• すべての暗号処理（署名はプロセス内で行われます）

外部エンドポイント

MCP サーバーが行うすべてのネットワークリクエスト：

エンドポイント	メソッド	送信データ	キーの送信？
handshake58.com/api/mcp/providers	GET	なし（公開カタログ）	いいえ
handshake58.com/api/directory/config	GET	なし（手数料ウォレットを読み込み）	いいえ
handshake58.com/api/channels/status	GET	channelId（公開オンチェーンデータ）	いいえ
handshake58.com/api/gas-station	POST	ウォレットアドレス	いいえ
handshake58.com/api/telemetry	POST	プロバイダー ID、レイテンシー、ステータス、コスト	いいえ
handshake58.com/api/feedback	POST	プロバイダー ID、結果	いいえ
Provider apiUrl /v1/docs	GET	なし（使用方法のドキュメントを取得）	いいえ
Provider apiUrl /v1/chat/completions	POST	リクエストメッセージ＋署名済みバウチャー（DRAIN）	いいえ
Provider apiUrl /v1/close-channel	POST	channelId＋クローズ署名	いいえ
MPP provider endpoint	POST	リクエスト本文＋Tempo 支払い（mppx 経由）	いいえ
Polygon RPC (on-chain tx)	POST	署名済みトランザクション	いいえ

安全対策

• 専用ウォレットを用意し、$1–5 USDC を入れてください。メインのウォレットは絶対に再利用しないでください。
• キーは必ずローカルで生成してください。キーはお使いのマシン上に保持されます。
• オープンソース：github.com/kimbo128/DRAIN（MIT ライセンス）
• 少額のデポジットでチャネルを開き、使い終わったら速やかに閉じてください。

---

リンク

• NPM：https://www.npmjs.com/package/drain-mcp
• GitHub：https://github.com/kimbo128/DRAIN
• マーケットプレイス：https://handshake58.com
• プロバイダーディレクトリ：https://handshake58.com/directory
• コントラクト：0x0C2B3aA1e80629D572b1f200e6DF3586B3946A8A（Polygon Mainnet）