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

Source candidate 2.2.0, paired with Node SDK 2.1.0. The published MCP 2.1.0 remains read-only; publish the coordinated dependencies before using this candidate through npm. Source builds support owner-enabled native Polygon v1.4 purchases with payable_fetch. 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.12",
  "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.

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, native POL, Polygon live mode only; Amoy payment receipts and stable-token execution are not part of this candidate.

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_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, quote_split and agent_claim_self 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. Enable the owner-configured payable_fetch tool only after installing the coordinated candidate dependencies.

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 candidate does not expose Amoy paid receipt purchases.