MCP server - AlgoVoi Platform

The AlgoVoi MCP server (v1.7.0 on both Python and TypeScript) lets any Model Context Protocol 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.

Tested against the AlgoVoi Agent Trust Bench — 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 8 chains including ARC testnet, 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 — 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="<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=<base64-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:

{
  "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	`uvx algovoi-mcp==1.7.0`
TypeScript `@algovoi/mcp-server`	npmjs.com/package/@algovoi/mcp-server	`npx -y @algovoi/mcp-server@1.7.0`

Both expose the same 29 tools across all 8 chains (Base, Algorand, Solana, Stellar, Hedera, Tempo, VOI, and ARC testnet). 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

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

{
  "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):

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

​29 tools

​Payment tools

​Protocol challenge tools

​A2A agent tools

​Recurring payment tools (Tier 2)

​MPP subscription tools

​Discovery and compliance tools

​A2A pay-and-call flow

​MPP consumer probe flow

​x402 probe flow

​Response model — ALGOVOI_MODE

​Two implementations

​Wiring it into Claude Desktop

​Wiring into Claude Code, Cursor, or Windsurf

​A2A and MCP together

​See also