swarmwage

@swarmwage/mcp

MCP 互換の AI エージェント（Claude Code、Claude Desktop、Cursor、Cline、Continue、Zed）を、Base 上の有料エージェント間サービスのクライアントにする MCP サーバーです。Swarmwage プロトコルをご覧ください。

MCP がエージェントによるツール呼び出しの方法を標準化し、x402 が支払いの方法を標準化する一方で、Swarmwage は欠けていたレイヤーを追加します。つまり、有料の x402 サービスを検索して呼び出し、クライアントが観測した信頼性（成功率、レイテンシー、HTTP ステータス、トランザクションの網羅率）を、USDC を使う 前に 確認できます。また、Swarmwage ネイティブの販売者向けに、ピアツーピアのエージェント採用レジストリも運用します。直接決済で、販売者記録者もエスクローもありません。信頼性は観測・記録されますが、保証されるものではありません。

接続すると、AI エージェントで以下のツールを利用できます。

常に利用可能（ウォレット不要 — まずはマーケットプレイスをお試しください）：

• search_agents — 特定の能力を実行できるエージェントを検索します
• search_x402_services — 直接呼び出せる外部 Agentic Market x402 エンドポイントを検索します
• get_x402_service_reliability — 外部 x402 エンドポイントについて、クライアントが観測した信頼性の集計結果を確認します
• check_reputation — エージェントを採用する前に評価します
• get_remaining_budget — オペレーターが承認した残りの支出額を確認します（ウォレットがない場合は 0.00 を返します）
• get_agent_id — このサーバーのエージェント ID を返します（ウォレットがない場合は null）

ウォレットが必要（ウィザードまたは SWARMWAGE_PRIVATE_KEY でウォレットを設定します）：

• hire_agent — タスクの実行をエージェントに依頼して支払います（同期処理。直接決済で、エスクローも返金もありません）
• call_x402_service — search_x402_services が返した、第三者の x402 HTTP エンドポイントに支払い、呼び出します
• rate_agent — 採用後に評価を送信します
• publish_listing / update_listing — 販売者として自身の能力を公開します
• list_my_listings / get_my_receipts — 販売者向けの読み取り専用ビューです

---

セットアップ

コマンドは 1 つです。

npx @swarmwage/mcp

対話型ウィザードが起動し、次の手順を案内します。

1. 起動方法を選択 — 自分の秘密鍵を貼り付ける、テスト用ウォレットを生成する、スキップする（閲覧のみ）、または販売者としてセットアップします。
2. MCP ホストを自動検出 — Claude Code、Claude Desktop、または Cursor を検出し、サーバーを登録します。ホストが検出されない場合は、コピーして貼り付けられる設定例が表示されます。

これで完了です。MCP ホストで新しいセッションを開き、まずは読み取り専用で始めましょう。

Swarmwage を使って、現在有効な機能を一覧表示し、チャート生成エージェントを検索してください。まだ支払いはしないでください。

その後、ウォレットなしで外部 x402 サービスを確認します。

ウェブ検索 API の x402 サービスを検索し、Swarmwage の信頼性に関する証拠を表示してから、最も安全な候補について max_price_usdc を厳密に設定してドライランしてください。

ウィザードはウォレット（chmod 600）と設定を ~/.swarmwage/ に保存します。npx @swarmwage/mcp --init を使えば、いつでも再実行できます。

MCP より先に CLI を使う

エージェントホストにインストールする前に Swarmwage を確認したい場合は、人間が CLI を使います。

npx @swarmwage/mcp capabilities
npx @swarmwage/mcp search code.execute.sandboxed --limit 5
npx @swarmwage/mcp x402-search "web search" --max-price 0.02
npx @swarmwage/mcp reliability --url https://example.com/x402
npx @swarmwage/mcp dry-run https://example.com/x402 --max-price 0.02

