AgentBank MCP adapter

This package is intended to run locally as a per-device, per-client stdio MCP adapter. It owns the local installation key and short-lived AgentBank agent session, while Protocol Core remains the authorization and payment policy boundary.

Local stdio installation

The published package is production-locked. Install it without a mode override:

codex mcp add agentbank -- npx -y agent-bank-mcp@latest

PROTOCOL_BASE_URL, APP_BASE_URL, and HFX_MCP_PROFILE remain optional runtime configuration for local or self-hosted environments. A normal deployed installation does not need them.

The agent calls begin_agent_onboarding, relays the single authorization URL to the human, then calls wait_for_agent_onboarding. The adapter stores the installation key, Privy authorization, and agent session outside MCP tool content and restores the session on restart.

Use a different HFX_MCP_PROFILE for each client or human account on the same device. The safest deployment is one adapter process per MCP client profile.

Endpoint configuration

• PROTOCOL_BASE_URL selects the Protocol Core API. It defaults to https://protocol.agentbank.world/.
• APP_BASE_URL selects the first-party AgentBank web app used for onboarding, KYC, profile, and agent-authorization pages. Core-issued approval and payment action links are returned unchanged and use Protocol Core's FE_BASE_URL. APP_BASE_URL defaults to https://staging.agentbank.world/.

Both values have trailing slashes removed internally. Explicit environment variables continue to override these defaults.

Do not use the deprecated backend/frontend-oriented environment names.

Credential storage

Storage uses the OS credential manager when available:

• macOS Keychain
• Windows Credential Manager
• Linux Secret Service/libsecret

Set HFX_MCP_CREDENTIAL_STORE=keychain to fail closed if the native store is unavailable. The default auto mode falls back to an encrypted file. For a headless Linux host, configure:

HFX_MCP_CREDENTIAL_STORE=file
HFX_MCP_KEY_STORE_SECRET='choose-this-outside-the-model'

The fallback file defaults to the platform configuration directory and can be overridden with HFX_MCP_KEY_STORE_FILE. The passphrase is required at each adapter startup; it is never persisted beside the encrypted file.

The adapter never returns private keys, session tokens, API keys, or keychain values in tool results, prompts, logs, or conversation history.

Optional HTTP mode

HTTP mode remains available for hosted deployments:

MCP_TRANSPORT=http PORT=8080 yarn start

Trusted hosts exchange an installation at POST /enrollment/session and send the returned session as Authorization: Bearer ... to /mcp. Personal desktop installs should use stdio instead.

Production surface

The published agent-bank-mcp binary always starts with the 34-tool production surface. Runtime environment variables cannot enable repository-only diagnostic tools.

Repository contributors can start the development surface with:

yarn dev

Repository development may expose internal diagnostics. They are intentionally undocumented, are not included in the npm package contract, and must not be used by external agents.

get_supported_payment_capabilities is a public, static Markdown reference for the product's generally supported fiat, crypto, and swap capabilities. It is not a live route, amount, or user-readiness check; agents must use list_quote_book_pairs and an amount-specific quote before starting a payment.

Payment instruction execution

Production payment funding uses execute_payment_instruction. Its public input contains only request_id, payment_id, instruction_id, and confirmed_by_user; callers cannot provide a wallet, chain, token, spender, amount, target, value, calldata, or execution order.

Protocol Core resolves and pins the active payment instruction and bound Privy wallet. It skips an approval when allowance is already sufficient, otherwise submits an exact-amount approval before the transfer or swap. Sponsored sends are durably resumed with the same request ID, and Core automatically submits the final swap hash for payment verification. If execution is still pending, call execute_payment_instruction again with the same request ID.

approve_token remains available as a compatibility wallet utility, but it is not part of the normal payment journey. Production exposes no generic custom EVM transaction tool.

Wallet read tools

The high-level wallet surface also includes read-only chain tools:

• get_wallet_balances reads native and ERC-20 balances for the onboarding-bound Privy user wallet. Omit tokens to query the active AgentBank Worldchain token catalog, or provide explicit token addresses.
• get_token_allowance reads the bound wallet's ERC-20 allowance for a spender.
• get_transaction_receipt accepts either a chain transaction hash or the original wallet mutation request_id. The latter resolves Privy's asynchronous sponsored transaction ID before reading the final chain receipt.

Direct receipt reads use the configured EVM_RPC_URL; sponsored status polling uses Protocol Core so the Privy app secret never enters the local MCP. These tools do not move funds. Payment completion remains authoritative in get_payment.