Clawallex MCP Server

@clawallex/mcp-server

Clawallex 決済 API 用の MCP サーバーです。USDC であらゆるものを支払えます。Clawallex がステーブルコインの残高を、オンラインのあらゆるチェックアウトで使えるバーチャルカードに変換します。

クイックスタート

1. インストール

npm install -g @clawallex/mcp-server

または、npx 経由で直接実行できます（インストール不要）。

2. API 認証情報を取得する

Clawallex に登録し、API Key ペア（api_key + api_secret）を作成します。

3. AI クライアントを設定する

クライアントを選択し、設定を追加します。

Claude Desktop

claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "clawallex": {
      "command": "npx",
      "args": ["@clawallex/mcp-server"],
      "env": {
        "CLAWALLEX_API_KEY": "your_api_key",
        "CLAWALLEX_API_SECRET": "your_api_secret"
      }
    }
  }
}

Claude Code

claude mcp add --scope local clawallex -- npx @clawallex/mcp-server \
  --api-key your_api_key \
  --api-secret your_api_secret

Codex CLI

~/.codex/config.toml または .codex/config.toml に追加します。

[mcp_servers.clawallex]
command = "npx"
args = [
  "@clawallex/mcp-server",
  "--api-key",
  "your_api_key",
  "--api-secret",
  "your_api_secret",
]

Gemini CLI

~/.gemini/settings.json に追加します。

{
  "mcpServers": {
    "clawallex": {
      "command": "npx",
      "args": [
        "@clawallex/mcp-server",
        "--api-key", "your_api_key",
        "--api-secret", "your_api_secret"
      ]
    }
  }
}

OpenCode

opencode.json に追加します。

{
  "mcp": {
    "clawallex": {
      "type": "local",
      "command": ["npx", "@clawallex/mcp-server", "--api-key", "your_api_key", "--api-secret", "your_api_secret"],
      "enabled": true
    }
  }
}

4. 接続を初期化する

設定後、AI エージェントに次のように伝えます。

「clawallex_setup を実行して接続を確認してください」

clawallex_setup は API Key を検証し、データ分離のための client_id を自動的に紐付けます。この操作は一度だけ必要です。

5. 使用を開始する

1 回限りの支払い：

「OpenAI API クレジットに 50 ドル支払って」

エージェントが clawallex_pay を呼び出す → バーチャルカードを作成 → get_card_details → decrypt_card_data → チェックアウトフォームに入力します。

サブスクリプション：

「AWS の月額請求用に 100 ドルのカードを設定して」

エージェントが clawallex_subscribe を呼び出す → リチャージ可能なカードを作成 → 残高が少なくなったら clawallex_refill を呼び出します。

6. 動作確認

すべてが正常に動作することを確認します。

clawallex_setup     → should show "ready" with bound client_id
get_wallet          → should return wallet balance
list_cards          → should return card list (empty if no cards yet)

一般的なフロー

支払いフロー（モード A — ウォレット残高）

1. clawallex_setup                           → verify connection & bind identity
2. get_wallet                                → check USDC balance
3. clawallex_pay({ amount, description })    → create a one-time virtual card
4. get_card_details({ card_id })             → get encrypted card data
5. decrypt_card_data({ nonce, ciphertext })  → decrypt PAN/CVV for checkout

サブスクリプションフロー

1. clawallex_setup                                          → verify connection
2. get_wallet                                               → check USDC balance
3. clawallex_subscribe({ initial_amount, description })     → create reloadable card
4. get_card_details({ card_id })                            → get card number
5. clawallex_refill({ card_id, amount })                    → top up when needed

ツール

高レベル（推奨）

ツール	説明
clawallex_setup	接続状態を確認し、エージェントの ID を紐付けます
clawallex_pay	1 回限りの支払い — 使い捨てバーチャルカードを作成します
clawallex_subscribe	定期サブスクリプション — リチャージ可能なカードを作成します
clawallex_refill	サブスクリプションカードの残高を補充します

ID と紐付け

ツール	説明
whoami	現在の API Key の紐付け状態を照会します（読み取り専用）
bootstrap	この API Key に client_id を紐付けます

ウォレットと照会

ツール	説明
get_wallet	ウォレットの残高と状態を取得します
get_wallet_recharge_addresses	オンチェーン USDC 入金アドレスを取得します
list_cards	このエージェントが作成したバーチャルカードを一覧表示します
get_card_balance	カードの残高と状態を取得します
batch_card_balances	1 回の呼び出しで複数のカードの残高を確認します
update_card	カードのリスク管理設定（tx_limit、allowed_mcc、blocked_mcc）を更新します
get_card_details	リスク管理設定、カード保有者情報、暗号化された PAN/CVV を含むカードの詳細を取得します
decrypt_card_data	get_card_details から PAN/CVV を復号します
list_transactions	オプションのフィルターを指定してカード取引を一覧表示します

