AiFinPay MCP server for persistent agent identity, Agent Passport resolution, route discovery and non-signing settlement invoices. Canonical domain: aifinpay.io.

Version 2.2.4. Owner-enabled native Polygon v1.4 purchases with payable_fetch are released (since 2.2.0). Without payment configuration the server keeps its inspection-only tool inventory.

Enable native paid GET requests

Use a persistent wallet created with public npx @aifinpay/mcp init or an existing configured identity. Keep its passphrase private. The owner must set:

{
  "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.05"
}

Limits are examples, not authorization. USD limits cover purchases; gas has its own per-transaction POL cap. Origins are exact HTTPS origins authorized by the owner. direct uses the full path for self-hosted sites; gateway uses the merchant slug on the hosted gateway. Restart/reconnect the MCP process after changing its environment.

To pay in USDC instead of native POL, the owner also sets "AIFINPAY_PAY_ASSET": "USDC". The wallet then needs USDC for the batch and a little POL for gas (an exact-amount token approval plus the settlement, both within AIFINPAY_MAX_GAS_POL together). Unset or "POL" keeps native POL.

Call payable_fetch({"url":"https://merchant.example/api/data"}). The tool uses the original signed v1.4 quote, independent fresh POL/USD pricing, SDK runtime/signer verification and owner limits. It persists the prepared transaction before sending, verifies the receipt, and reuses the purchased batch. No special merchant script, alternate contract or facilitator fallback is used. GET, Polygon live mode only, in POL or the configured stablecoin; Amoy payment receipts are not supported. The smallest batch is $0.10 plus gas, so keep AIFINPAY_MAX_USD a little above the batch you expect to buy.

Network access

A sandbox that allowlists outbound hosts must allow api.aifinpay.io (quotes and receipts) and a Polygon RPC. The independent POL/USD rate comes from Chainlink on Polygon over that same RPC, then api.coinbase.com, then api.coingecko.com; one of them is enough. If none answers, payable_fetch stops before paying and the error names each host it tried.

Link the agent to its owner's dashboard

The owner sees the agent's balance, payments and receipts at https://dash.aifinpay.io → My Agents. There, Claim via MCP generates a one-time URL; pass it to agent_claim_self. The tool contacts only AiFinPay origins, signs only the claim challenge for this agent's own address, and moves no funds. Offer this to the owner after init.

Private recovery state lives at AIFINPAY_HOME/payments/<evm-address>/state.json (default home ~/.aifinpay). State is mode600 in mode700 directories, atomically written and fsynced. One operation lock serializes the wallet across processes. A retry recovers a pending receipt before allowing another purchase. A process crash leaves the lock for owner reconciliation; it is never stolen automatically. If a prepared transaction was never broadcast or reverted, reconcile its exact hash before clearing anything. Never put raw transactions, receipt JWTs or the state file in chat. Unconfirmed payments consume the budget conservatively.

Tools

Tool	Purpose
`agent_address`	Read the current Solana, EVM and Casper addresses.
`agent_claim_self`	Link this agent to its owner's dashboard (one-time URL).
`agent_reload`	Reload local wallet files in the current MCP connection.
`agent_quota`	Read the agent's quota.
`agent_passport_resolve`	Resolve the global Agent Passport identity.
`settlement_routes`	Read the available verified settlement routes.
`settlement_invoice`	Prepare a non-signing settlement invoice.

payable_fetch appears only with valid owner payment configuration and a persistent wallet. Legacy agent_call, agent_quote, pay_with_split and quote_split remain unregistered.

Persistent wallet selection

The CLI (init and stdio), programmatic server and agent_reload use the same priority:

SEED_HASH: an existing 32-byte seed encoded as 64 hex characters, optionally prefixed with 0x. It is passed directly to AiFinPayAgent.fromSeed; do not hash it again or supply a mnemonic.
./aifinpay/agents.json, relative to the MCP process's working directory. Set an absolute AIFINPAY_AGENTS_FILE when a desktop client's working directory differs from the project directory. The file contains an agents array of records with id and private seed_hash fields. If there is more than one record, select exactly one with AIFINPAY_AGENT_ID.
AIFINPAY_AGENT_SECRET: a legacy base58 Solana secret.
~/.aifinpay/agent.json, or AIFINPAY_HOME/agent.json: the legacy CLI keystore. Encrypted files require AIFINPAY_WALLET_PASSPHRASE.

Keep seeds and wallet files private and out of chat, source control and logs. Invalid or ambiguous configured inputs fail; they never generate a replacement wallet. With no configured wallet at all the server has an ephemeral identity: do not fund it.

Initialize and connect

A quote or invoice is not a completed payment. payable_fetch pays only with the owner configuration above.

Local configuration

AIFINPAY_WALLET_PASSPHRASE='<a long passphrase>' npx @aifinpay/mcp init

