Banco do Brasil

v0.1.0-alpha.1OAuth2alpha

BR top public bank (largest by assets). OAuth2 + mTLS + gw-dev-app-key. Pix, DICT, boleto cobranças, conta-corrente. Alpha on npm — devportal contract-gated, paths follow BACEN standard.

13 tools6 env vars🇧🇷 Brazilalpha — pending validation

Install

terminal

$ npm install @codespar/mcp-banco-do-brasil@alpha

Quickstart

Add this entry to your claude_desktop_config.json (or any MCP-compatible client config).

claude_desktop_config.json

{
  "mcpServers": {
    "banco-do-brasil": {
      "command": "npx",
      "args": [
        "-y",
        "@codespar/mcp-banco-do-brasil@alpha"
      ],
      "env": {
        "BB_CLIENT_ID": "<your_bb_client_id>",
        "BB_CLIENT_SECRET": "<your_bb_client_secret>",
        "BB_DEVELOPER_APP_KEY": "<your_bb_developer_app_key>"
      }
    }
  }
}

After restart, your agent can call any of the 13 tools below — try create_pix_cob first.

Environment variables · 6

Required to authenticate the server. Stored encrypted when using CodeSpar managed hosting.

BB_CLIENT_ID

required

Banco do Brasil OAuth client_id issued via developers.bb.com.br after contract onboarding.

BB_CLIENT_SECRET

requiredsecret

Banco do Brasil OAuth client_secret.

BB_DEVELOPER_APP_KEY

requiredsecret

BB Developer App Key (gw-dev-app-key) — appended as a query param on most BB API calls.

BB_CERT_PATH

optional

Absolute path to the mTLS client certificate (.crt or .pem). BACEN mandates mTLS for Pix v2 in production.

BB_KEY_PATH

optionalsecret

Absolute path to the mTLS private key (.key or .pem).

BB_ENV

optional

Environment: 'sandbox' or 'production'. Defaults to 'sandbox'.

Available tools · 13

Each tool is independent — your agent loads only what it needs to reduce context and response time.

WRITEcreate_pix_cob

Create an immediate Pix charge (cob) with QR code. Returns txid, EMV copy-paste payload, and location URL. BACEN Pix v2 standard.

READget_pix_cob

Retrieve an immediate Pix charge by its txid.

READlist_pix_cob

List immediate Pix charges (cob) by date range. Paginated per BACEN Pix v2.

WRITEcreate_pix_devolucao

Refund (devolução) a previously received Pix. Must reference the original endToEndId and a merchant-side refund id.

READget_pix_devolucao

Retrieve a Pix devolução by its endToEndId + refund id.

READresolve_dict_key

Resolve a DICT key (CPF, CNPJ, email, phone, EVP) to the owner's account data before sending a Pix. Subject to BCB rate limits per consenting payer.

WRITEregister_dict_key

DELETEdelete_dict_key

Delete a DICT key owned by the merchant. Irreversible — key becomes available for re-registration after BCB lockout window.

Compatible frameworks

MCP is a protocol — any framework that speaks it can mount this server.

Claude Agent SDKAnthropic

OpenAI AgentsOpenAI

Vercel AI SDKVercel

LangChainLangChain

LlamaIndexLlamaIndex

CrewAICrewAI

MastraMastra

Any MCP clientProtocol

Frequently asked questions

All credentials are encrypted at rest in an isolated vault scoped per organization. OAuth2 tokens are automatically refreshed before expiry. Your agent code never sees raw secrets — it receives scoped, short-lived session tokens.