MCP server

Install @hodle/mcp — a stdio MCP server that exposes the Hodle Platform API as tools for Claude Code, Cursor, Codex, and Hermes.

@hodle/mcp runs locally over stdio and exposes Hodle REST API tools to your agent.

Environment variables

VariableRequiredDefaultNotes
HODLE_API_KEYYes—API key; supplied through the environment.
HODLE_API_URLNohttps://api.hodle.com.brHodle API base URL.
HODLE_MCP_ALLOW_WRITESNofalse (unset)Set to true to enable write tools.
HODLE_WALLET_PINOnly for payout/transfer/card sign-in—Wallet PIN.
HODLE_PROTECTED_SYMMETRIC_KEYOnly for payout/transfer (optional for the card tools)—From POST /api/wallet/keys.
HODLE_MCP_CARD_FUND_MAX_USDNo50Largest card top-up one hodle_card_fund call may move, in USD.

Add the MCP server

Add it with the CLI:

claude mcp add hodle \
  -e HODLE_API_KEY=YOUR_API_KEY \
  -e HODLE_API_URL=https://api.hodle.com.br \
  -e HODLE_MCP_ALLOW_WRITES=false \
  -- bunx @hodle/mcp

Or drop this into your project's .mcp.json:

.mcp.json
{
  "mcpServers": {
    "hodle": {
      "command": "bunx",
      "args": ["@hodle/mcp"],
      "env": {
        "HODLE_API_KEY": "YOUR_API_KEY",
        "HODLE_API_URL": "https://api.hodle.com.br",
        "HODLE_MCP_ALLOW_WRITES": "false"
      }
    }
  }
}

Add this to ~/.cursor/mcp.json (or your project's .cursor/mcp.json):

~/.cursor/mcp.json
{
  "mcpServers": {
    "hodle": {
      "command": "bunx",
      "args": ["@hodle/mcp"],
      "env": {
        "HODLE_API_KEY": "YOUR_API_KEY",
        "HODLE_API_URL": "https://api.hodle.com.br",
        "HODLE_MCP_ALLOW_WRITES": "false"
      }
    }
  }
}

Reload Cursor's MCP settings from Settings → MCP after saving.

Add this to ~/.codex/config.toml:

~/.codex/config.toml
[mcp_servers.hodle]
command = "bunx"
args = ["@hodle/mcp"]

[mcp_servers.hodle.env]
HODLE_API_KEY = "YOUR_API_KEY"
HODLE_API_URL = "https://api.hodle.com.br"
HODLE_MCP_ALLOW_WRITES = "false"

Restart Codex CLI to pick up the new server.

Add this to ~/.hermes/config.yaml:

~/.hermes/config.yaml
mcpServers:
  hodle:
    command: bunx
    args: ["@hodle/mcp"]
    env:
      HODLE_API_KEY: YOUR_API_KEY
      HODLE_API_URL: https://api.hodle.com.br
      HODLE_MCP_ALLOW_WRITES: "false"

Then run /reload-mcp in a Hermes chat to pick it up without restarting.

Tools

Tools use HODLE_API_URL. Write tools require HODLE_MCP_ALLOW_WRITES=true and confirm: true on each call.

ToolGatedWraps
hodle_quoteReadPOST /api/quote — Quote
hodle_kyc_getReadGET /api/kyc — KYC
hodle_account_statementReadGET /api/account/statement — Account statement
hodle_wallet_getReadGET /api/wallet — Wallet get
hodle_payout_statusReadGET /api/wallet/payout/{transactionId} — Wallet payout
hodle_subaccount_listReadGET /api/subaccount
hodle_subaccount_getReadGET /api/subaccount/{subAccountId}
hodle_wallet_payoutWritePOST /api/wallet/payout — Wallet payout
hodle_wallet_transferWritePOST /api/wallet/transfer — Wallet transfer
hodle_deposit_assetWritePOST /api/deposit/asset — Deposit asset
hodle_lightning_invoiceWritePOST /api/lightning/invoice — Lightning invoice
hodle_subaccount_createWritePOST /api/subaccount
hodle_kyc_createWritePOST /api/kyc (hosted flow) — KYC
hodle_card_statusReadGET /api/card — Card
hodle_card_transactionsReadGET /api/card/transactions — Card
hodle_card_onboardingWritePOST /api/card/onboarding — Card
hodle_card_fundWritePOST /api/card/fund and …/submit, capped per call — Card
hodle_card_freezeWritePOST /api/card/freeze — Card
hodle_card_sessionWritePOST /api/card/session with the server wallet PIN — Card

Use it

Ask your agent:

Get a quote for converting R$500 (PIX) into USDC on Base.

The agent calls hodle_quote and returns the amount and fees.

What the gates do and do not do

Leave HODLE_MCP_ALLOW_WRITES unset to expose only read tools. confirm: true is set by the agent and does not represent human approval. Enable your MCP client's tool approval for write calls. For unattended agents, leave writes disabled.

Supply walletPin and protectedSymmetricKey through HODLE_WALLET_PIN and HODLE_PROTECTED_SYMMETRIC_KEY. Payouts and transfers require both. Never paste a user's PIN into chat.

The server holds one credential pair. hodle_wallet_payout therefore refuses subAccountId; use your own integration code with each subaccount's credentials for those payouts.

Card tools

The card tools accept subAccountId for a PF sub-account's card. They never return the card number, CVV or expiry. They never guess a step that belongs to the card holder: hodle_card_onboarding refuses SIGN_UP without the emailed otp, VERIFY_PHONE without the SMS phoneCode, and SUBMIT_SOURCE_OF_FUNDS without the holder's answers (errorCode: "HUMAN_INPUT_REQUIRED"), and results carry nextHumanAction (for example the kycUrl to hand to the holder) whenever a person has to act.

hodle_card_session opens or renews your own card session: Hodle unlocks the wallet with HODLE_WALLET_PIN (and HODLE_PROTECTED_SYMMETRIC_KEY when set; the API otherwise uses the wallet's stored key, same lockout as payouts) and signs the sign-in. Those credentials are the account holder's, so it refuses subAccountId: sign sub-account cards in from your integration with that wallet's own secret.

hodle_card_fund works in two calls: sourceKey + amount prepares a top-up (returns fundingId and signingHash), then fundingId submits it: signed by Hodle with the server wallet PIN (account holder only), or with a signature from an external wallet. Each call is refused above HODLE_MCP_CARD_FUND_MAX_USD (default 50 USD): before quoting for USDC/USDT sources, on the quoted USD amount for BRLA, and again on the stored quote before submitting.

When a write call times out

Writes time out after 60 seconds; reads after 15 seconds. A write timeout or connection failure returns outcomeUnknown: true: the operation may already have been accepted. Do not resend blindly. Check hodle_payout_status for a payout or hodle_account_statement for other operations before retrying.

Next steps