Algovoi Mcp Server

AlgoVoi MCP サーバー

AlgoVoi の決済インフラを、Claude Desktop、Claude Code、Cursor、Windsurf、その他の MCP 互換アシスタントなど、あらゆる MCP クライアントから呼び出せるツールとして提供する MCP（Model Context Protocol） サーバーです。

2 つのパッケージとして提供されています。

パッケージ	インストール	コマンド
TypeScript	npm i -g @algovoi/mcp-server	npx -y @algovoi/mcp-server
Python	pip install algovoi-mcp	uvx algovoi-mcp または algovoi-mcp

両方のパッケージで、現在 21 個すべてのツールを利用できます（Tier 1 が 13 個、Tier 2 の継続的な権限付与による定期実行ツールが 8 個。どちらも v1.3.0 で提供）。MCP クライアントやデプロイスタックが好むランタイムを選んでください。どちらも同じインターフェース、同じ JSON Schema 定義、同じ Pydantic 厳格検証／追加フィールド禁止の検証を備えています。

---

ツール

決済ツール

#	ツール	機能
1	create_payment_link	指定した金額とチェーンに対応するホスト型チェックアウト URL
2	verify_payment	チェックアウトトークンを検証します（任意で tx_id を指定可能）
3	prepare_extension_payment	ページ内ウォレットフロー用のパラメーター（Algorand / VOI）
4	verify_webhook	AlgoVoi Webhook の HMAC-SHA256 署名を検証します
5	list_networks	対応チェーンとアセット ID を一覧表示します（オフラインで実行され、API 呼び出しはありません）

プロトコルチャレンジツール

#	ツール	機能
6	generate_mpp_challenge	IETF MPP 402 の WWW-Authenticate ヘッダーと challenge_id を生成します
7	verify_mpp_receipt	MPP のオンチェーンレシートを検証します（インデクサーに直接接続し、API 呼び出しはありません）
8	verify_x402_proof	x402 の Base64 決済証明を検証します（インデクサーに直接接続）
9	generate_x402_challenge	x402 の X-Payment-Required 402 ヘッダーとペイロードを生成します
10	generate_ap2_mandate	AI エージェントの決済フロー用に AP2 v0.1 PaymentMandate を生成します
11	verify_ap2_payment	AP2 マンデートの決済レシートを検証します（インデクサーに直接接続）

A2A エージェントツール (v1.2.0 で追加)

#	ツール	機能
12	fetch_agent_card	GET {agent_url}/.well-known/agent.json — A2A エージェントを呼び出す前に、その機能と決済要件を確認します
13	send_a2a_message	POST {agent_url}/message:send — 決済ゲート付きの A2A v1.0 エージェントを呼び出します。200 の場合はタスク結果を返し、402 の場合は Claude が決済して再試行できるよう challenge_headers を返します

A2A の決済と呼び出しのフロー

1. fetch_agent_card("https://agent.example.com")
   → see agent costs $0.01, accepts MPP on Algorand

2. send_a2a_message(agent_url, "What is the price of ALGO?")
   → payment_required: true, challenge_headers: {WWW-Authenticate: ...}

3. generate_mpp_challenge(...)   ← use tool #6
   → user pays on-chain

4. send_a2a_message(agent_url, text, payment_proof="<proof>")
   → task result returned

対応ネットワーク：Algorand、VOI、Hedera、Stellar（4 つすべてで USDC に対応し、ネイティブ通貨は ALGO／VOI／HBAR／XLM に対応）。

Tier 2 — 継続的な権限付与による定期実行ツール (v1.3.0 で追加 — TS と Python の両方に対応)

Tier 2 は、**「顧客が一度だけ署名し、AlgoVoi が各サイクルで自動引き落としを行う」**仕組みです。サブスクリプションやエージェントに紐づく支出パターンに対応します。各チェーンではネイティブの認可プリミティブを使用します（加盟店側にカスタムエスクローコントラクトは不要です）。

#	ツール	機能
14	create_recurring_authority	新しい継続的な権限付与を開始します。顧客のウォレットで署名する、チェーン固有の customer_signing_payload を返します
15	get_authority	現在の状態（status、cycles_pulled、cap_remaining など）を読み取ります
16	list_authorities	このテナントのすべての権限付与を一覧表示します。status／subscription_id で絞り込み可能です
17	confirm_authority	オンチェーンへの反映後に有効としてマークします（ほとんどのフローではこの手順を省略し、Webhook が処理します）
18	revoke_authority	チェーン側で権限を取り消します（顧客のウォレットで取り消しトランザクションに署名します）
19	pause_authority	オフチェーンで一時停止します（チェーン上の操作はありません）
20	resume_authority	オフチェーンで再開します
21	manual_pull	テナントが開始する、未処理分の回収や日割り計算による引き落とし

チェーンごとの認可プリミティブ

チェーン	プリミティブ
Algorand / VOI	SpendingCapVault（6 アクションのアトミックグループ）
Base / Tempo	ERC-20 approve（単一トランザクション）
Solana	SPL Token Approve とファシリテーターデリゲート
Hedera	HTS AccountAllowanceApproveTransaction
Stellar	Soroban auth_entry（スマートコントラクト認可）

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

