mcpField
P
Piprail

Piprail

Local
piprail.comFinance9Updated 7w ago
RepositoryVisit website

About Piprail

Piprail is a local MCP server that gives AI agents a self-custodial wallet for x402 payments, with operator-defined spending limits. It supports discovery and registration as well as payment, and offers additional wallet capabilities in sovereign mode.

Key features

  1. 01Budget-capped x402 payments
  2. 02Discover and register payment URLs
  3. 03Read-only operation without a key
  4. 04Support for multiple chains
  5. 05Optional sovereign wallet tools

Use cases

  1. 01Let an agent pay for an x402-gated URL
  2. 02Discover and register payment endpoints
  3. 03Set payment limits for an agent wallet
  4. 04Enable selling and wallet tools in sovereign mode

MCP support

Piprail exposes eight default tools to MCP clients for discovery, quotes, payment planning and execution, registration, budget, guidance, and receipt verification. Sovereign mode adds tools for swaps, selling, collections, earnings, and wallet information.

#x402#agent-payments#crypto-payments#usdc#stablecoin#multichain#wallet#autonomous-payments#web3

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config
{
  "mcpServers": {
    "piprail": {
      "command": "npx",
      "args": [
        "-y",
        "@piprail/mcp"
      ],
      "env": {
        "PIPRAIL_PRIVATE_KEY": "<PIPRAIL_PRIVATE_KEY>",
        "PIPRAIL_CHAIN": "<PIPRAIL_CHAIN>",
        "PIPRAIL_CHAINS": "<PIPRAIL_CHAINS>",
        "PIPRAIL_MAX_AMOUNT": "<PIPRAIL_MAX_AMOUNT>",
        "PIPRAIL_MAX_TOTAL": "<PIPRAIL_MAX_TOTAL>",
        "PIPRAIL_MAX_TOTAL_DENOM": "<PIPRAIL_MAX_TOTAL_DENOM>",
        "PIPRAIL_MAX_PAYMENTS": "<PIPRAIL_MAX_PAYMENTS>",
        "PIPRAIL_MAX_PAYMENTS_PER_WINDOW": "<PIPRAIL_MAX_PAYMENTS_PER_WINDOW>",
        "PIPRAIL_WARN_AT_FRACTION": "<PIPRAIL_WARN_AT_FRACTION>",
        "PIPRAIL_SPEND_LOG": "<PIPRAIL_SPEND_LOG>",
        "PIPRAIL_EVENT_LOG": "<PIPRAIL_EVENT_LOG>",
        "PIPRAIL_TOKENS": "<PIPRAIL_TOKENS>",
        "PIPRAIL_SCHEMES": "<PIPRAIL_SCHEMES>"
      }
    }
  }
}
Run commandnpx -y @piprail/mcp
Environment variables to set
PIPRAIL_PRIVATE_KEYSecretYour wallet's private key/seed for the chosen chain. Optional: omit it to run read-only (discover/quote/register/budget/guide); set it to let the agent pay. Stays on your machine; the spend policy caps every payment.
PIPRAIL_CHAINChain to pay on (default: base).
PIPRAIL_CHAINSPay across several chains (instead of PIPRAIL_CHAIN): a comma-separated list, e.g. base,polygon,solana. Give each its own PIPRAIL_<CHAIN>_KEY (+ optional PIPRAIL_<CHAIN>_RPC_URL). The agent pays whichever chain a 402 asks for — the first listed that can settle — under one shared budget.
PIPRAIL_MAX_AMOUNTMax spend per single payment, in token units (default: 0.10).
PIPRAIL_MAX_TOTALLifetime spend cap per token, in token units (default: 10.00).
PIPRAIL_MAX_TOTAL_DENOMCross-token GRAND TOTAL: one spend cap per denomination across every stablecoin and chain, e.g. USD:20.00,EUR:5.00. Not a price oracle — sums tokens of the same unit, each counted 1:1. Native coins are excluded.
PIPRAIL_MAX_PAYMENTSLifetime cap on the NUMBER of payments, across every chain + token (e.g. 100).
PIPRAIL_MAX_PAYMENTS_PER_WINDOWCap on the number of payments within PIPRAIL_WINDOW_SECONDS (a rolling rate limit; set PIPRAIL_WINDOW_SECONDS too).
PIPRAIL_WARN_AT_FRACTIONEmit an early-warning event when spend crosses this fraction of any cap, e.g. 0.8 (80%). Needs PIPRAIL_EVENT_LOG to be visible.
PIPRAIL_SPEND_LOGPath to a local append-only spend log. When set, the budget (lifetime, grand total, counts) SURVIVES a restart — hydrated from this file. No backend; you own the file.
PIPRAIL_EVENT_LOGMirror payment events (settled / declined / budget-threshold) as one-line JSON to 'stderr' or a file path — the operator's notification stream. Default: off.
PIPRAIL_TOKENSSecretComma-separated allowed token symbols, plus the alias 'native' for the chain's coin (default: USDC).
PIPRAIL_SCHEMESComma-separated payment schemes to settle (default: onchain-proof). Add 'exact' (onchain-proof,exact) to also pay standard x402 servers GASLESS on EVM + Solana (method auto-selected). Add 'upto' to also pay metered x402 servers on EVM (Permit2): sign a MAX, the server settles the actual <= max.

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages
npm@piprail/mcp0.10.0

Tools

8

Saved tool list · updated 2w ago

ParameterTypeRequiredDescription
querystringNoFree-text topic to search for (optional). Multi-word queries are fanned out per word and results are ranked by relevance, so "crypto price feed" finds the best matches even when no single listing contains that exact phrase.
networkstringNoCAIP-2 id, 'self' (your chain — default), or 'any' (all chains).
categorystringNoKeep ONLY this category, e.g. 'ai', 'finance', 'data' (strict).
assetstringNoKeep only resources paying in this token symbol, e.g. 'USDC'.
maxPricenumberNoDrop results advertised above this USD price.
minReliabilitynumberNoDrop results below this health score (0–100); unscored pass.
verifiedbooleanNoPrefer verified listings (402 Index).
sortenumNoOrdering. Default 'relevance' with a query, else first-seen.relevance | reliability | price | uptime | name
limitnumberNoMax results to fetch per index (default 20).

Details

From the project README

@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

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

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

Overview · Getting startedWhat it is · first run
Client setup · ConfigurationPer-client config · every env var
Tools · ModesThe 8 default tools (14 in sovereign) · headless vs supervised
Security · ChainsWhy it's safe · per-chain setup
Use as a library · FAQEmbed 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.

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.