> ## Documentation Index > Fetch the complete documentation index at: https://docs.algovoi.co.uk/llms.txt > Use this file to discover all available pages before exploring further. # AlgoVoi MCP server > Expose AlgoVoi as MCP tools to Claude Desktop, Claude Code, Cursor, and Windsurf. Create USDC payment links and verify x402, MPP, AP2, and A2A on-chain. The AlgoVoi MCP server (v1.7.0 on both Python and TypeScript) lets any [Model Context Protocol](https://modelcontextprotocol.io) client call AlgoVoi's gateway as if its tools were native. An assistant can create payment links, verify transactions, probe MPP endpoints, screen recipients, generate protocol challenges, call payment-gated A2A agents, manage recurring payment authorities, and drive MPP subscription lifecycles — all from a normal conversation. [![Agent Trust Bench](https://img.shields.io/badge/Agent_Trust_Bench-128%2F138_Passed-238636)](https://agent-trust-bench.algovoi.co.uk) Tested against the [AlgoVoi Agent Trust Bench](https://agent-trust-bench.algovoi.co.uk) — 128/138 correct (92.8%) across 138 adversarial payment profiles and 30 attack categories. Zero adversarial profiles settled. ## 29 tools ### Payment tools | Tool | Action | | --------------------------- | ---------------------------------------------------------------------- | | `create_payment_link` | Generate a hosted-checkout URL from amount + currency + chain | | `verify_payment` | Confirm an on-chain transaction was paid for the given token | | `prepare_extension_payment` | Prepare an in-page browser-wallet payment (AVM chains only) | | `list_networks` | Return all supported chains and assets (all 7 chains, 26 network keys) | | `verify_webhook` | Verify an AlgoVoi webhook signature and parse the payload | ### Protocol challenge tools | Tool | Action | | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `generate_mpp_challenge` | Compose an IETF MPP 402 `WWW-Authenticate` header + challenge ID | | `verify_mpp_receipt` | Verify an MPP on-chain receipt via direct indexer (no API call) | | `try_mpp_endpoint` | Probe any URL gated by MPP or x402; decode the `WWW-Authenticate: Payment` header (MPP) or the `X-Payment-Required` / `PAYMENT-REQUIRED` header (x402 v1) and return the payment details — mirrors `npx agentcash try {url}` | | `verify_x402_proof` | Decode a base64 x402 proof and verify the transaction on-chain | | `generate_x402_challenge` | Compose an x402 v1 `X-Payment-Required` header | | `generate_ap2_mandate` | Compose an AP2 v0.1 `PaymentMandate` for agent payment flows | | `verify_ap2_payment` | Verify an AP2 mandate payment receipt via direct indexer | ### A2A agent tools | Tool | Action | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | | `fetch_agent_card` | `GET {agent_url}/.well-known/agent.json` — discover a payment-gated A2A agent's capabilities | | `send_a2a_message` | `POST {agent_url}/message:send` — call a payment-gated A2A agent; returns result on 200, `challenge_headers` on 402 for pay-and-retry | ### Recurring payment tools (Tier 2) Eight tools for standing-authority subscriptions — the customer authorises a spending cap once; the agent pulls on schedule without re-asking. | Tool | Action | | ---------------------------- | ------------------------------------------------------------------ | | `create_recurring_authority` | Open a standing authority (cap + period + per-cycle amount) | | `get_authority` | Fetch current state of an authority by ID | | `list_authorities` | List authorities for a subscription or by status | | `confirm_authority` | Mark an authority active after the on-chain wallet signature lands | | `revoke_authority` | Revoke an active authority (constructs on-chain revocation) | | `pause_authority` | Pause cycle pulls without revoking | | `resume_authority` | Resume a paused authority | | `manual_pull` | Trigger a one-off pull (catch-up or proration) | ### MPP subscription tools Three tools for the MPP-protocol subscription lifecycle ([tempoxyz/mpp-specs#230](https://github.com/tempoxyz/mpp-specs/pull/230) — `draft-payment-intent-subscription-00`). Distinct from Tier 2 above: MPP subscriptions are on-chain per-period pulls executed by the facilitator, settled to `payment_ledger` with hash-chain audit retention. Webhook events emitted: `mpp_subscription.activated`, `.charged`, `.revoked`, `.expired`. | Tool | Action | | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `try_mpp_subscription` | Probe a public `/mpp/sub/{tenant_short_id}/{resource_id}` URL; parse the 402 dual envelope and surface subscription-specific extras (periodCount, periodUnit, intent, payTo, amount, asset) so agents can present the terms before submitting a signed authority credential. Unauthenticated. | | `list_mpp_subscriptions` | List the tenant's MPP subscriptions with first\_pull\_tx\_id, first\_pull\_finalized\_at, status, next\_due\_at, activated\_at. Optional status filter. Requires admin-scope API key. | | `cancel_mpp_subscription` | Cancel an active MPP subscription — next due renewal pull will not execute; current period's already-paid access is unaffected. Idempotent. Requires admin-scope API key. | ### Discovery and compliance tools | Tool | Action | | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `discover_resources` | Fetch the public AlgoVoi Bazaar catalog — all x402 and MPP payable resources from active tenants. No API key required. | | `screen_recipient` | Pre-payment sanctions screen (OFSI / OFAC SDN / EU Consolidated + AlgoVoi KYB). Returns verdict, risk\_tier, and reasons under SAMLA 2018 s.20. No API key required. | | `get_compliance_attestation` | Fetch the operator's public compliance posture: active frameworks, live sanctions sources, audit chain heads, and Object Lock status. No API key required. | #### 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="") → task result returned ``` #### MPP consumer probe flow ``` 1. try_mpp_endpoint("https://api.example.com/premium-data") → payment_required: true → accepts: [{network: "algorand_mainnet", amount: 1000000, asset: "USDC", receiver: "..."}] → expires: "2026-05-19T12:00:00Z" 2. create_payment_link(amount=1, currency="USD", network="algorand_mainnet", ...) → checkout_url, token 3. verify_payment(token) → paid: true 4. try_mpp_endpoint("https://api.example.com/premium-data") → status: 200, payment_required: false, body_preview: "..." ``` #### x402 probe flow ``` 1. try_mpp_endpoint("https://api.example.com/data") → status: 402, payment_required: true → x402_challenge: {accepts: [{network: "base-mainnet", amount: "10000", asset: "0x833..."}]} 2. generate_x402_challenge(network="base_mainnet", amount=0.01, asset="USDC") → x402_header, challenge_id 3. verify_x402_proof(proof=, network="base_mainnet") → verified: true, tx_id: "0x..." ``` ## Response model — `ALGOVOI_MODE` Set the `ALGOVOI_MODE` environment variable to choose how much detail tool results carry: | Mode | Behaviour | | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `standard` *(default if unset is `substrate`)* | Tools return the bare x402 / MPP / AP2 / A2A standard response. Verdict fields (`verified`, `paid`, `verdict`, `reasons`, `trust_outcome`) are present. Substrate-only keys are stripped client-side. **This is the traditional payment model** — compatible with any x402 or MPP implementation. | | `substrate` *(default)* | Tools return the full AlgoVoi substrate response. Each payment verification includes a signed `settlement_attestation` (Ed25519/Falcon-1024 sealed, JCS-canonical). Compliance screens include a signed `compliance_receipt` and `action_ref`. Trust queries include `composite_hash` and a signed `ctq_response`. | Both modes call the same gateway API. Substrate fields are additive — `standard` simply filters them client-side, so you can switch modes by flipping one env var without changing any integration code. **Which tools carry substrate fields:** | Tool | Standard mode | Substrate mode adds | | ------------------------ | --------------------------------- | ---------------------------------------- | | `verify_payment` (x402) | `verified`, `paid` | `settlement_attestation` + JWS | | `verify_mpp_receipt` | `verified` | `settlement_attestation` + JWS | | `verify_ap2_payment` | `verified` | `settlement_attestation` + JWS | | `verify_x402_proof` | `verified` | `settlement_attestation` + JWS | | `screen_recipient` | `verdict`, `risk_tier`, `reasons` | `action_ref`, `compliance_receipt` + JWS | | `compliance_trust_query` | `trust_outcome`, `receipt_count` | `composite_hash`, `ctq_response` + JWS | **Example — switch to standard mode:** ```json theme={null} { "mcpServers": { "algovoi": { "command": "uvx", "args": ["algovoi-mcp"], "env": { "ALGOVOI_API_KEY": "algv_…", "ALGOVOI_TENANT_ID": "your-tenant-id", "ALGOVOI_MODE": "standard" } } } } ``` `standard` mode is recommended for agents that only need to confirm payment success. `substrate` mode is recommended for agents that operate inside compliance-sensitive flows, need an auditable trail, or want to feed receipts into `compliance_trust_query` for a composite trust verdict. ## Two implementations | Implementation | Package | Versioned install | | ------------------------------------ | ------------------------------------------------------------------------------------------ | ---------------------------------- | | **Python** `algovoi-mcp` | [pypi.org/project/algovoi-mcp](https://pypi.org/project/algovoi-mcp/) | `uvx algovoi-mcp==1.7.0` | | **TypeScript** `@algovoi/mcp-server` | [npmjs.com/package/@algovoi/mcp-server](https://www.npmjs.com/package/@algovoi/mcp-server) | `npx -y @algovoi/mcp-server@1.7.0` | Both expose the same 29 tools across all 7 chains (Base, Algorand, Solana, Stellar, Hedera, Tempo, VOI). Functional behaviour is identical. ## Wiring it into Claude Desktop Add the MCP server to your Claude Desktop config: * **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` * **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` ```json theme={null} { "mcpServers": { "algovoi": { "command": "uvx", "args": ["algovoi-mcp"], "env": { "ALGOVOI_API_KEY": "algv_…", "ALGOVOI_TENANT_ID": "your-tenant-id", "ALGOVOI_PAYOUT_ALGORAND": "your-algorand-address", "ALGOVOI_PAYOUT_BASE": "0x…", "ALGOVOI_PAYOUT_SOLANA": "your-solana-address", "ALGOVOI_PAYOUT_TEMPO": "0x…" } } } } ``` Restart Claude Desktop. The AlgoVoi tools appear in the tools list. Now ask Claude "create a \$5 USDC checkout link on Solana" and it will call `create_payment_link` and return the URL. Or pin to a specific version: ```json theme={null} { "mcpServers": { "algovoi": { "command": "npx", "args": ["-y", "@algovoi/mcp-server@1.7.0"], "env": { "ALGOVOI_API_KEY": "algv_…", "ALGOVOI_TENANT_ID": "your-tenant-id", "ALGOVOI_PAYOUT_ALGORAND": "your-algorand-address", "ALGOVOI_PAYOUT_BASE": "0x…", "ALGOVOI_PAYOUT_TEMPO": "0x…" } } } } ``` ## Wiring into Claude Code, Cursor, or Windsurf **Claude Code** — add to `.claude/mcp.json` in your project root (project-scoped) or `~/.claude/mcp.json` (global): ```json theme={null} { "mcpServers": { "algovoi": { "command": "uvx", "args": ["algovoi-mcp==1.7.0"], "env": { "ALGOVOI_API_KEY": "algv_…", "ALGOVOI_TENANT_ID": "your-tenant-id", "ALGOVOI_PAYOUT_ALGORAND": "your-algorand-address", "ALGOVOI_PAYOUT_BASE": "0x…" } } } } ``` **Cursor** — add to `.cursor/mcp.json` in your project root. **Windsurf** — add to `.codeium/windsurf/mcp_config.json`. The server entry shape is identical across all three editors. ## A2A and MCP together The same gateway exposes [A2A skills](/protocols/a2a) for agent-to-agent calls and MCP tools for assistants. Use `fetch_agent_card` + `send_a2a_message` to discover and call payment-gated A2A agents from inside Claude or Cursor — no separate client code required. ## See also * [A2A](/protocols/a2a) for the agent-to-agent equivalent * [MPP](/protocols/mpp) for paywalling MCP tools that you build * [Agent Trust Bench](/agent-trust-bench) — test your own agent against 138 adversarial payment profiles * The [MCP spec](https://modelcontextprotocol.io)