> ## 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="<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:**

```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)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.