PipRail

MCP server · agent payments · 28 chains · local-only

x402 agents, zero integration.

Hand any MCP client a budget-bound payment wallet. Claude Desktop, Cursor, Claude Code, Windsurf, VS Code, and Cline can pay x402-gated URLs on their own — across 28 chains, capped by a spend policy the model cannot exceed. No backend, no custody, no code.

$ npx -y @piprail/mcp
@piprail/mcp on npm

Add it in one block.

Drop this into your MCP client with your wallet key and a budget. The defaults are deliberately small and safe — 0.10 per payment, 10.00 lifetime per token, USDC on Base.

claude_desktop_config.json 
// claude_desktop_config.json — paste, restart, done
{
  "mcpServers": {
    "piprail": {
      "command": "npx",
      "args": ["-y", "@piprail/mcp"],
      "env": {
        "PIPRAIL_PRIVATE_KEY": "0x…",
        "PIPRAIL_CHAIN": "base",
        "PIPRAIL_MAX_AMOUNT": "0.10"
      }
    }
  }
}

Restart your client — the tools appear.

Never commit your key. Cursor, Claude Code, Windsurf and VS Code support ${env:PIPRAIL_PRIVATE_KEY} interpolation — keep it out of the file. Claude Desktop takes the plain value, so treat that config as a secret.

Quote, plan, pay.

The moment the server connects, your agent gains a complete, safe payment workflow.

01

piprail_quote_payment

Read the exact price of a gated URL — without paying.

02

piprail_plan_payment

Check balance, gas, recipient-readiness, and your spend policy in one read-only call across every rail — and say which rail to use, or exactly what to top up.

03

piprail_pay_request

Fetch the URL with payment attached, on the cheapest rail you can afford, and return the resource.

Budget-bound and local-only. The policy is enforced on-chain before any send, so the model can't overspend even if it tries — and no key ever leaves your machine.

Find, and be found.

Two more tools turn the wallet into a marketplace participant — built on the open x402 indexes (CDP Bazaar, 402 Index). Nothing PipRail-hosted: no registry, no database, no fee.

piprail_discover

Search the open x402 indexes for payable APIs — the phone book. Filtered to your chain by default; no paying.

piprail_register

List an endpoint you run on the open indexes (402 Index — no auth, no signature) so other agents discover it.

@piprail/sdk — you write the code

For developers building a paid endpoint or a paying agent in TypeScript: requirePayment / createPaymentGate to charge, PipRailClient to pay.

@piprail/mcp — you add an env block

For AI/agent operators: no code at all. Add the wallet and the limits, and agents in your MCP client pay autonomously. Same engine, same 28 chains, same self-custody.

Works in every MCP client.

Same tools everywhere. Here's where each client keeps its config.

Configuration.

All config is environment variables — never CLI arguments (a key in argv leaks). Canonical names below; the wallet key also accepts the AGENT_KEY alias.

Variable Required Default Meaning
PIPRAIL_PRIVATE_KEY yes — Wallet key/seed for the chosen chain (alias: AGENT_KEY). Env-only, never a CLI arg.
PIPRAIL_CHAIN no base Chain to pay on — any of the 28 PipRail supports.
PIPRAIL_MAX_AMOUNT no 0.10 Max spend per single payment (token units).
PIPRAIL_MAX_TOTAL no 10.00 Lifetime spend cap per token (token units).
PIPRAIL_TOKENS no USDC* Allowed token symbols + "native" for the chain coin (CSV). *Defaults to USDT on Tron & TON.
PIPRAIL_HOSTS no any Host allowlist (CSV; supports *.example.com).
PIPRAIL_RPC_URL no chain default Override the RPC — fold any API key into this URL.
PIPRAIL_NEAR_ACCOUNT_ID NEAR only — Your NEAR account id (e.g. you.near).

Wallet key format, per chain

EVM (base, ethereum, …), Tron private key — 0x… 32-byte hex
Sui private key — suiprivkey1… (bech32)
Aptos private key — ed25519-priv-0x… or raw 0x… hex
Solana secret key — base58
TON mnemonic — 24 words
Algorand mnemonic — 25 words
Stellar secret seed — S…
XRPL seed — s…
NEAR private key ed25519:… + PIPRAIL_NEAR_ACCOUNT_ID

