Connect an agent (MCP)

Bolívar Connect has an MCP server so that an agent (Claude Code, Cursor or any MCP client with HTTP transport) can look into your operation and, in your test account, integrate end to end: from zero to your first payment.settled just by talking to it.

Server URL	https://qa.bolivarconnect.com/mcp
Authentication	Claude’s Connect button (Bolívar Connect sign-in), or Authorization: Bearer <your key>
Transport	Stateless HTTP: only POST /mcp (no SSE)

To operate, use your test key

Use the sk_test_ key of your test account: it is the only one the agent can write with, and everything it does uses simulated money. With an sk_live_ key the agent only reads.

Connecting with Claude

With the Connect button, Claude opens a Bolívar Connect page: there you paste your API key (see Before connecting) or continue without a key. Never paste your key into the chat: only on that page.

claude.ai and Claude Desktop

Add to Claude

1. The button opens Customize › Connectors › Add custom connector with the name and URL (https://qa.bolivarconnect.com/mcp) already filled in. Click Add and then Connect.
2. Bolívar Connect opens. Choose Paste my API key (or Continue without an API key, see Without a key). The page shows in Spanish or English depending on your browser; you can switch it at the top right (ES · EN).
3. Review the summary (company, key, account and permission) and click Allow.
4. In a chat, enable it from + › Connectors and type “get started with Bolívar Connect”.

The key stays at Bolívar Connect; Claude keeps a temporary permission you can revoke (see View and revoke connections). The connector lives in your Claude account, so you see it the same way in claude.ai and in Claude Desktop.

Claude Code

claude mcp add --transport http bolivar-connect https://qa.bolivarconnect.com/mcp

Inside Claude Code, open /mcp, choose bolivar-connect and press Authenticate: the same Bolívar Connect page opens in your browser. Then run the /mcp__bolivar-connect__empezar prompt.

For CI or use without a browser, the header still works:

export BC_API_KEY=<YOUR_TEST_KEY>
claude mcp add --transport http bolivar-connect https://qa.bolivarconnect.com/mcp \
  --header "Authorization: Bearer $BC_API_KEY"

Cursor and VS Code

Add to Cursor

Open in VS Code

Both buttons install the server with the Authorization: Bearer ${env:BC_API_KEY} header: they take the key from the BC_API_KEY variable of the environment you opened the editor from, never from the link. If you open the editor from the Dock and it does not see the variable, open it from a terminal with BC_API_KEY exported or set the header by hand (Cursor tab below).

Before connecting

1. Create a separate key for the agent, with only what it needs. To integrate in testing: payments:read, beneficiaries:read, events:read, treasury:read, quotes:write, beneficiaries:write, payments:write and webhooks:write. Each tool only appears if your key has its scope. Add only what you use:
   • Per-ticket prefunding and source wallets (quote, notify the transfer, register or remove a wallet): prefondeos:write.
   • BDV collections (bc_bdv_*): bdv:read.
   • Gift cards: giftcards:read to look them up and, in testing, giftcards:write to issue them and configure your brand.
2. Store it in an environment variable (BC_API_KEY) and never paste it into a file you push to a repository. Not in the URL either: a key in the query string is rejected.

Connecting your client

Claude Code

export BC_API_KEY=sk_test_...      # the key of your TEST account
claude mcp add --transport http bolivar-connect https://qa.bolivarconnect.com/mcp \
  --header "Authorization: Bearer $BC_API_KEY"

Or in a .mcp.json at the project root:

{
  "mcpServers": {
    "bolivar-connect": {
      "type": "http",
      "url": "https://qa.bolivarconnect.com/mcp",
      "headers": { "Authorization": "Bearer ${BC_API_KEY}" }
    }
  }
}

Then run the server’s empezar prompt: /mcp__bolivar-connect__empezar.

Cursor

In .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "bolivar-connect": {
      "url": "https://qa.bolivarconnect.com/mcp",
      "headers": { "Authorization": "Bearer ${env:BC_API_KEY}" }
    }
  }
}

