> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aifinpay.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect the AiFinPay MCP server

> Set up a persistent agent wallet, enable owner-limited payments, and link the agent to your dashboard.

`@aifinpay/mcp` connects AiFinPay tools to an MCP-compatible assistant. Install
[the payer skill](/skills) first so the assistant knows the workflow.

<Note>
  MCP 2.2.0 and later pay with `payable_fetch` once you enable payments below; without
  that configuration it only inspects. A quote or invoice does not move funds.
</Note>

## Initialize a persistent wallet

```bash theme={null}
npx @aifinpay/mcp init
```

`init` selects an existing configured identity or creates a local keystore.
The default file is `~/.aifinpay/agent.json`. Existing wallets are retained.
Since 2.2.3 a new wallet needs `AIFINPAY_WALLET_PASSPHRASE` (encrypted keystore);
`init --plaintext` creates an unencrypted one for disposable tests only. The MCP
process needs the same passphrase to read it.

On a first plaintext wallet creation in an interactive terminal, init also
prints a one-time recovery key. Prepare encryption before recording init;
never capture or share that recovery output.

Do not share seed backups, keystore contents or passphrases. The client can
work with public addresses; secrets should stay outside chat and recordings.
Do not fund an ephemeral identity.

## Connect your client

Add this server through your client's MCP settings:

```json theme={null}
{
  "mcpServers": {
    "aifinpay": {
      "command": "npx",
      "args": ["-y", "@aifinpay/mcp"]
    }
  }
}
```

For a custom wallet directory, configure `AIFINPAY_HOME` as its absolute path.
Configure an encrypted wallet's passphrase privately in the host environment.
Some desktop clients do not inherit terminal environment variables.

Connect or restart the server, then ask for `agent_address`. Compare it with
the address printed by init. If init ran while the server was connected,
`agent_reload` reloads wallet files in that connection. Changes to environment
variables or package versions require reconnecting the process.

## Enable payments

Fund the wallet's EVM address with **POL on Polygon** and add to the server's
environment (example limits):

```json theme={null}
{
  "AIFINPAY_PAYMENTS_ENABLED": "1",
  "AIFINPAY_GATEWAY_ORIGINS": "https://merchant.example",
  "AIFINPAY_GATEWAY_PATH_MODE": "direct",
  "AIFINPAY_MAX_USD": "0.15",
  "AIFINPAY_DAILY_USD": "1.00",
  "AIFINPAY_MAX_GAS_POL": "0.3"
}
```

The smallest batch is \$0.10 plus gas; keep `AIFINPAY_MAX_USD` a little above the
batch you expect.

`AIFINPAY_MAX_GAS_POL` caps the worst case, not the fee you expect to pay.
Before signing, the client prices the estimated gas plus 20% at the maximum fee
per gas the Polygon RPC quotes, and refuses with `V14_GAS_BUDGET_EXCEEDED` if
that exceeds the cap. The worst case follows the gas price: at about 280 gwei
(September 2026) it is about 0.10 POL for a POL payment and about 0.21 POL when
paying in USDC (`AIFINPAY_PAY_ASSET=USDC`: a token approval plus the
settlement). `0.3` covers both at that price; check the current Polygon gas
price and raise the cap when it is higher. The fee charged is usually a
fraction of the cap, but the wallet must hold the batch plus the worst case.

`payable_fetch` then buys and fetches GET resources on the
approved origins. It checks the POL/USD rate independently of the quote:
2.2.3 uses `api.coinbase.com`; 2.2.4 reads Chainlink on Polygon over the wallet's
RPC first, then Coinbase, then CoinGecko.

### Network access

In a sandbox that allowlists outbound hosts, allow `api.aifinpay.io`, a Polygon
RPC and a POL/USD 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](https://dash.aifinpay.io) → **My Agents** → **Claim via
MCP** you get a one-time URL; give it to the agent and it links itself with
`agent_claim_self` (2.2.4+). With 2.2.3, use **Add agent by address** instead.
You then see the agent's balance, payments and receipts.

## 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](/reference/mcp-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` | `1` registers `payable_fetch` (with the limits below) |
| `AIFINPAY_MAX_USD` / `AIFINPAY_DAILY_USD` | Per-payment and 24h USD limits |
| `AIFINPAY_MAX_GAS_POL` | Worst-case gas per payment, in POL; follows the gas price (see above) |
| `AIFINPAY_GATEWAY_ORIGINS` | Exact HTTPS origins the agent may pay |
| `AIFINPAY_GATEWAY_PATH_MODE` | `direct` for a site running its own paywall; `gateway` (default) for the hosted gateway |
| `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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.