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
| Variable | Required | Default | Notes |
|---|---|---|---|
HODLE_API_KEY | Yes | — | API key; supplied through the environment. |
HODLE_API_URL | No | https://api.hodle.com.br | Hodle API base URL. |
HODLE_MCP_ALLOW_WRITES | No | false (unset) | Set to true to enable write tools. |
HODLE_WALLET_PIN | Only for payout/transfer/card sign-in | — | Wallet PIN. |
HODLE_PROTECTED_SYMMETRIC_KEY | Only for payout/transfer (optional for the card tools) | — | From POST /api/wallet/keys. |
HODLE_MCP_CARD_FUND_MAX_USD | No | 50 | Largest 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/mcpOr drop this into your project's .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):
{
"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:
[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:
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.
| Tool | Gated | Wraps |
|---|---|---|
hodle_quote | Read | POST /api/quote — Quote |
hodle_kyc_get | Read | GET /api/kyc — KYC |
hodle_account_statement | Read | GET /api/account/statement — Account statement |
hodle_wallet_get | Read | GET /api/wallet — Wallet get |
hodle_payout_status | Read | GET /api/wallet/payout/{transactionId} — Wallet payout |
hodle_subaccount_list | Read | GET /api/subaccount |
hodle_subaccount_get | Read | GET /api/subaccount/{subAccountId} |
hodle_wallet_payout | Write | POST /api/wallet/payout — Wallet payout |
hodle_wallet_transfer | Write | POST /api/wallet/transfer — Wallet transfer |
hodle_deposit_asset | Write | POST /api/deposit/asset — Deposit asset |
hodle_lightning_invoice | Write | POST /api/lightning/invoice — Lightning invoice |
hodle_subaccount_create | Write | POST /api/subaccount |
hodle_kyc_create | Write | POST /api/kyc (hosted flow) — KYC |
hodle_card_status | Read | GET /api/card — Card |
hodle_card_transactions | Read | GET /api/card/transactions — Card |
hodle_card_onboarding | Write | POST /api/card/onboarding — Card |
hodle_card_fund | Write | POST /api/card/fund and …/submit, capped per call — Card |
hodle_card_freeze | Write | POST /api/card/freeze — Card |
hodle_card_session | Write | POST /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
- Test reads before enabling writes.
- Install the
hodle-apiskill for flow guidance. - Use the API reference for request and response fields.