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 humanfx

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 the deployed protocol endpoint.
• APP_BASE_URL selects the first-party AgentBank web app used for onboarding, KYC, World ID, and payment action pages. It defaults to http://localhost:5173.

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 and repository development

The published humanfx binary always starts with the production tool surface. Runtime environment variables cannot enable development-only tools.

Repository contributors can start the development surface with:

yarn dev

Development additionally exposes test_send_evm_transaction. The diagnostic tool accepts only confirmed_by_user, to, value, data, and chain_id; it generates its internal idempotency key automatically. The repository-only development launcher is not included in the npm package.

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.