Payfetch MCP Server

payfetch

payfetch lets an AI agent fetch a URL and, when the server answers HTTP 402 (the x402 payment protocol), pay for it automatically, but only within a spending policy you control. It is non-custodial: you bring your own wallet, the key stays on your machine, and no MCP tool can raise the limits. It ships as a local stdio MCP server with a small library and CLI alongside it.

The reference x402 clients pay whatever a 402 asks for. payfetch is the opposite: the policy and safety surface is the point. Per-call, per-day, and per-host spend caps; host allow and deny lists; a human-approval threshold; optional pre-payment trust and safety checks; and an append-only local receipt for every attempt, whether it paid, was denied, was a dry run, or failed.

• Website: https://forum-labs.com
• Source: https://github.com/forum-labs/payfetch

Status and scope

• Version 1.0.0. Policy schema p3f.policy.v1, client schema p3f-1.0.0.
• x402 only, Base USDC, the exact scheme. Solana-settled x402, the upto scheme, and MPP are parsed and then refused with a reason recorded in your receipts.
• Requires Node 22 or newer. Windows is not supported.
• USD is treated as USDC at 1.00. Budgets are denominated in USD and settle in USDC, so a depeg makes the caps wrong by the depeg factor.

Install

The package ships compiled JavaScript, so there is no build step and no tsx for consumers. Run it on demand with npx:

# Operator CLI (status, verify, clear-autodeny, report):
npx @forum-labs/payfetch status

# MCP server (what an MCP client launches):
npx -p @forum-labs/payfetch payfetch-mcp

The package exposes two binaries: payfetch (the operator CLI) and payfetch-mcp (the stdio MCP server). Because there are two, the server is launched with npx -p @forum-labs/payfetch payfetch-mcp; the -p flag selects the named binary.

Quickstart

1. Configure a wallet (pick exactly one signer)

payfetch refuses to start if zero or more than one signer source is set. It never guesses which wallet to spend from.

Raw private key, the simplest option. Use a dedicated low-balance wallet:

export PAYFETCH_PRIVATE_KEY=0xabc...

Key file, which must be mode 600 (payfetch refuses to start otherwise):

printf '0xabc...' > ~/.payfetch-wallet.key && chmod 600 ~/.payfetch-wallet.key
export PAYFETCH_KEY_FILE=~/.payfetch-wallet.key

Coinbase CDP server wallet, where the keys are managed by CDP under your account instead of being pasted into an environment variable:

export PAYFETCH_CDP_API_KEY_ID=...
export PAYFETCH_CDP_API_KEY_SECRET=...
export PAYFETCH_CDP_WALLET_SECRET=...
export PAYFETCH_CDP_ACCOUNT_NAME=payfetch   # optional; stable name across restarts

2. Wire it into an MCP client

Claude Desktop, in claude_desktop_config.json:

{
  "mcpServers": {
    "payfetch": {
      "command": "npx",
      "args": ["-y", "-p", "@forum-labs/payfetch", "payfetch-mcp"],
      "env": {
        "PAYFETCH_PRIVATE_KEY": "0xabc...",
        "PAYFETCH_TEST_MODE": "1"
      }
    }
  }
}

Claude Code:

claude mcp add payfetch \
  --env PAYFETCH_PRIVATE_KEY=0xabc... \
  --env PAYFETCH_TEST_MODE=1 \
  -- npx -y -p @forum-labs/payfetch payfetch-mcp

The examples set PAYFETCH_TEST_MODE=1 so your first runs settle on Base Sepolia and never touch mainnet. Drop it when you are ready to spend real USDC.

3. First paid fetch

Quote before you pay. payment_quote returns the terms, the selected quote, the trust-check result, your remaining budgets, and the policy decision (would_pay or would_deny). It signs nothing and reserves nothing:

{ "url": "https://api.example.com/paid-endpoint" }

Dry run the whole pipeline. paid_fetch with "dryRun": true runs the exact code path a real payment takes, up to but not including the signature.

Pay for real with paid_fetch:

{ "url": "https://api.example.com/paid-endpoint", "maxAmountUsd": 0.25 }

maxAmountUsd tightens the per-call cap for this one call. It can only lower the limit, never raise it. If the price is above your approval threshold, a human is asked to confirm (see Approvals). The result carries the response body, the payment outcome and transaction reference, any warnings, and a receiptId.

The spending policy