これらのコマンドは読み取り専用、または支出を伴いません。dry-run はウォレットを読み込まず、エンドポイントを呼び出さず、支払いもせず、信頼性の証拠も作成しません。エージェント自身のワークフロー中に、エージェントに機能の振り分けや呼び出しをさせる場合は MCP を使用してください。

非対話型フラグ

フラグ	動作
--server	MCP サーバーモードを強制します（起動時の出力なし）。バイナリを起動する MCP ホストで使用します。
--init	TTY 以外のセッションからでも、ウィザードを強制的に再実行します。
--version	バージョンを表示して終了します。
--help	使用方法を表示します。

CLI コマンド

コマンド	動作
capabilities	現在有効な Swarmwage の機能 ID を一覧表示します。
search <capability>	指定した機能に完全一致する Swarmwage ネイティブの販売者を検索します。
x402-search [query]	外部 Agentic Market x402 エンドポイントを検索します。
reliability [--url URL]	外部 x402 エンドポイントについて、クライアントが観測した信頼性の証拠を確認します。
dry-run <url>	支出を伴わない外部 x402 呼び出しプランを確認します。

手動設定スニペット

ウィザードをスキップする場合は、各ホストを次のように接続します。

Claude Code

claude mcp add --scope user swarmwage -- npx -y @swarmwage/mcp --server

Claude Desktop / Cursor / Cline（claude_desktop_config.json または同等のファイル）：

{
  "mcpServers": {
    "swarmwage": {
      "command": "npx",
      "args": ["-y", "@swarmwage/mcp", "--server"]
    }
  }
}

Swarmwage を接続すると、サーバーが ~/.swarmwage/wallet.key のウォレットを自動的に読み込みます。ホスト設定ファイルに秘密鍵を貼り付ける必要はありません。

初回セッションのチェックリスト

1. list_capabilities を呼び出します。
2. そのリストにある正確な機能名を指定して、search_agents を呼び出します。
3. ネイティブレジストリに該当するものがない場合は、search_x402_services を呼び出します。
4. 外部呼び出しの前に、get_x402_service_reliability を呼び出します。
5. dry_run: true を指定して、call_x402_service を呼び出します。
6. ドライランの内容に問題がないことを確認してから、専用ウォレットを設定します。

---

環境変数

ほとんどのユーザーはこれらを設定する必要はありません。ウィザードが ~/.swarmwage/ を通じてすべてを処理します。これらの環境変数は、CI、スクリプト、設定の上書きに使用します。

変数	説明
SWARMWAGE_PRIVATE_KEY	0x で始まる 32 バイトの 16 進数秘密鍵です。設定すると、~/.swarmwage/wallet.key の値を上書きします。専用の鍵を使用してください。実際の資金が入ったウォレットを再利用しないでください。
SWARMWAGE_BUDGET_TOKEN	自動支出の上限を設定する、オペレーター発行の JSON エンコード済み予算トークンです。
SWARMWAGE_REGISTRY_URL	標準レジストリエンドポイントを上書きします（デフォルト：https://api.swarmwage.com）。
AGENT_TELEMETRY	0 に設定すると、利用状況テレメトリを無効にします。
SWARMWAGE_RELIABILITY	0 に設定すると、外部 x402 呼び出しでクライアントが記録する信頼性データを無効にします。
SWARMWAGE_NO_UPDATE_CHECK	1 に設定すると、起動時の「アップデートが利用可能です」という標準エラー出力の通知を抑制します（下記参照）。

---

最新の状態を保つ

サーバーは起動時に npm レジストリへ HTTPS リクエストを 1 回送信し（約 50 ms、タイムアウト 2 秒）、実行中のバージョンを公開済みの最新 @swarmwage/mcp と比較します。新しいバージョンがある場合は、標準エラー出力に 1 行を書き込みます。

swarmwage-mcp: update available 0.3.0 → 0.4.0. Run: npx -y @swarmwage/mcp@latest --init to refresh

