AgentBank (useagentbank.com): crypto banking services for AI agents. Agents collect money, move it, and pay bank accounts, QR codes and wallets in local currency, with the human owner confirming every payment. This repository is the MCP client (
agent-bank-mcpon npm). Hosted remote MCP: https://mcp.useagentbank.com. Docs: https://docs.useagentbank.com. License: MIT.
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.
The published package is production-locked. Install it without a mode override:
codex mcp add agentbank -- npx -y agent-bank-mcp@latestPROTOCOL_BASE_URL, APP_BASE_URL, and AGENTBANK_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 AGENTBANK_MCP_PROFILE for each client or human account on the same
device. The safest deployment is one adapter process per MCP client profile.
Related MCP server: BankSync MCP Server
PROTOCOL_BASE_URL selects the Protocol Core API. It defaults to
https://protocol.useagentbank.com/.
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://app.useagentbank.com/.
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.
Storage uses a deterministic per-user AgentBank vault. Profile records are encrypted, and the vault master key is protected by:
macOS Keychain
Windows current-user DPAPI
Linux per-user filesystem permissions
Backend selection never depends on ambient desktop, D-Bus, or XDG runtime state. For a managed headless host that supplies its own passphrase, configure:
AGENTBANK_MCP_CREDENTIAL_STORE=file
AGENTBANK_MCP_KEY_STORE_SECRET='choose-this-outside-the-model'AGENTBANK_MCP_CREDENTIAL_STORE=auto and keychain are accepted aliases for this same deterministic
vault; neither value enables environment-dependent auto-selection.
The managed encrypted file defaults to the platform configuration directory and can be
overridden with AGENTBANK_MCP_KEY_STORE_FILE. The passphrase is required at each
adapter startup; it is never persisted beside the encrypted file.
On Linux, the default vault and its master key are protected by the OS-user boundary (0700
directory and 0600 files). Copying the complete AgentBank MCP directory copies both, so hosts must
use disk encryption and protected backups when home-directory theft is in scope. Managed hosts that
need cryptographic separation should use file mode and inject its secret from outside the vault
directory and MCP-visible configuration.
The adapter never returns private keys, session tokens, API keys, or keychain values in tool results, prompts, logs, or conversation history.
The legacy HFX_MCP_* and HFX_AGENT_CREDENTIAL names remain accepted as
fallbacks for existing launch configurations. AgentBank names take precedence
and are the only names documented for new installations.
HTTP mode remains available for hosted deployments:
MCP_TRANSPORT=http PORT=8080 yarn startHosts on the same machine exchange an installation at POST /enrollment/session
and send the returned session as Authorization: Bearer ... to /.
In installation mode (the default, when MCP_HTTP_AUTH_MODE is not
remote_oauth), HTTP is a same-machine service:
the listener binds 127.0.0.1 unless MCP_HTTP_BIND_HOST is set explicitly;
every request must come from a loopback address (127.0.0.1 or ::1) and must
not carry X-Forwarded-For, Forwarded or X-Real-IP;
the Host header must be localhost, 127.0.0.1 or [::1] (any port), and
an Origin header, if present, must be a loopback origin (403 otherwise);
every POST must send Content-Type: application/json (415 otherwise).
remote_oauth mode is unaffected and returns 404 for /enrollment/session.
Over HTTP, a request without a bearer credential never falls back to
AGENTBANK_AGENT_CREDENTIAL or a process-level session. Personal desktop
installs should use stdio instead.
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 devRepository 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.
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.
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 token catalog
for the selected chain, 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 reads select the requested chain from EVM_CHAIN_CONFIGS (with legacy
EVM_RPC_URL as the Worldchain fallback); 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.
MIT © Thinking Horizon, Inc. See LICENSE.
This server cannot be deployed
Banking for AI agents: wallet, US bank account, prepaid cards, and Venmo, PayPal, and bank payouts.
Crypto banking services for AI agents: collect money and pay bank accounts in local currency.
Real-time AML and sanctions screening for agent-to-agent transactions
Agent payments, API key vaulting, and governed mandates. Agents spend within user-defined limits.