Cursor resolves ${env:BC_API_KEY} from your environment. Then, in the agent chat, ask it to use the empezar prompt from bolivar-connect.

Other clients

Any MCP client with HTTP transport that lets you add a header works: point it to https://qa.bolivarconnect.com/mcp and send Authorization: Bearer <your sk_test_ key>.

If your client only speaks stdio (for example, Claude Desktop with a configuration file), use a bridge such as mcp-remote:

{
  "mcpServers": {
    "bolivar-connect": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://qa.bolivarconnect.com/mcp",
        "--header", "Authorization:${BC_AUTH}"
      ],
      "env": { "BC_AUTH": "Bearer sk_test_..." }
    }
  }
}

The Bolívar Connect sign-in currently supports Claude (claude.ai, Claude Desktop and Claude Code). For other clients, use the header.

What you can ask it

Once connected, talk to it like someone on your team. For example:

• “How much did I pay out yesterday and how many failed?”
• “Reconcile today”
• “Was the webhook for the last payment delivered?”
• “How much do I have left to pay out?”
• “Show me today’s BDV collections”

Claude answers in the language you write in; tool names and prompts are the same in every language.

If you do not know where to start, use the What can I do prompt (que_puedo_hacer): it summarizes what you can look up and what you can operate in testing with your key, and offers to continue with empezar. Each lookup only appears if your key has its scope.

What the agent can do depending on your key

Key	What it sees
sk_test_ from your test account	Read and write, always with simulated money
sk_test_ from a live account	Read only: it shares your live account’s accounting
sk_live_	Read only, with Connect or via header
No key	Public information only (see Without a key)

Dashboard sessions and embedded-component sessions are not accepted (403).

Without a key

If you choose Continue without an API key, the agent only sees public information: what Bolívar Connect does, the documentation, the environments (test and live) and how to request a key. Never a company’s data, nor rates or quotes.

When you ask it for something about your company, the agent uses bc_conectar_mi_empresa and Claude reopens the Bolívar Connect page so you can paste your key. If it does not open, go to Settings › Connectors › Bolívar Connect, click Disconnect and then Connect, and choose Paste my API key.

Permissions

• With an sk_live_ key, or with a key from a live account, the permission is read-only, even if the key has write scopes.
• With an sk_test_ key from your test account the Read-only checkbox comes unchecked: the agent operates in testing, each operation in two steps. Check it if you only want it to read. A connection you made with the box checked stays read-only; to operate, click Connect again.
• The agent never has more scopes than your key: if you remove one from the key, the agent loses it too.
• The permission lasts one hour and renews itself; the connection expires after 90 days at most, and then you have to click Connect again.
• Platform keys and keys with admin cannot be connected.

View and revoke connections

With a key that has tenant:write:

curl -s $BASE/v1/tenant/conexiones-mcp -H "x-api-key: $KEY"
curl -s -X DELETE $BASE/v1/tenant/conexiones-mcp/<id> -H "x-api-key: $KEY"

Revoking the key also cuts off Claude: a permission never outlives its key. To cut a single connection without touching the key, revoke it here. On a live account, revoking is done with an sk_live_ key: with an sk_test_ key the response is 403 insufficient_scope. On your test account it works with sk_test_.

Tools

