Skip to main content
@aifinpay/mcp connects AiFinPay tools to an MCP-compatible assistant. Install the payer skill first so the assistant knows the workflow.
MCP 2.2.x pays with payable_fetch once you enable payments below; without that configuration it only inspects. A quote or invoice does not move funds.

​
Initialize a persistent wallet

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:
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):
The smallest batch is $0.10 plus gas; keep AIFINPAY_MAX_USD a little above the batch you expect. 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. At 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. 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

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.