Algovoi Mcp Server

AlgoVoi MCP Server

An MCP (Model Context Protocol) server that exposes AlgoVoi's payment infrastructure as tools any MCP client can call — Claude Desktop, Claude Code, Cursor, Windsurf, or any other MCP-compatible assistant.

Ships as two packages:

Package	Install	Command
TypeScript	npm i -g @algovoi/mcp-server	npx -y @algovoi/mcp-server
Python	pip install algovoi-mcp	uvx algovoi-mcp or algovoi-mcp

Both packages now expose all 21 tools (13 Tier 1 + 8 Tier 2 standing-authority recurring tools, both shipped at v1.3.0). Pick whichever runtime your MCP client / deployment stack prefers — same surface, same JSON Schema definitions, same Pydantic-strict / extra-forbid validation.

---

Tools

Payment tools

#	Tool	What it does
1	create_payment_link	Hosted-checkout URL for a given amount + chain
2	verify_payment	Verify a checkout token (optionally with a tx_id)
3	prepare_extension_payment	In-page wallet-flow params (Algorand / VOI)
4	verify_webhook	HMAC-SHA256 signature check for AlgoVoi webhooks
5	list_networks	Supported chains + asset IDs (offline, no API call)

Protocol challenge tools

#	Tool	What it does
6	generate_mpp_challenge	IETF MPP 402 WWW-Authenticate headers + challenge_id
7	verify_mpp_receipt	Verify an MPP on-chain receipt (direct indexer, no API call)
8	verify_x402_proof	Verify an x402 base64 payment proof (direct indexer)
9	generate_x402_challenge	x402 X-Payment-Required 402 headers + payload
10	generate_ap2_mandate	AP2 v0.1 PaymentMandate for AI agent payment flows
11	verify_ap2_payment	Verify an AP2 mandate payment receipt (direct indexer)

A2A agent tools (new in v1.2.0)

#	Tool	What it does
12	fetch_agent_card	GET {agent_url}/.well-known/agent.json — discover an A2A agent's capabilities and payment requirements before calling it
13	send_a2a_message	POST {agent_url}/message:send — call a payment-gated A2A v1.0 agent; returns the task result on 200, or challenge_headers on 402 so Claude can pay and retry

A2A pay-and-call flow

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

Supported networks: Algorand, VOI, Hedera, Stellar (USDC on all four + native ALGO/VOI/HBAR/XLM).

Tier 2 — Standing-authority recurring tools (new in v1.3.0 — both TS and Python)

Tier 2 is "customer signs ONCE, AlgoVoi auto-pulls per cycle" — the subscription / agent-bound spending pattern. Each chain uses its native authorisation primitive (no custom escrow contracts on the merchant side):

#	Tool	What it does
14	create_recurring_authority	Open a new standing authority. Returns chain-specific customer_signing_payload for the customer's wallet to sign
15	get_authority	Read current state (status, cycles_pulled, cap_remaining, etc.)
16	list_authorities	List all authorities for this tenant; filter by status / subscription_id
17	confirm_authority	Mark active after on-chain landing (most flows skip this — webhook does it)
18	revoke_authority	Chain-side revocation (customer's wallet signs the revoke tx)
19	pause_authority	Off-chain pause (no chain action)
20	resume_authority	Off-chain resume
21	manual_pull	Tenant-initiated catch-up / proration pull

Per-chain authorisation primitives

Chain	Primitive
Algorand / VOI	SpendingCapVault (6-action atomic group)
Base / Tempo	ERC-20 approve (single tx)
Solana	SPL Token Approve + facilitator delegate
Hedera	HTS AccountAllowanceApproveTransaction
Stellar	Soroban auth_entry (smart-contract authorisation)

Subscription flow

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.

Per-chain wallet-side integration: see ../Recurr/<chain>/README.md for each chain's customer-side flow.

Supported networks: all 14 (7 mainnets + 7 testnets) — Algorand, VOI, Base, Tempo, Solana, Hedera, Stellar.

---

Two ways to connect

Option A — AlgoVoi Cloud (recommended)

AlgoVoi Cloud is the control plane for all your integrations — WooCommerce, Zapier, n8n, and MCP all in one dashboard. Point ALGOVOI_API_BASE at https://cloud.algovoi.co.uk and your single algv_... API key covers every integration — no tenant ID or payout addresses needed (they're stored in the dashboard).

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

Every payment Claude creates appears in your Cloud dashboard alongside payments from every other platform. One place to see everything.

Sign up free at dash.algovoi.co.uk.

---

Option B — AlgoVoi direct

Connect straight to the AlgoVoi API with your algv_... key and tenant ID.

Both packages read the same env vars:

Var	Required	Purpose
ALGOVOI_API_KEY	✅	algv_... API key from the AlgoVoi dashboard
ALGOVOI_TENANT_ID	✅	Tenant UUID from the AlgoVoi dashboard
ALGOVOI_PAYOUT_ALGORAND	✅*	Algorand payout wallet address
ALGOVOI_PAYOUT_VOI	✅*	VOI payout wallet address
ALGOVOI_PAYOUT_HEDERA	✅*	Hedera payout account (e.g. 0.0.123456)
ALGOVOI_PAYOUT_STELLAR	✅*	Stellar payout address (G...)
ALGOVOI_PAYOUT_ADDRESS	—	Universal fallback if per-chain vars are not set
ALGOVOI_WEBHOOK_SECRET	—	For verify_webhook
ALGOVOI_API_BASE	—	Override the AlgoVoi API base URL (default: https://cloud.algovoi.co.uk)

* At least one per-chain address (or ALGOVOI_PAYOUT_ADDRESS as fallback) is required.

Auth is env-var only. Secrets never pass through tool arguments — the MCP client never sees the API key.

Sign up at www.algovoi.co.uk to get your API key and tenant ID.

{
  "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>"
      }
    }
  }
}

For the Python package, swap "command": "uvx", "args": ["algovoi-mcp"].

Config file locations:

• 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

---

Testing

# 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

---

Licensed under the Business Source License 1.1.