• Read: bc_quien_soy, bc_mi_integracion, bc_checklist_integracion, bc_pagos_listar, bc_pago_ver, bc_metricas_dispersion, bc_limites_consumo, bc_bancos, bc_cotizacion_ver, bc_beneficiarios_listar, bc_beneficiario_ver, bc_eventos_listar, bc_evento_ver, bc_posicion, bc_inventario, bc_fondeos, bc_tasa_venta_ver, bc_volumen_fee, bc_cuadrar_dia and bc_cuadres_cuenta_propia.
• Write (test account only): bc_cotizar and bc_webhook_probar; and in two steps (🔒) bc_webhook_configurar, bc_beneficiario_crear, bc_dispersar and bc_tasa_venta_fijar. Where available, bc_prueba_sembrar requires beneficiaries:write and bc_prueba_resolver_pago, payments:write.
• Per-ticket prefunding and source wallets: read, bc_prefondeo_listar, bc_prefondeo_ver, bc_prefondeo_consumos and bc_prefondeo_wallets_listar; in two steps (🔒, test account only, they also require prefondeos:write), bc_prefondeo_cotizar, bc_prefondeo_avisar_envio, bc_prefondeo_wallet_registrar and bc_prefondeo_wallet_baja.
• BDV collections (read, require bdv:read): bc_bdv_conexion, bc_bdv_saldo, bc_bdv_pagos_hoy, bc_bdv_comisiones and bc_bdv_metricas.
• Gift cards: read (require giftcards:read), bc_giftcards_catalogo, bc_giftcards_programa, bc_giftcards_listar and bc_giftcard_ver, without the gift link; in two steps (🔒, test account only, they also require giftcards:write), bc_giftcard_emitir (test only: it cannot be redeemed and is not charged) and bc_giftcards_marca_configurar. The logo is uploaded through the API.

The bc_prueba_* tools

bc_prueba_sembrar, bc_prueba_resolver_pago and bc_prueba_cargar_prefondeo appear on qa.bolivarconnect.com with a key from your test account that has the scope of what they simulate; they do not exist in production. To force an outcome, put PRUEBA:SUBMITTED, PRUEBA:UNKNOWN or PRUEBA:TIMEOUT_AFTER_SUBMIT in the reference of bc_dispersar (see the test environment). Your test account has no wallet: your prefunding already comes loaded (bc_prefondeo_listar). Pay out against it; do not send USDT.

Prompts: que_puedo_hacer, empezar, primera_dispersion, cuadrar_dia, prefondeo and primera_giftcard. Resources: bc://guia/integracion, bc://guia/mcp, bc://guia/modelos-de-fondeo, bc://guia/giftcards, bc://referencia/errores, bc://referencia/estados and bc://openapi. The prompts and resources are served in Spanish.

🔒 operations go in two steps

The agent calls once without confirmacion and receives a summary built by the server (amount, rate, fee, beneficiary, expiry) and a token. Only if you approve that summary does it repeat the call with the same arguments and the token: it is valid for 2 minutes and only once. If the quote expires in the meantime, it has to quote again and ask again. All of them require an idempotencyKey.

Caps and privacy

• Agent caps (per account): Bs 50,000.00 per payout, Bs 500,000.00 and 50 operations per day (payouts and issued gift cards), and 10 writes per minute. On top of that, 60 tool calls per minute per key (429 with Retry-After).
• Masked personal data: national IDs, RIF, accounts and phone numbers come out with their last 4 digits, and people’s names as initials. For the full data, use the REST API.
• Exceptions, only in the summary you approve (only the session that requested it sees it; the confirmation is stored masked):
  • bc_beneficiario_crear: the full details you provided (name, national ID, account and phone), so you can check them before they are saved.
  • bc_dispersar: the bank and the first and last 4 of the account or phone (0102••••6479), and the payment concept (reference, optional, 3 to 30 characters) if you asked for it.
  • bc_webhook_configurar: the new URL exactly as you wrote it, with its query.
  • bc_prefondeo_wallet_registrar and bc_prefondeo_wallet_baja: the full wallet address, so you can compare it character by character.
• URLs come out without a query string: every URL the MCP returns (your webhook’s included) arrives as protocol//host/path, except the new URL in the bc_webhook_configurar summary.
• A gift card link never comes out whole: when issuing in testing, enlace_prueba arrives without the gift key (what comes after #k=). The full link is requested through the API with includeLink=1.
• Your webhook secret never goes through the MCP: there is no tool to rotate it or read it.
• Every call is logged (tool, result and time), without the arguments or the response.

The MCP’s own errors (mcp_confirmacion_vencida, mcp_tope_superado, …) and what to do with each one are in the bc://referencia/errores resource; the API’s, in Errors.