Banco MCP — Documentation

Última atualização: 28 de abril de 2026

What is Banco MCP?

Banco MCP is a read-only data connector between Open Finance Brasil (regulated by the Central Bank of Brazil) and AI assistants that support the Model Context Protocol (MCP). It lets you query bank accounts, balances, transactions, and credit card bills from any participating Brazilian institution — directly inside Claude, ChatGPT, Cursor, or any MCP-compatible client.

No money transfers, payments, or Pix. The connector exposes only read operations. The single write tool ( openfinance_disconnect_bank) revokes consent — it cannot move funds.

Getting started

1. Paste the URL

Copy the MCP URL and add it as a connector in your AI client:

  • Claude Desktop / claude.ai: Settings → Connectors → Add → paste https://api.mcp.ai/banco?tools=true
  • ChatGPT: Settings → Apps & Connectors → Create → paste https://api.mcp.ai/banco?tools=true
  • Cursor / IDE agents: Add remote MCP server with URL https://api.mcp.ai/banco?tools=true

2. Authorize with your bank

The first time the assistant tries to access your data, you will be redirected to the Open Finance consent flow — authentication happens directly on your bank's website. Banco MCP never sees your password.

3. Ask your AI

Once connected, you can ask things like:

  • “What is my current balance across all banks?”
  • “Show my transactions for March 2026”
  • “What's my credit card bill this month?”
  • “Categorize my expenses from last week”

Available tools

Banco MCP exposes 8 tools via the /banco endpoint. All tools are annotated with readOnlyHint / destructiveHint per the MCP spec — only openfinance_disconnect_bank is marked destructive (revokes consent; cannot move funds).

  • openfinance_list_connections (read-only) — Returns saved bank connections (connector_id, item_id, bank name) and a URL to link additional banks.
  • openfinance_get_item_status (read-only) — Returns the status of a bank connection (UPDATED, UPDATING, LOGIN_ERROR, OUTDATED, WAITING_USER_INPUT, etc.).
  • openfinance_list_accounts (read-only) — Returns BANK (checking/savings) and CREDIT (credit card) accounts with balance, type, and metadata.
  • openfinance_list_transactions (read-only) — Returns transactions for an account with date filters (from/to ISO), pagination (max 500/page), and an optional search_queries keyword filter (case- and accent-insensitive substring match across description and merchant, OR semantics).
  • openfinance_list_credit_card_bills (read-only) — Returns credit card bills: due date, total amount, minimum payment, allowsInstallments.
  • openfinance_list_investments (read-only) — Returns the investment portfolio for a connection: FIIs, stocks, ETFs, fixed income (CDB / LCI / LCA / Tesouro), mutual funds, retirement (previdência) and COE — with balance, amount invested, profit, monthly / annual / 12-month rate, due date, issuer and ISIN. Returns { total:0, results:[], warning } instead of throwing when the INVESTMENTS product is not enabled.
  • openfinance_list_investment_transactions (read-only) — Returns the movement history for a specific investment position: BUY / SELL / TAX / INTEREST / AMORTIZATION / TRANSFER, with quantity, value, netAmount, agreedRate (treasury) and itemized expenses (brokerageFee, incomeTax, settlementFee, custodyFee, etc.).
  • openfinance_disconnect_bank (destructive — revokes consent only) — Revokes the Open Finance consent for a specific bank and deletes the connection data. The bank's data will no longer be available. Cannot transfer money, initiate Pix, or alter any bank-side data.

Authentication

Banco MCP supports OAuth 2.1 with PKCE (S256) for AI clients that implement the MCP authorization spec (RFC 9728).

  • Authorization server metadata: GET /.well-known/oauth-authorization-server
  • Protected resource metadata: GET /banco/.well-known/oauth-protected-resource
  • Dynamic Client Registration: POST /oauth/register
  • Token endpoint: POST /oauth/token (authorization_code + refresh_token)

Clients that don't support OAuth (e.g. some IDE agents) can use the manual token flow: call the authenticate tool, open the provided URL, and paste the JWT token back.

Troubleshooting

All tools return structured warnings instead of throwing on recoverable upstream errors — read the warning field on the response before retrying. Common cases:

Connection status (openfinance_get_item_status)

  • UPDATED — Connection healthy, data is fresh.
  • UPDATING — Sync in progress. Wait 30–60 s and call openfinance_get_item_status again.
  • LOGIN_ERROR — Credentials changed at the bank, or MFA / 2FA expired. The user must reconnect through add_connection_url returned by openfinance_list_connections.
  • OUTDATED — Open Finance consent expired (max 12 months per Banco Central rules). Reconnect to grant a new consent.
  • WAITING_USER_INPUT — Bank requires MFA / 2FA / token. Open the bank app or the Pluggy widget via add_connection_url to complete.

Tool-level warnings

  • 403 INVESTMENTS / CREDIT_CARDS not enabled — openfinance_list_investments / openfinance_list_credit_card_bills return { total:0, results:[], warning } when the bank or the OF connection didn't grant that product. Reconnect and tick the missing product in the bank's consent screen.
  • 404 account_id not found — After a reconnect, account_ids may change. Call openfinance_list_accounts first to get the current id.
  • 429 rate limit — Internal MCP.AI throttle (2 req/s per Pluggy app). The warning includes a suggested retry window.
  • truncated:true on list_transactions — When search_queries aggregates more than 5 000 transactions in the from/to window. Narrow the date range and retry.

OAuth / authorization

  • 401 invalid_token on tools/call — The Bearer JWT expired. The MCP client should refresh it via the refresh_token grant; first request after refresh succeeds. Lazy-discovery clients receive a WWW-Authenticate header pointing at /banco/.well-known/oauth-protected-resource.
  • Browser blocked by CORS — The MCP server allows claude.ai, app.claude.ai, chatgpt.com, banco.mcp.ai and api.mcp.ai by default. Custom origins must be added to the allowlist — open a support ticket if your deployment needs another origin.
  • tools/list works but tools/call returns 401 — This is the lazy-OAuth pattern (RFC 9728). Anonymous initialize + tools/list are allowed for discovery; the first tools/call triggers the OAuth consent flow.

Empty results right after connecting

Open Finance institutions sync historical data asynchronously after the first consent — accounts and balances usually settle in 30–60 s, full transaction history in up to 5 minutes. Use openfinance_get_item_status until it returns UPDATED.

Need help

Email contato@mcp.ai with the item_id (from openfinance_list_connections) and the full warning string returned by the tool. From inside the AI conversation, the report_bug tool ships the full context (tool name, args, response, conversation snapshot) automatically.

Security

  • All traffic over TLS 1.3+
  • Open Finance connection tokens encrypted at rest (AES-256-GCM)
  • Balances, transactions and investments returned by the bank API are not persisted — they transit through our infrastructure only to be delivered to your MCP client
  • Read-only — no write operations on bank data
  • Consent revocable at any time via dashboard or bank app
  • LGPD — retention per privacy policy; revoke connections and request deletion as described there

Supported banks

All institutions participating in Open Finance Brasil: Nubank, Itaú, Bradesco, Santander, Banco do Brasil, Inter, C6, Caixa, BTG, Sicoob, Sicredi, Original, PicPay, Mercado Pago, and 100+ others. See full list →

Pricing

Plans start at R$19.90/month. See pricing on banco.mcp.ai. Cancel anytime, no penalties.

Support

contato@mcp.ai — for bugs, use the report_bug tool directly in your AI conversation.

Legal

Operated by DL WEB EIRELI — banco.mcp.ai

Documentation | Banco MCP