高度な機能（x402 オンチェーン）

ツール	説明
get_x402_payee_address	x402 支払い用のオンチェーン受取アドレスを取得します
create_card_order	詳細な制御オプション付きでカードを作成します（モード B の 2 段階方式に対応）
refill_card	x402 またはカスタムの冪等性キーを使ってストリームカードを補充します

CLI オプション

オプション	環境変数	必須	デフォルト	説明
--api-key	CLAWALLEX_API_KEY	はい	—	Clawallex API Key
--api-secret	CLAWALLEX_API_SECRET	はい	—	Clawallex API Secret（HMAC-SHA256 署名）
--base-url	CLAWALLEX_BASE_URL	いいえ	https://api.clawallex.com	API ベース URL
--client-id	CLAWALLEX_CLIENT_ID	いいえ	自動生成	エージェント ID UUID。「Client ID」セクションを参照してください。
--transport	—	いいえ	stdio	トランスポートモード：stdio、sse、http
--port	—	いいえ	18080	sse / http トランスポート用の HTTP ポート

CLI 引数は環境変数より優先されます。両方を組み合わせることもできます。たとえば、認証情報を環境変数で設定し、--transport を CLI で上書きできます。

要件

• Node.js >= 22

クライアント ID

client_id はエージェントの固定 ID で、API キーとは別のものです。すべての /payment/* リクエストで X-Client-Id として送信されます。

重要な概念： エージェントは複数の API キーを持つことができます（ローテーション／失効のため）が、client_id は変わりません。新しい API キーに切り替える場合も、同じ client_id を使い続けてください。新しいキーは初回のリクエスト時に自動的に紐づけられます。

データの分離：

• ウォレット：ユーザーレベルで共有されます。同じ API キーを使うすべてのエージェントに、同じウォレット残高が表示されます
• カードと取引：client_id の範囲に限定されます。各エージェントには、自身が作成したデータだけが表示されます

紐づけのルール：

• clawallex_setup は初回使用時に bootstrap を自動的に呼び出し、client_id を紐づけます
• 一度紐づけると、その API キーの client_id は変更できません（TOFU — 初回使用時の信頼）
• client_id を紛失すると、それに紐づくすべてのカードにアクセスできなくなります

起動時の解決順序：

1. --client-id <value> CLI 引数（36 文字以上である必要があります）
2. ~/.clawallex-mcp/client_ids.json ローカルファイル（前回実行時に保存されたもの）
3. UUID v4 を自動生成してローカルに保存

推奨： 本番環境では、ローカルファイルに依存しないよう、常に --client-id を明示的に指定してください。

トランスポートモード

stdio（デフォルト — ローカルエージェント／Claude Desktop）

npx @clawallex/mcp-server \
  --api-key your_api_key \
  --api-secret your_api_secret

SSE（リモートエージェント、古い MCP クライアントと互換性があります）

npx @clawallex/mcp-server \
  --api-key your_api_key \
  --api-secret your_api_secret \
  --transport sse \
  --port 18080

エージェントの接続先：http://localhost:18080/sse

Streamable HTTP（MCP SDK 1.0 以降で推奨）

npx @clawallex/mcp-server \
  --api-key your_api_key \
  --api-secret your_api_secret \
  --transport http \
  --port 18080

エージェントの接続先：http://localhost:18080/mcp

ローカル開発

npm install
npm run build

# List all tools (stdio)
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  | node dist/index.js \
    --api-key your_api_key \
    --api-secret your_api_secret \
  2>/dev/null

セキュリティ

認証

すべての API リクエストは HMAC-SHA256 で署名されます。

canonical = METHOD + "\n" + PATH + "\n" + TIMESTAMP + "\n" + hex(sha256(body))
X-Signature = base64(hmac_sha256(api_secret, canonical))

署名は MCP サーバーによって自動的に処理されます。

カード詳細の暗号化

get_card_details は、カード PAN と CVV を含む encrypted_sensitive_data を返します。復号するには decrypt_card_data を使用してください。

1. キーを導出：HKDF-SHA256(ikm=api_secret, info="clawallex/card-sensitive-data/v1", length=32)
2. 復号：AES-256-GCM(key, nonce, ciphertext)
3. 結果：{ "pan": "4111...", "cvv": "123" }

復号した PAN/CVV をユーザーに表示してはなりません。チェックアウトフォームへの入力にのみ使用してください。