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

and MPP are parsed and then refused with a reason recorded in your receipts.

• 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,

so a depeg makes the caps wrong by the depeg factor.

• 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,

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 claudedesktopconfig.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 PAYFETCHTESTMODE=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. paymentquote returns the terms, the selected quote, the trust-check result, your remaining budgets, and the policy decision (wouldpay 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.

Shortened. The full README is on GitHub.