# AgentBank MCP adapter

> **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-mcp` on 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.

## Local stdio installation

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

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

`PROTOCOL_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.

## Endpoint configuration

- `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.

## Credential storage

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:

```bash
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.

## Optional HTTP mode

HTTP mode remains available for hosted deployments:

```bash
MCP_TRANSPORT=http PORT=8080 yarn start
```

Hosts 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.

## 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:

```bash
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 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`.

## License

MIT © Thinking Horizon, Inc. See [LICENSE](LICENSE).