1. create_recurring_authority(subscription_id, chain, customer_wallet,
                              cap_amount_minor, cap_period_seconds,
                              per_cycle_amount_minor)
   → customer_signing_payload returned

2. Hand template to wallet (Pera / Defly / MetaMask / Phantom /
   HashPack / Freighter / etc.)
   → customer signs the chain-native authorisation tx

3. confirm_authority(authority_id, on_chain_address)
   → status: 'pending' → 'active'

4. AlgoVoi cycle reaper auto-pulls per cap_period_seconds.
   Each pull emits subscription.charged or subscription.payment_failed
   webhooks (verify with verify_webhook).

5. Lifecycle: revoke_authority / pause_authority / resume_authority /
   manual_pull as needed.

チェーンごとのウォレット側の連携については、各チェーンの顧客側のフローを../Recurr/<chain>/README.mdでご確認ください。

対応ネットワーク：全14（メインネット7＋テストネット7）— Algorand、VOI、 Base、Tempo、Solana、Hedera、Stellar。

---

接続方法は2つ

オプションA — AlgoVoi Cloud（推奨）

AlgoVoi Cloudは、WooCommerce、Zapier、n8n、MCPなど、すべての連携を一元管理するコントロールプレーンです。ALGOVOI_API_BASEをhttps://cloud.algovoi.co.ukに設定すると、1つのalgv_... APIキーですべての連携を利用できます。テナントIDや出金先アドレスは不要です（ダッシュボードに保存されます）。

{
  "mcpServers": {
    "algovoi": {
      "command": "npx",
      "args": ["-y", "@algovoi/mcp-server"],
      "env": {
        "ALGOVOI_API_KEY": "algv_...",
        "ALGOVOI_API_BASE": "https://cloud.algovoi.co.uk"
      }
    }
  }
}

Claudeが作成したすべての支払いは、ほかのすべてのプラットフォームからの支払いとともにCloudダッシュボードに表示されます。すべての情報を1か所で確認できます。

dash.algovoi.co.ukで無料登録できます。

---

オプションB — AlgoVoiに直接接続

algv_...キーとテナントIDを使って、AlgoVoi APIに直接接続します。

どちらのパッケージも同じ環境変数を読み込みます。

変数	必須	用途
ALGOVOI_API_KEY	✅	AlgoVoiダッシュボードで取得したalgv_... APIキー
ALGOVOI_TENANT_ID	✅	AlgoVoiダッシュボードで取得したテナントUUID
ALGOVOI_PAYOUT_ALGORAND	✅*	Algorandの出金先ウォレットアドレス
ALGOVOI_PAYOUT_VOI	✅*	VOIの出金先ウォレットアドレス
ALGOVOI_PAYOUT_HEDERA	✅*	Hederaの出金先アカウント（例：0.0.123456）
ALGOVOI_PAYOUT_STELLAR	✅*	Stellarの出金先アドレス（G...）
ALGOVOI_PAYOUT_ADDRESS	—	チェーンごとの変数が設定されていない場合に使う共通のフォールバック
ALGOVOI_WEBHOOK_SECRET	—	verify_webhook用
ALGOVOI_API_BASE	—	AlgoVoi APIのベースURLを上書きします（デフォルト：https://cloud.algovoi.co.uk）

* チェーンごとのアドレスを少なくとも1つ設定するか、フォールバックとしてALGOVOI_PAYOUT_ADDRESSを設定する必要があります。

認証情報は環境変数でのみ設定します。 シークレットがツールの引数を介して渡されることはありません。MCPクライアントがAPIキーを参照することもありません。

APIキーとテナントIDを取得するには、www.algovoi.co.ukで登録してください。

{
  "mcpServers": {
    "algovoi": {
      "command": "npx",
      "args": ["-y", "@algovoi/mcp-server"],
      "env": {
        "ALGOVOI_API_KEY": "algv_...",
        "ALGOVOI_TENANT_ID": "...",
        "ALGOVOI_PAYOUT_ALGORAND": "<your-algorand-address>",
        "ALGOVOI_PAYOUT_VOI":      "<your-voi-address>",
        "ALGOVOI_PAYOUT_HEDERA":   "0.0.<your-account>",
        "ALGOVOI_PAYOUT_STELLAR":  "G<your-stellar-address>"
      }
    }
  }
}

Pythonパッケージを使う場合は、"command": "uvx", "args": ["algovoi-mcp"]に置き換えてください。

設定ファイルの場所：

• Claude Desktop：~/Library/Application Support/Claude/claude_desktop_config.json（macOS）、%APPDATA%\Claude\claude_desktop_config.json（Windows）
• Claude Code：~/.claude.json
• Cursor：~/.cursor/mcp.json

---

テスト

# TypeScript unit tests (77/77)
cd typescript && npm test

# Python unit tests (85/85)
cd python && pytest

# Stdio integration smoke — boots both servers and confirms all 13 tools list
python smoke_stdio.py

---

Business Source License 1.1に基づいてライセンスされています。