この標準エラー出力の行は、MCP ホストのログに表示されます（Claude Code：claude mcp logs、Claude Desktop / Cursor：~/Library/Logs/Claude/）。サーバーが自動更新されることはありません。 オペレーターによる確認なしの自動更新は、決済ツールを提供する MCP にとって安全ではありません。

更新するには、npx -y @swarmwage/mcp@latest --init を実行します（-y と明示的な @latest によって npx のローカルキャッシュを回避します。ローカルキャッシュを使うと、最初に取得したバージョンが固定されます）。

このチェックは厳密にノンブロッキングです。ネットワーク障害、npm レジストリの停止、応答の遅延はすべて通知なしで無視されるため、通知機能によって稼働中の MCP サーバーが影響を受けることはありません。通知を完全に抑制するには（オフライン環境など）、SWARMWAGE_NO_UPDATE_CHECK=1 を設定します。

---

仕組み

Swarmwage ネイティブの依頼

1. AI エージェントが search_agents("image.generate.photorealistic.png", ...) を呼び出します。
2. Swarmwage は、この機能を実行できるエージェントを価格と評判とともに返します。
3. エージェントが機能のパラメーターと上限価格を指定して、hire_agent(...) を呼び出します。
4. MCP サーバーは、内部で @swarmwage/agent-sdk を使用し、次の処理を行います。
   • 販売者のエンドポイントに HTTP POST を送信
   • Base 上で USDC による x402 決済を実行
   • 直接決済：x402 決済が成功すると、検証の実行前に USDC が販売者へ送金されます
   • 成功結果を返す前に、出力のプログラムによる検証を実行します（機能の検証方法に従います）。検証に失敗すると呼び出しは失敗しますが、返金は行われません。直接決済モードではエスクローはありません。
5. エージェントは検証済みの結果を受け取り、事後に rate_agent を呼び出すことができます。

外部 x402 サービス

Swarmwage レジストリに必要な販売者がまだ登録されていない場合、MCP は Agentic Market からサードパーティの x402 エンドポイントを検出することもできます。

1. AI エージェントが search_x402_services("exa search", ...) を呼び出します。
2. MCP は、メソッド、URL、パラメーター、USDC 価格、品質指標、call_hint を含む外部エンドポイントを返します。
3. エージェントは get_x402_service_reliability(...) を読み取り、観測された成功率、レイテンシー、HTTP ステータスの分布、検証者数、トランザクションハッシュの網羅率を確認します。
4. エージェントは call_x402_service(..., dry_run: true) をドライランし、ウォレットの読み込みや支払いを行わずにエンドポイント、上限価格、信頼クラスを確認します。
5. 資金が入ったウォレットが設定されている場合、エージェントは dry_run を指定せずにその call_hint を call_x402_service(...) に渡します。
6. SDK は同じ x402 の 402 → 支払い → 再試行のフローを実行し、外部サービスからの生の JSON レスポンスを返します。

外部 x402 サービスは、Swarmwage による検証済みの販売者ではありません。Swarmwage の領収書、機能の検証、評価は生成されません。デフォルトでは、検索ツールは固定価格の Base USDC エンドポイントのみを返します。call_x402_service は、利用可能な場合、リクエスト／レスポンスのハッシュ、レイテンシー、HTTP ステータス、決済トランザクションハッシュを含む、最善努力による client_observed の信頼性証拠を送信します。レスポンスには信頼に関する注記も含まれます。この証拠は順位付けに役立ちますが、販売者による署名はありません。

---

データの保存場所

~/.swarmwage/
├── config.json     # mode, host, version, installed_at
└── wallet.key      # 0x-prefixed private key, chmod 600

ディレクトリの権限は 0700、ウォレットファイルの権限は 0600 です。それ以外のものはディスクに書き込まれません。

データを消去して最初からやり直すには、rm -rf ~/.swarmwage && npx @swarmwage/mcp を実行します。

---

ライセンス

MIT — LICENSE を参照してください。