Policy lives in {dataDir}/config.json (the data dir defaults to ~/.payfetch). On first run payfetch writes the defaults there so you can read and edit exactly what you are running. A missing file falls back to the defaults. An invalid file fails closed: every paying tool returns policy_config_invalid until you fix it, so a typo never silently restores a cap you lowered. The file is re-read when its mtime changes.

Only you can change the policy. No MCP tool mutates it and no tool clears an auto-deny. Agent-supplied parameters such as maxAmountUsd can only tighten, never loosen. Every denied paid_fetch result repeats this back to the agent so a prompt-injected model cannot mistake the boundary for something negotiable.

Caps

• caps.perCallUsd (default 1.00): maximum for a single payment.
• caps.dailyUsd (default 2.00): maximum per UTC day.
• caps.perHostDailyUsd (default 1.00): maximum per host per UTC day.
• caps.totalUsd (default null): optional lifetime cap.

Caps are hard and reserve before paying. A signed authorization is held against the budget until it provably expires, so budgets can over-count but never under-count. At most one payment attempt happens per request, so a retry loop cannot drain the wallet.

There is deliberately no default lifetime cap. The dedicated wallet's balance already bounds lifetime spend on-chain (see Security), so a software lifetime ceiling would be one more field to forget. Set totalUsd only if you want a software ceiling on top of a larger-balance wallet.

Allow and deny lists

mode is open by default. Set it to allowlist to pay only hosts listed in allow. Patterns in deny are always refused and win over allow. A pattern like *.example.com matches subdomains, not the apex.

Approvals

A payment whose price is strictly above approval.thresholdUsd (default 0.10) triggers approval. An approval authorizes one payment only. There is no "always allow", and it never widens future authority.

• elicit (default): the client prompts a human with the host, resource, amount, network and asset, guard results, and today's remaining budgets. They approve once or deny. The prompt times out after 120 seconds and is then treated as a denial. Some MCP clients cannot service an elicitation prompt (Claude Desktop cancels it immediately; Claude Code supports it). payfetch tells apart a real human "deny" from a client that simply cannot ask, and it never treats "cannot ask" as a silent denial. When a payment is blocked only because the client cannot elicit, the tool result says so and names the ways to allow it.
• queue: the payment is not executed. The result returns an approvalId. A human with approval authority resolves it with the approve_pending tool. An approved entry is a grant to re-run: the follow-up paid_fetch runs the full pipeline again and matches on host and exact amount. It expires after one hour, and drifted terms require a fresh approval.
• deny: anything above the threshold is refused, for unattended fleets.

For clients that cannot prompt a human, two config-only settings let above-threshold payments through without a dialog. Both are explicit operator authorization, not the agent's, and neither is reachable from a tool. approval.preApprovedUpToUsd (default null) auto-approves above-threshold payments up to a ceiling. approval.preApprovedHosts (default empty) auto-approves specific hosts. Both still pass through every cap and every guard.

Approval never bypasses caps. An approved payment that fails budget reservation is still denied.

approve_pending with {"action":"list"} is always allowed and shows the queue. Approving or denying an entry requires PAYFETCH_APPROVER=1 in the server's environment; without it the tool returns approver_not_enabled. An agent must not approve its own payments, so the server refuses to start if PAYFETCH_APPROVER=1 is combined with a queue-capable approval mode.

Receipts

Every outcome, including free fetches, dry runs, denials, and unknown-settlement cases, appends one immutable JSON line to the ledger:

{dataDir}/ledger/{yyyy-mm}.jsonl   # append-only, monthly rotation, fsync on payments
{dataDir}/state.json               # disposable cache, rebuildable from the ledger
{dataDir}/downloads/{receiptId}    # response bodies when responseMode is "file"

A receipt records the URL, method, and host; the outcome and deny code; the pipeline steps traversed; the selected quote and a tally of rejected quotes; guard results; approval info; the payment (payer address, nonce, validBefore, settled amount, transaction reference, and whether it confirmed); the budgets at decision time; and an HTTP summary. Key material, signatures, full payment payloads, response bodies, and request header values are never stored. Response bodies are recorded as a SHA-256 hash plus a byte count. URL query strings are stored, because this is your own audit trail on your own disk; guard calls, by contrast, strip the query (see Security). Nothing is rewritten. Corrections append p3f.adjust.v1 records.

