Connect the AiFinPay MCP server

@aifinpay/mcp connects AiFinPay tools to an MCP-compatible assistant. Install the payer skill first so the assistant knows the workflow.

This page describes @aifinpay/mcp 2.12.1. Payments are on from the first start, within a built-in ceiling of $5 per payment and $20 per 24 hours; nothing in the MCP client config has to change to pay. payable_fetch signs only with a persistent wallet, so an unfunded fresh install spends nothing. A quote or invoice does not move funds.

First payment: init → fund → link → pay

Each step is one tool call or one command. Signing happens only in the last step, and only from a persistent wallet.

Init. Call payment_setup_status. If the wallet is ephemeral, run the command next_step gives — npx @aifinpay/mcp init, with an AIFINPAY_HOME=… prefix when the server uses its own wallet directory. Put the env it prints (the wallet passphrase) into the aifinpay entry of your MCP client config, then call agent_reload: the server switches to the persistent wallet and can pay in the same connection, without a restart. Never fund an ephemeral address.
Fund. Send the amount payment_setup_status reports in funding (the smallest batch, $0.10, at today’s rate plus the gas cap) to the wallet’s EVM address on Polygon.
Link. At dash.aifinpay.io → My Agents → Claim via MCP, generate a one-time URL and give it to the agent; it calls agent_claim_self. From then on you set the agent’s working limits under Controls (see below), and payment_setup_status shows them.
Pay. payable_fetch the URL. It reads the 402, buys the batch, retries with the receipt and returns the content; later requests reuse the batch.

Initialize a persistent wallet

npx @aifinpay/mcp init

init selects an existing configured identity or creates a local encrypted keystore (~/.aifinpay/agent.json, or $AIFINPAY_HOME/agent.json). Existing wallets are never overwritten.

In a terminal it asks for a passphrase (AIFINPAY_WALLET_PASSPHRASE).
Without a terminal (an agent running it, or AIFINPAY_NONINTERACTIVE=1) it generates the passphrase and prints one JSON document: the keystore path, the public addresses, and the exact env block for the MCP client config. The passphrase appears only there — treat that output as a secret.
If a keystore exists and cannot be opened, init does not replace it; its next_step suggests a new AIFINPAY_HOME instead.

init --plaintext creates an unencrypted keystore for disposable tests only. Do not share keystore contents or passphrases; the client works with public addresses.

Connect your client

Add this server through your client’s MCP settings:

{
  "mcpServers": {
    "aifinpay": {
      "command": "npx",
      "args": ["-y", "@aifinpay/mcp"]
    }
  }
}

Some desktop clients do not inherit terminal environment variables; put the env block from init in the server entry itself. Connect or restart the server, then ask for agent_address and compare it with the address init printed.

Change the limits

The working limits live in the dashboard. Once the agent is linked (step 3), open My Agents → the agent → Controls and set the per-payment cap, the daily cap, a merchant allowlist, an expiry, or pause it. AiFinPay enforces these on every quote and payment for that agent, immediately — no env change, no server restart. The agent sees them in payment_setup_status → dashboard. Underneath, the client keeps a local ceiling it refuses to sign above: $5 per payment and $20 per rolling 24 hours, with gas capped at 0.3 POL on Polygon. A payment has to pass both. To lower the ceiling or narrow the sites, set the optional overrides in the server’s env and restart the server (env is read at start; agent_reload re-reads only the wallet):

{
  "AIFINPAY_MAX_USD": "2",
  "AIFINPAY_DAILY_USD": "10",
  "AIFINPAY_GATEWAY_ORIGINS": "https://merchant.example",
  "AIFINPAY_MAX_GAS_POL": "0.3"
}

