Obolus MCP server

<!-- mcp-name: io.github.inviti8/obolus -->

Obolus

<!-- The logo above is a placeholder. Replace assets/obolus-logo.svg; the only reference is the absolute URL above, which is absolute because PyPI does not resolve relative paths in a long description. -->

An MCP server that gives an AI agent a disposable Algorand wallet, so it can pay for x402 resources without a human provisioning anything.

The name is the coin paid to the ferryman for passage: small denomination, one purpose, spent and gone.

agent → x402_fetch(url) → 402 → sign → pay → body

x402 has over a thousand listed resources and almost no buyers — a handful of wallets account for nearly all volume, and they are scripted loops rather than agents. The rail exists; nothing can reach it. Obolus is the buyer-side piece: account setup, opt-in, signing and sweeping handled invisibly, so an agent just spends.

Install

Claude Code — the plugin

/plugin marketplace add inviti8/Obolus
/plugin install obolus@heavymeta

Wires up the MCP server and adds /obolus:fund-wallet, which knows the bootstrap order and why it cannot be rearranged. Nothing to install first beyond uv — the server is launched with uvx obolus mcp.

Everything else

uv tool install obolus

uv tool install rather than uvx for the CLI: uvx re-resolves on every invocation, measured at 200–400 ms over an installed console script. That is nothing once per session, which is all the MCP server costs — it is why the plugin above uses uvx — but it is the wrong trade for a command called in a loop. pipx install obolus works too.

Add it to Claude Code by hand

claude mcp add obolus -e OBOLUS_NETWORK=testnet -- obolus-mcp

Add it to any other MCP client

{
  "mcpServers": {
    "obolus": {
      "command": "obolus-mcp",
      "env": { "OBOLUS_NETWORK": "testnet" }
    }
  }
}

It starts on testnet. Mainnet is never disabled — Obolus is meant to make real payments — but it is never what you get by forgetting to choose.

Fund it

A new vault holds nothing, and the order is forced by the chain:

obolus vault          # says which of the three steps you are on
obolus vault qr       # scannable codes for the two things you can send

Step 3 before step 2 fails. An Algorand account cannot receive an asset it has not opted into — the transfer is rejected outright, it does not sit pending. That is why the QR codes encode the asset id and not just the address, and why walletfundinginfo tells you which step you are on every time rather than only on error.

The QR codes carry no amount. You type that into your own wallet, where you see it before confirming.

Use it

Three tools, deliberately:

There is no tool for any particular merchant. Everything is reached through x402_fetch, because the moment a wallet grows first-class verbs for one seller it stops being a wallet.

What bounds a loss

The session balance, enforced by the chain. Payments come from a short-lived session account funded from your vault, never from the vault itself. A session cannot spend what it does not hold, and that is true regardless of what any code here does.

Shortened. The full README is on GitHub.