The keystore is encrypted at rest and the MCP server needs the same AIFINPAY_WALLET_PASSPHRASE to load it. For a disposable test wallet only, npx @aifinpay/mcp init --plaintext writes it unencrypted (mode 600); without either, init refuses rather than create an unencrypted wallet you might fund.

Select the wallet in this order: SEED_HASH → ./aifinpay/agents.json → legacy AIFINPAY_AGENT_SECRET → ~/.aifinpay/agent.json. SEED_HASH means a 32-byte hex seed, passed directly to SDK fromSeed. See the skill for the exact project-file schema and multi-agent selection. init prints the selected wallet's public addresses. If a seed or project wallet is already configured, it does not create a second legacy wallet. With no wallet, it creates the legacy keystore with mode 600; existing keystores are retained. Back up that file privately. Use the published release or build this source checkout.

Use an absolute AIFINPAY_AGENTS_FILE path when the host's working directory is not your project directory. Do not put the seed itself in a shared config. A client configuration can use the keystore without embedding its secret:

{
  "mcpServers": {
    "aifinpay": {
      "command": "npx",
      "args": ["-y", "@aifinpay/mcp@2.2.0"],
      "env": {
        "AIFINPAY_AGENTS_FILE": "/absolute/project/aifinpay/agents.json",
        "AIFINPAY_AGENT_ID": "research-agent"
      }
    }
  }
}

The release above must be published before this npx command can install it. After the pinned dependencies are published, source checkouts can run npm ci && npm run build in mcp/ and configure node /absolute/path/to/mcp/bin/aifinpay-mcp.js instead.

If using the legacy keystore, run npx @aifinpay/mcp init once and omit the project-file variables. Optional AIFINPAY_WALLET_PASSPHRASE encrypts that legacy file at creation. An already connected server can load it with agent_reload; it does not need a new conversation. A changed package or launch environment requires a server reconnect, subject to host support.

History

Connect the MCP server once. After init or a wallet file update, call agent_reload in that same connection; no new conversation is required. A failed reload keeps the previous wallet. Changed shell environment variables require reconnecting the MCP process, since its environment is a startup snapshot. Verify agent_address against the wallet you intend to use.

Other environment variables

Variable	Default	Purpose
`AIFINPAY_BASE_URL`	`https://aifinpay.io`	Backend URL.
`AIFINPAY_TIMEOUT_MS`	`30000`	Request timeout.
`AIFINPAY_MAX_USD`	—	Configures the underlying agent's per-call cap; it does not enable signing.
`AIFINPAY_GATEWAY_ORIGINS`	SDK default	Comma-separated exact HTTPS origins trusted for AIFP-1 settlement.
`AIFINPAY_GATEWAY_PATH_MODE`	`gateway`	Use `gateway` for merchant-slug identity or `direct` for full request-path identity.

agent_history({address, source:"transactions"}) reads indexed Polygon settlements; source:"receipts" reads retained batches, including test-mode payments. Pass passport instead of, or alongside, address to resolve a public passport first. A backend without the passport resolver cannot satisfy passport-only queries. No secret API key is needed for public metadata.

Responses do not include bearer receipts. Limits are 1..100; follow next_offset. History source/coverage is explicit: it is not a full wallet explorer. Dev networks currently use receipt history, not the Polygon ledger.

const { server } = await createServer(loadConfigFromEnv());
await server.connect(new StdioServerTransport());

The programmatic equivalents of identity environment options are seedHash, agentsFile, agentId, agentSecretB58, walletHome and walletPassphrase.

AIFINPAY_BASE_URL: backend origin; default https://aifinpay.io.
AIFINPAY_HOME: directory of the legacy agent.json keystore.
AIFINPAY_MODE=dev: expose dev_payment_quote; requires a separate dev base URL.
AIFINPAY_TIMEOUT_MS: SDK request timeout.
AIFINPAY_MAX_USD: legacy per-call budget; does not enable signing.
AIFINPAY_TRUSTED_HOSTS: exact hosts allowed to bypass the DNS pre-check.
AIFINPAY_ALLOW_PRIVATE_FETCH=1: explicit local-development network access. Never enable this on the public hosted MCP.

For a self-hosted AIFP-1 gateway, set AIFINPAY_GATEWAY_ORIGINS to exact HTTPS origins. AIFINPAY_GATEWAY_PATH_MODE=direct makes the process use each request's full pathname as its AIFP-1 resource identity; gateway uses the merchant slug. The mode is process-wide, does not broaden the trusted-origin allowlist, and does not enable the retired signing tools in the production RC.

Dev quoting does not bypass wallet signatures, issuer verification or receipt metering. See the bundled skill for backend prerequisites. The low-level SDK has an Amoy executor; this MCP does not expose Amoy paid receipt purchases.