AIFINPAY_MAX_USD and AIFINPAY_DAILY_USD can only lower the ceiling. A value above $5 / $20 stops the server at start with a message pointing to the dashboard; it is never silently clipped. Higher limits belong in Controls, or in the Node SDK with its own budgets. Without AIFINPAY_GATEWAY_ORIGINS, the agent pays only a merchant that has verified its site with AiFinPay, and only on that very site: before signing, payable_fetch looks up the merchant the AiFinPay quote names and refuses unless the site is DNS-verified and its host is the host being fetched (on the hosted gateway, verification alone). A refusal signs and sends nothing. The money goes only to that merchant, never to an address a 402 claims. Setting AIFINPAY_GATEWAY_ORIGINS to exact HTTPS origins replaces this check with your own allowlist. AIFINPAY_PAYMENTS_ENABLED=0 switches payments off entirely. AIFINPAY_MAX_GAS_POL caps the worst-case fee, not the fee you expect to pay. Before signing, the client prices the estimated gas plus 20% at the maximum fee per gas the RPC quotes and refuses with V14_GAS_BUDGET_EXCEEDED above the cap. Paying in USDC (AIFINPAY_PAY_ASSET=USDC) takes an approval plus the settlement, so it needs roughly twice the gas of a POL payment. Payments settle AIFP-1 (splitter v1.4) on Polygon by default. To pay on Base, set AIFINPAY_PAY_CHAIN=base with AIFINPAY_MAX_GAS in ETH; the merchant must accept Base too. Where AiFinPay accepts payments right now is the networks field of x402.json. payable_fetch checks the native/USD rate independently of the quote: the Chainlink feed over the wallet’s RPC first, then Coinbase, then CoinGecko.

Network access

In a sandbox that allowlists outbound hosts, allow api.aifinpay.io, an RPC for the selected network and a price source (see above). Without a rate payable_fetch stops before paying and nothing is spent.

Link the agent to your dashboard

At dash.aifinpay.io → My Agents → Link an agent → Claim via MCP you get a one-time URL; give it to the agent and it links itself with agent_claim_self. Pass the URL to the tool: opened in a browser, or pasted into a chat without the AiFinPay MCP, it links nothing. You then see the agent’s balance, payments and receipts, and set its working limits under Controls: per-payment and daily caps, pause, merchant allowlist and expiry. AiFinPay enforces them on every quote and receipt for that agent, and the agent reads them back in payment_setup_status → dashboard (a read signed by its own key; it cannot change them).

Try the supported tools

Show my persistent agent address and my indexed transaction history. Then inspect the settlement routes and tell me which are enabled. Do not send a payment.

agent_history can inspect indexed Polygon transactions or receipt history; agent_quota reads quota reported by the AiFinPay meter. A self-hosted merchant meters locally, so this counter is not its authoritative remaining balance. Coverage is explicit in the response: these are not a full wallet explorer. See all registered tools. The bundled instructions are exposed as the MCP resource aifinpay://skill. Your client must read the resource to use them; connecting the server does not mean every host automatically loads every resource.

Configuration

Variable	Purpose
`AIFINPAY_HOME`	Directory containing the local `agent.json` keystore
`AIFINPAY_WALLET_PASSPHRASE`	Decrypt an encrypted keystore; keep private
`AIFINPAY_AGENTS_FILE` / `AIFINPAY_AGENT_ID`	Select a project identity by absolute file path and ID
`AIFINPAY_BASE_URL`	AiFinPay backend origin
`AIFINPAY_PAYMENTS_ENABLED`	Optional override. Unset or `1`: payments on (default); `0`: `payable_fetch` signs nothing and returns the setup checklist
`AIFINPAY_MAX_USD` / `AIFINPAY_DAILY_USD`	Optional override that lowers the ceiling the client checks before signing (default $5 per payment, $20 per 24h; a higher value is refused)
`AIFINPAY_PAY_CHAIN` / `AIFINPAY_MAX_GAS`	Pay on another served network (e.g. `base`) with a gas cap in its native currency
`AIFINPAY_PAY_ASSET`	`USDC` to pay in USDC instead of the native currency
`AIFINPAY_NONINTERACTIVE`	`1` makes `init` print JSON instead of prompting
`AIFINPAY_MAX_GAS_POL`	Optional override of the worst-case gas per payment in POL (default 0.3); follows the gas price (see above)
`AIFINPAY_GATEWAY_ORIGINS`	Optional allowlist: exact HTTPS origins the agent may pay; unset, only a merchant that verified the very site being fetched
`AIFINPAY_GATEWAY_PATH_MODE`	Optional override: `direct` for a site running its own paywall, `gateway` for the hosted gateway; unset, inferred from the origin
`AIFINPAY_MODE=dev`	Expose dev quoting with a separate dev backend

Wallet selection is: SEED_HASH, project agents file, legacy AIFINPAY_AGENT_SECRET, then the local keystore. Invalid or ambiguous configured identities fail instead of silently creating a different wallet.

Get started

Pay for services

Charge for your API

Reference

Connect the AiFinPay MCP server

First payment: init → fund → link → pay

Initialize a persistent wallet

Connect your client

Change the limits

Network access

Link the agent to your dashboard

Try the supported tools

Configuration