Provides AI agents with a budget-bound payment wallet to pay x402 URLs using local spend policies and private keys.
Also known as piprail/piprail, mcp, @piprail/mcp
- Stars
- 10
- Tools
- 8
- Downloads, 30 days
- —
- Latest version
- 0.10.0
- Last commit
- Sep 10, 2026
- License
- MIT
What is PipRail MCP?
PipRail provides AI agents with a budget-bound payment wallet to pay x402 URLs using local spend policies and private keys. It exposes 8 tools, such as piprail_discover, piprail_quote_payment, piprail_plan_payment.
Summary generated from the project's README
About PipRail MCP server
PipRail provides AI agents with a budget-constrained payment wallet to interact with x402 URLs. It runs locally via stdio, allowing clients like Claude Desktop, Cursor, Windsurf, and VS Code to execute payments using your own private keys and spend policies. Because it operates without a backend or third-party custody, you maintain full control over your funds and limits.
The server includes eight standard tools such as piprail_discover, piprail_quote_payment, and piprail_pay_request. If you enable sovereign mode by setting PIPRAIL_MODE to sovereign, the toolset expands to fourteen, adding capabilities for selling, collecting earnings, and performing swaps. This mode allows an agent to both pay merchants and receive payments.
Users can configure the server to work across multiple chains like Base, Polygon, or Solana by providing specific keys for each. If no private key is provided, the server functions in a read-only mode where tools like piprail_budget and piprail_guide remain available, but actual money movement is restricted until a key is added.
What you can do with it
- 1Execute restricted merchant paymentsAn AI agent can pay for access to a protected URL while staying within a predefined spending limit.
- 2Manage multi-chain crypto assetsA developer can configure an agent to handle payments across different blockchain networks using specific keys.
- 3Perform read-only financial researchAn agent can investigate payment quotes and budgets without needing access to a private wallet.
Written from the project's README. Every use case is checked against a quote from it.
How to install PipRail MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall PipRail MCP in Claude Code
$ claude mcp add --env 'PIPRAIL_PRIVATE_KEY=<YOUR_PIPRAIL_PRIVATE_KEY>' mcp -- npx -y @piprail/mcpInstall PipRail MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@piprail/mcp"
],
"env": {
"PIPRAIL_PRIVATE_KEY": "<YOUR_PIPRAIL_PRIVATE_KEY>"
}
}
}
}Install PipRail MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@piprail/mcp"
],
"env": {
"PIPRAIL_PRIVATE_KEY": "<YOUR_PIPRAIL_PRIVATE_KEY>"
}
}
}
}Install PipRail MCP in VS Code CLI
$ code --add-mcp '{"name":"mcp","type":"stdio","command":"npx","args":["-y","@piprail/mcp"],"env":{"PIPRAIL_PRIVATE_KEY":"<YOUR_PIPRAIL_PRIVATE_KEY>"}}'Install PipRail MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@piprail/mcp"
],
"env": {
"PIPRAIL_PRIVATE_KEY": "<YOUR_PIPRAIL_PRIVATE_KEY>"
}
}
}
}Install PipRail MCP in Codex
$ codex mcp add mcp --env 'PIPRAIL_PRIVATE_KEY=<YOUR_PIPRAIL_PRIVATE_KEY>' -- npx -y @piprail/mcpInstall PipRail MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mcp] command = "npx" args = ["-y", "@piprail/mcp"] [mcp_servers.mcp.env] PIPRAIL_PRIVATE_KEY = "<YOUR_PIPRAIL_PRIVATE_KEY>"
Install PipRail MCP in Gemini CLI
$ gemini mcp add -s user -e 'PIPRAIL_PRIVATE_KEY=<YOUR_PIPRAIL_PRIVATE_KEY>' mcp npx -- -y @piprail/mcpInstall PipRail MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@piprail/mcp"
],
"env": {
"PIPRAIL_PRIVATE_KEY": "<YOUR_PIPRAIL_PRIVATE_KEY>"
}
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for @piprail/mcp 0.10.0 in an isolated container with no network and no keys. It answered and listed 8 tools.
PipRail MCP tools 8
Read from the server with tools/listpiprail_discoverRead-onlyFind x402 payment-gated resources on the OPEN indexes (a phone book of payable APIs) WITHOUT paying. Use it to answer "what can I buy?" — search by topic, then quote/plan/pay a chosen one. By default returns only resources payable on your wallet's chain (network='self'); pass 'any' for every chain. Results are cross-scheme: ALWAYS call piprail_quote_payment on a chosen resource (it re-checks the live price) before piprail_pay_request.
piprail_quote_paymentRead-onlyGet the price of an x402 payment-gated URL WITHOUT paying. Returns the amount, token, chain, recipient, and whether it is within the spend policy. Returns { gated: false } when the URL needs no payment. Call this first to decide whether a resource is worth buying.
piprail_plan_paymentRead-onlyCheck whether you CAN pay an x402-gated URL before paying. Reads your wallet balance, native gas, and whether the recipient can receive — across every rail the URL offers on your chain — and returns { gated, payable, best, options, fundingHint }. payable:false means do NOT attempt the payment; fundingHint says exactly what to top up. Call this before piprail_pay_request so you never commit to a payment you cannot finish. Returns { gated: false } when no payment is needed.
piprail_pay_requestActionFetch an x402 payment-gated URL, automatically making the required payment if needed (subject to the spend policy + approval hook). Pays whichever rail the client is configured for — PipRail's backendless on-chain rail, or, when enabled, the standard `exact` rail (where the buyer signs and the server settles, so no buyer gas). Returns the HTTP status, the response body, and a payment receipt if one settled. If the payment is refused by policy or the approval hook, returns { declined: true, reason } — no funds moved.
piprail_registerActionList an x402 payment-gated resource YOU run on the open indexes so other agents can discover it. Default target is 402 Index — no auth, no signature, no payment; a self-registered listing is pending review (verify your domain on 402index.io for instant approval). Returns one outcome per index ({ source, ok, detail, visibility, note }); a step the chain can't satisfy comes back ok:false with the reason. Moves no funds; nothing is PipRail-hosted. NOTE: index/agent payers are overwhelmingly standard `exact` clients — a default onchain-proof-only gate gets listed but they cannot pay it, so add an `exact` rail (and set the gate's `discovery` option, required for x402scan) to be usefully discoverable AND payable.
piprail_budgetRead-onlyRead how much of your spend budget and time leash is left — per (network, asset) remaining, the cross-token GRAND TOTAL per denomination (e.g. how much USD you can still spend across every stablecoin and chain), the payment-count leash, the session time envelope, and your spend so far. Use it in Mode A (headless) to self-check BEFORE paying, so you never discover the leash by hitting a decline. Read-only; moves no funds. NOTE: the time envelope is in-memory for THIS process; the money/count totals persist only if a spend store is configured.
piprail_guideRead-onlyRead the PipRail agent contract — the quote → plan → pay loop, how to read a refusal (and which declines are TERMINAL), the never-re-pay rule for broadcast-but-unconfirmed payments, and Mode A (headless) vs Mode B (supervised). Read-only; call it once if unsure how to use these tools.
piprail_verify_receiptRead-onlyRe-verify a PipRail VERIFIABLE RECEIPT against the chain — confirm a payment REALLY settled (the funds provably moved to payTo for AT LEAST the stated amount) WITHOUT trusting whoever handed you the receipt. Read-only and WALLET-FREE: pass the PipRailReceipt JSON (from a prior piprail_pay_request `verifiableReceipt`, or any third party). Returns { ok, onChain:{payTo,asset,amount,payer}, matchesClaims, ageSeconds, error? }: `ok` = the chain confirms the settlement; `onChain.payer` is RE-DERIVED from the tx and `matchesClaims:false` means the receipt forged the payer; `amount` is a verified lower bound. Pass `rpcUrl` for a chain outside the common presets.
Configuration
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_BASE_KEYPIPRAIL_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_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_MAX_AMOUNTMax spend per single payment, in token units (default: 0.10).
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_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_POLYGON_KEYPIPRAIL_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.
PIPRAIL_SOLANA_KEYPIPRAIL_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_TOKENSComma-separated allowed token symbols, plus the alias 'native' for the chain's coin (default: USDC).
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.
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablepiprail/piprail is public and reachablegithub.com/piprail/piprail ↗Pass
- Package names this repository as its source@piprail/mcp names piprail/piprail as sourcenpmjs.com/package/@piprail/mcp ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-09-10github.com/piprail/piprail ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @piprail/mcpPass
- No critical advisory in the package or its dependencies113 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHub@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 started | What it is · first run |
| Client setup · Configuration | Per-client config · every env var |
| Tools · Modes | The 8 default tools (14 in sovereign) · 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.
PipRail MCP questions
How do I add PipRail MCP to Claude Code?
Run claude mcp add --env 'PIPRAIL_PRIVATE_KEY=<YOUR_PIPRAIL_PRIVATE_KEY>' mcp -- npx -y @piprail/mcp in your terminal. Add --scope user to make it available in every project.
How do I add PipRail MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does PipRail MCP provide?
It exposes 8 tools, including piprail_discover, piprail_quote_payment, piprail_plan_payment, piprail_pay_request, piprail_register.
Does PipRail require a backend?
No, it runs locally with your wallet and your limits, meaning there is no backend, no custody, and no facilitator.
Can I use PipRail without a private key?
Yes, the server will boot in read-only mode, allowing you to discover, quote, register, budget, and guide, but you cannot move money until a key is added.
Can the agent pay across different blockchains?
Yes, you can list several chains and provide a unique key for each, allowing the tools to pay whichever chain a 402 request requires.