Why it's safe.

The spend policy is the boundary — and it's enforced where it counts.

Caps enforced before any send

Per-call and lifetime-per-token limits are checked against the token's true on-chain decimals — a server can't understate a price to slip past a cap. Over budget → declined, nothing moves.

No custody, no backend

Runs locally with your key, your RPC, your limits. Payments settle wallet-to-wallet — PipRail holds nothing and runs no service. Nothing to compromise.

Open and auditable

MIT-licensed and open source — read it, audit it, run it yourself. No key ever leaves your machine.

Pay across all 28 chains — 19 EVM mainnets plus Solana, TON, Tron, NEAR, Sui, Aptos, Algorand, Stellar, and the XRP Ledger. EVM works out of the box; non-EVM chains pull their SDK peer on demand. See every chain →

MCP FAQ.

Setting up agent payments — answered for humans and agents alike.

Can I use PipRail with Claude Desktop?

Yes. @piprail/mcp is an MCP (Model Context Protocol) server, so it runs in any MCP client — Claude Desktop, Cursor, Claude Code, Windsurf, VS Code, and Cline. Add one entry to your client’s config with your wallet key and spend limits, restart, and five tools (piprail_discover, piprail_quote_payment, piprail_plan_payment, piprail_pay_request, piprail_register) appear in the agent’s tool list. No code, no backend.

How do I set up @piprail/mcp?

Add it to your MCP client’s config with two things: your wallet private key and (optionally) a budget. For Claude Desktop, open Settings → Developer → Edit Config and add an mcpServers entry that runs "npx -y @piprail/mcp" with env PIPRAIL_PRIVATE_KEY, PIPRAIL_CHAIN, PIPRAIL_MAX_AMOUNT, and PIPRAIL_MAX_TOTAL. Restart the client. Cursor, Claude Code, Windsurf, and VS Code support ${env:PIPRAIL_PRIVATE_KEY} interpolation so the key never sits in the config file.

How does spend budgeting work — can the agent overspend?

No. PIPRAIL_MAX_AMOUNT caps each individual payment and PIPRAIL_MAX_TOTAL caps lifetime spend per token. Both are enforced by the SDK before any on-chain send, and checked against the token’s true on-chain decimals — so a malicious server can’t slip past a limit by misstating the price. An over-budget request comes back as { declined: true, reason } and nothing moves. You can also restrict tokens (PIPRAIL_TOKENS) and destination hosts (PIPRAIL_HOSTS).

What happens if an agent tries to pay something out of policy?

The call is declined before any on-chain send and returns { declined: true, reason } — the model never signs and never broadcasts. Because piprail_plan_payment is read-only, the agent can also check affordability and policy compliance up front and avoid the failed attempt entirely.

Which AI clients and chains does the MCP support?

Clients: Claude Desktop, Cursor, Claude Code, Windsurf, VS Code, and Cline — any MCP client. Chains: all 28 PipRail supports — 19 EVM mainnets plus Solana, TON, Tron, NEAR, Sui, Aptos, Algorand, Stellar, and the XRP Ledger. EVM works out of the box (the server ships with viem); non-EVM chains pull their SDK peer library on demand. Each server instance is one wallet on one chain — register it once per chain to give an agent several rails.

Does the MCP take custody of my funds or run a backend?

No. The server runs locally on your machine with your key, your RPC, and your limits. Payments settle wallet-to-wallet straight to the recipient — PipRail runs no service and holds nothing. There’s no PipRail backend to compromise and no facilitator in the path. The server code is MIT and open; you can audit or run it yourself.

What’s the difference between @piprail/sdk and @piprail/mcp?

The SDK is for developers who write code — you call requirePayment / createPaymentGate to charge, or PipRailClient to pay, in TypeScript. The MCP flips that: you write no code, you add an env block, and agents in your MCP client pay x402 URLs autonomously, capped by a spend policy. Same engine, same 28 chains, same backendless self-custody — the MCP is the zero-integration path for AI/agent operators.

Give your agent a wallet.

One env block, budget-bound, on every chain that matters.

npm install GitHub Read the docs