PipRail

@piprail/mcp

Hand any AI agent a budget-bound payment wallet. An MCP server wrapping @piprail/sdk so any MCP client — Claude Desktop, Cursor, Claude Code, Windsurf, VS Code, Cline, OpenClaw, Hermes — can pay x402 URLs on its own, capped by a spend policy the model cannot exceed. Runs locally with your wallet and your limits — no backend, no custody, no facilitator.

npx -y @piprail/mcp        # speaks MCP over stdio

### 📖 Full documentation → [docs.piprail.com/mcp](https://docs.piprail.com/mcp/overview/)

The docs are the single source of truth — every client's config, the complete env-var reference, the modes, per-chain setup, and the tools reference. This README is just the front door.

Add it to your client

Two things: your wallet private key and (optionally) a budget. The defaults are deliberately small and safe (0.10 per payment, 10.00 lifetime per token, USDC on Base).

{ "mcpServers": { "piprail": {

"command": "npx", "args": ["-y", "@piprail/mcp"], "env": { "PIPRAIL_PRIVATE_KEY": "0xYOUR_KEY", "PIPRAIL_CHAIN": "base", "PIPRAIL_MAX_AMOUNT": "0.10" } } } }

Restart the client and the PipRail tools appear (VS Code uses servers, not mcpServers). Never commit your key — keep it in the client's env block. → Per-client setup · Configuration

8 tools — piprail_discover · piprail_quote_payment · piprail_plan_payment · piprail_pay_request · piprail_register · piprail_budget · piprail_guide · piprail_verify_receipt. Only piprail_pay_request moves money; piprail_register writes a listing to an external index; the other six are read-only. → Tools reference

14 tools in sovereign mode. PIPRAIL_MODE=sovereign appends the swap tools, the seller tools (piprail_sell · piprail_collect · piprail_earnings) and piprail_wallet (what it holds, and the address it gets paid at), so the agent owns both halves of its wallet: it can be paid, not only pay. It appends rather than replaces, so the default above is untouched. → Modes

No key? It still runs. Without PIPRAIL_PRIVATE_KEY the server boots in read-only mode — discover, quote, register, budget, and guide all work; only piprail_pay_request (and piprail_plan_payment) ask for a wallet. Add a key when you're ready to actually pay.

Pay across chains? List several chains and give each its own key — the tools then pay whichever chain a 402 asks for (one server, one budget):

"env": {

"PIPRAIL_CHAINS": "base,polygon,solana", "PIPRAIL_BASE_KEY": "0x…", "PIPRAIL_POLYGON_KEY": "0x…", "PIPRAIL_SOLANA_KEY": " ", "PIPRAIL_MAX_AMOUNT": "1.00" }

One EVM key works on every EVM chain; non-EVM families each need their own key (and that family's peer libs). A chain with no key is read-only. → Configuration

Listed in the official MCP registry as io.github.piprail/mcp.

What it will not do by default

There is no swap tool in the default set, and that is deliberate: the spend policy does not govern swaps. Every budget cap here governs *paying a merchant*, while a swap moves your own funds between denominations, so an agent able to swap could drain a wallet through fees and slippage without tripping a single budget check.

That is a reason to bound the capability, not to pretend it does not exist. PIPRAIL_MODE=sovereign unlocks it for an operator who says the agent owns this wallet, and requires PIPRAIL_MAX_PER_SWAP before the server will start, because the payment caps cannot bound a swap. A model can never set its own mode.

Sovereign also unlocks selling, which needs no ceiling: it takes money rather than spending it, and the receiving side holds no private key at all.

Documentation

Spread the word

Free, open-source, self-custodial — no backend to sell you. If PipRail gave your agent a wallet it can trust, help others find it:

⭐ [Star on GitHub](https://github.com/piprail/piprail) · 𝕏 [Follow @piprailhq](https://x.com/piprailhq) · 🌐 [piprail.com](https://piprail.com) · 📖 [docs.piprail.com](https://docs.piprail.com)

Docs · PipRail · @piprail/sdk · x402 · Model Context Protocol

MIT · no backend, no fee, ever.