Query receipts with the list_receipts tool (filter by time, host, or outcome) or spend_status (today's totals, holds, and recent payments). After repeated paid-but-bad outcomes a host is auto-denied for 7 days; clear it out of band with payfetch clear-autodeny <host>, never from a tool.

Trust and safety checks

payfetch can consult two checks before it pays. Both call paid Forum Labs APIs at https://api.forum-labs.com, and both are self-dealing that is disclosed here rather than buried: the guards call our own products. The default guard budget is 0, so by default the client uses only those products' free tier. Any paid guard usage is opt-in, budgeted with guards.*.dailyBudgetUsd > 0, and produces a receipt like any other spend.

The trust check is on by default in advisory mode. Before paying, it asks whether the target endpoint has a reliable history. In advisory mode it warns; in enforce mode it blocks on the configured verdicts (unreliable by default). New endpoints without enough history come back unrated and pass by default, so the check does not strangle them. This check is the client's only outbound call to us; see Security for exactly what it sends and how to turn it off.

The safety check is off by default. When enabled it screens a token mint you pass in (tokenAddress) against the Forum Labs token safety API and blocks on a danger verdict, or on a serial_rugger deployer verdict in deep mode. deep is always a paid screen, so it needs dailyBudgetUsd > 0.

Security and disclosure

Read this before pointing payfetch at a funded wallet.

The wallet balance is your real limit

The primary control on how much a bug or a prompt-injected agent can spend is the balance of the wallet you point payfetch at, not the software caps. A wallet's balance is a hard on-chain bound: payfetch cannot spend a dollar that is not in the wallet, whatever the config says or the agent is told to do. So the first thing to get right is the wallet.

Create a fresh wallet, fund it with only the amount you are willing to lose entirely (a few dollars for a trial, a capped top-up for production), and give payfetch that wallet. Never your main wallet. Refill it deliberately rather than by standing order.

The caps, lists, approval threshold, and guards are the fine-grained layer on top. They shape rate, per-target exposure, and detection within that balance. They are real and enforced, but the wallet balance is the circuit breaker and the caps are the scalpel. Set both.

Key custody

Your key is never transmitted to us, never logged, and never written to the receipt ledger. The ledger stores addresses and amounts, not keys, and that is asserted by a test. Keys are read from the environment in-process to sign EIP-3009 payment authorizations. A signed authorization is bounded to one asset, one amount, one recipient, and one time window. If you use PAYFETCH_KEY_FILE, payfetch refuses to start when the file is group- or world-readable, so chmod 600 it.

What the trust guard sends, and the off switch

While the trust guard is on, it makes one call to the Forum Labs trust API on every paid fetch. That call is the client's only egress to us. It sends the target endpoint with the query string stripped, plus a random per-install id. The query is stripped because a target URL's query can carry your own secrets; server-side we store a hash of the input, never the raw target, and the install id is used for aggregate counting only, never per-install profiling or resale. The install id is a random 32-hex value generated on first run and stored in your state file; delete the state file and it regenerates.

Turn the guard off with guards.trust.enabled: false. With it off, payfetch makes no external call at all: no guard result, no network request, nothing dialed. That is the complete off switch, and the honest cost of it is that operators who disable the guard are invisible to our adoption instrument.

Optional outcome reporting (off by default)

Reporting is off by default and changes nothing unless you turn it on. When you report an outcome, currently only per-incident with payfetch report <receiptId>, the client reports the outcome of a completed payment attempt (paid and delivered, or paid and not delivered), signed by your payment wallet and tied to the on-chain settlement, to the trust API. This is a fact about the seller's conduct that you are reporting. It is never a record of what you looked at. Lookups (guard checks, quotes, dry runs) are never retained per consumer.

A report sends exactly these fields and nothing else: the endpoint {method, url} with the query stripped; the outcome, derived from the receipt and never agent-supplied; structural checks (settlementConfirmed, a coarse HTTP status class, contentTypeOk, nonEmpty); the termsHash you paid under; the seller's payTo address, which is already on-chain; a coarse amountBand rather than the exact amount; the UTC day rather than an exact timestamp; and your payment wallet address plus an EIP-712 signature over the payload. A report never carries the query string, request headers or bodies, the response body, the receiptId, the exact amount, or the exact timestamp. The install id never rides on the report path, so the report wallet and the guard install id are never joined.

A settled x402 payment is already public (payer, payee, amount, and time are on the chain). What a report adds is the outcome bit. On very-low-traffic endpoints a seller may be able to infer that a report came from you, since the anonymity set is small; we mitigate with day granularity and bucketed publication, and we state the residual here rather than hide it. In this version the trust API verifies the signature (recover(sig) === payer), so a stranger cannot report on your behalf, but it does not yet prove the settlement, so reports are shown as unverified until they are settlement-matched in a later version. We will not monetize, publish, or attempt to deanonymize reporter wallets.

SSRF and private targets

Unless you set allowPrivateTargets: true, payfetch refuses non-http(s) schemes and any host that resolves to loopback, RFC1918, link-local 169.254/16, CGNAT, or ULA. A paying-fetch must not become the tool that exfiltrates 169.254.169.254. DNS is pinned, so the vetted IP is the one dialed; every redirect hop is re-checked; and an https to http downgrade aborts.

What payfetch does not protect against

Fetched content is untrusted input to your agent. A malicious page can tell the agent to fetch or pay somewhere else. payfetch bounds the damage with the dedicated wallet's balance and the caps, lists, approval threshold, receipts, and SSRF block, but it cannot make the agent wise. It cannot stop an injected agent from spending within policy, so keep the wallet balance small. For untrusted-content workloads, tighten the defaults:

{
  "mode": "allowlist",
  "allow": ["api.trusted-vendor.com"],
  "caps": { "perCallUsd": 0.05, "dailyUsd": 0.50, "perHostDailyUsd": 0.25 },
  "approval": { "thresholdUsd": 0.0, "mode": "elicit", "elicitFallback": "deny" },
  "guards": { "trust": { "enabled": true, "mode": "enforce" } }
}

thresholdUsd: 0.0 sends every payment to a human. mode: "enforce" blocks on an unreliable verdict instead of only warning.

Two more limits worth stating plainly. There is no on-chain settlement verification yet: settlement facts come from the server's payment-response header, so a lying server can misreport. Both error directions over-count, which is the safe direction, and on-chain verification is planned. And the ledger is single-instance: one lockfile, one process, one machine. A fleet needs a policy plane that is not built here.

Configuration reference

Defaults, from {dataDir}/config.json, schema p3f.policy.v1:

Environment variables read by both the server and the CLI:

Test mode

Set PAYFETCH_TEST_MODE to any value. Then every receipt is stamped test: true and excluded from metrics, and Base mainnet quotes are refused so a self-test can never touch mainnet spend. Only Base Sepolia settles. Use it to run the end-to-end Base Sepolia path before spending real USDC.

CLI

The payfetch CLI reads the same environment as the MCP server.

# Reset a host's auto-deny circuit breaker (an operator action, not a tool).
npx @forum-labs/payfetch clear-autodeny api.example.com

# Print today's spend status as JSON.
npx @forum-labs/payfetch status

# Verify the ledger tamper-evidence sidecar (exits non-zero on any integrity gap).
npx @forum-labs/payfetch verify

# Report a paid outcome for a receipt (opt-in, off by default). Prints the exact
# wallet-signed payload, asks for confirmation, then submits. Never an MCP tool, so
# the agent can neither file nor suppress a report. Use --yes to skip the prompt.
npx @forum-labs/payfetch report <receiptId>

status builds the engine and takes the single-writer lock. If the MCP server is already running, use the spend_status tool instead, or stop the server first.

Manual .mcpb install

Directory submission is not offered for payment connectors, so payfetch is packaged for manual install. Build the bundle:

npm run build:mcpb        # produces dist-mcpb/payfetch.mcpb

This runs tsc, then esbuild-bundles the built server entry and its runtime dependencies into a single self-contained ESM file, and packs it with the mcpb tool. The result is a small .mcpb zip holding manifest.json alongside the bundled server. No node_modules is shipped, so Claude Desktop installs it without running npm install. In Claude Desktop, go to Settings, Extensions, Install from file, choose the .mcpb, then fill in exactly one signer option. The bundling logic is in mcpb/build.mjs and the manifest is mcpb/manifest.json.

From source

npm install         # dev dependencies, including tsx for the from-source flow
npm run typecheck   # tsc --noEmit
npm test            # vitest, hermetic, no network
npm run build       # emit dist/, the compiled JS the package ships

License

MIT. See LICENSE. Copyright (c) 2026 Forum Labs.