@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

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

7 tools — piprail_discover · piprail_quote_payment · piprail_plan_payment · piprail_pay_request · piprail_register · piprail_budget · piprail_guide. Only piprail_pay_request moves money; the rest are read-only. → Tools reference

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": "<base58-secret>",
  "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.

Documentation

| | | |---|---| | Overview · Getting started | What it is · first run | | Client setup · Configuration | Per-client config · every env var | | Tools · Modes | The 7 tools · headless vs supervised | | Security · Chains | Why it's safe · per-chain setup | | Use as a library · FAQ | Embed it · common questions |

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  ·  𝕏 Follow @piprailhq  ·  🌐 piprail.com  ·  📖 docs.piprail.com

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

MIT · no backend, no fee, ever.