Conectar un agente (MCP)

Bolívar Connect tiene un servidor MCP para que un agente (Claude Code, Cursor o cualquier cliente MCP con transporte HTTP) consulte tu operación y, en tu cuenta de pruebas, se integre de punta a punta: de cero a tu primer payment.settled hablando con él.

URL del servidor	https://qa.bolivarconnect.com/mcp
Autenticación	Botón Connect de Claude (inicio de sesión de Bolívar Connect), o Authorization: Bearer <tu key>
Transporte	HTTP, sin estado: sólo POST /mcp (sin SSE)

Para operar, tu key de pruebas

Usa la key sk_test_ de tu cuenta de pruebas: es la única con la que el agente puede escribir, y todo lo que hace es con dinero simulado. Con una key sk_live_ el agente sólo consulta.

Conectar con Claude

Con el botón Connect, Claude abre una página de Bolívar Connect: ahí pegas tu API key (mira Antes de conectar) o sigues sin key. Nunca pegues tu key en el chat: sólo en esa página.

claude.ai y Claude Desktop

Añadir a Claude

1. El botón abre Personalizar › Conectores › Añadir conector personalizado con el nombre y la URL (https://qa.bolivarconnect.com/mcp) ya puestos. Pulsa Añadir y luego Connect.
2. Se abre Bolívar Connect. Elige Pegar mi API key (o Seguir sin API key, ver Sin key). La página sale en español o inglés según tu navegador; arriba a la derecha puedes cambiarla (ES · EN).
3. Revisa el resumen (empresa, key, cuenta y permiso) y pulsa Permitir.
4. En un chat, actívalo desde + › Conectores y escribe «empezar con Bolívar Connect».

La key se queda en Bolívar Connect; Claude guarda un permiso temporal que puedes revocar (ver Ver y revocar conexiones). El conector queda en tu cuenta de Claude, así que lo ves igual en claude.ai y en Claude Desktop.

Claude Code

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

Dentro de Claude Code, abre /mcp, elige bolivar-connect y pulsa Authenticate: se abre la misma página de Bolívar Connect en tu navegador. Luego lanza el prompt /mcp__bolivar-connect__empezar.

Para CI o uso sin navegador, sigue valiendo la cabecera:

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

Cursor y VS Code

Añadir a Cursor

Abrir en VS Code

Los dos botones instalan el servidor con la cabecera Authorization: Bearer ${env:BC_API_KEY}: la key la toman de la variable BC_API_KEY del entorno desde el que abriste el editor, nunca del enlace. Si abres el editor desde el Dock y no ve la variable, ábrelo desde una terminal con BC_API_KEY exportada o pon la cabecera a mano (pestaña Cursor más abajo).

Antes de conectar

1. Crea una key aparte para el agente, con lo justo. Para integrar en pruebas: payments:read, beneficiaries:read, events:read, treasury:read, quotes:write, beneficiaries:write, payments:write y webhooks:write. Cada herramienta aparece sólo si tu key tiene su scope. Añade sólo lo que uses:
   • Prefondeo por ticket y wallets de origen (cotizar, avisar el envío, registrar o dar de baja una wallet): prefondeos:write.
   • Cobros BDV (bc_bdv_*): bdv:read.
   • Gift cards: giftcards:read para consultarlas y, en pruebas, giftcards:write para emitirlas y configurar tu marca.
2. Guárdala en una variable de entorno (BC_API_KEY) y nunca la pegues en un archivo que subas a un repositorio. Tampoco en la URL: una key en la query se rechaza.

Conectar tu cliente

Claude Code

export BC_API_KEY=sk_test_...      # la key de tu cuenta de PRUEBAS
claude mcp add --transport http bolivar-connect https://qa.bolivarconnect.com/mcp \
  --header "Authorization: Bearer $BC_API_KEY"

O en un .mcp.json en la raíz del proyecto:

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

Luego lanza el prompt get_started del servidor: /mcp__bolivar-connect__empezar.

Cursor

En .cursor/mcp.json (del proyecto) o ~/.cursor/mcp.json (global):

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

Cursor resuelve ${env:BC_API_KEY} desde tu entorno. Después, en el chat del agente, pídele que use el prompt get_started de bolivar-connect.

Otros clientes

Cualquier cliente MCP con transporte HTTP que permita añadir una cabecera sirve: apunta a https://qa.bolivarconnect.com/mcp y manda Authorization: Bearer <tu key sk_test_>.

Si tu cliente sólo habla stdio (por ejemplo, Claude Desktop con un archivo de configuración), usa un puente como 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_..." }
    }
  }
}

El inicio de sesión de Bolívar Connect admite por ahora a Claude (claude.ai, Claude Desktop y Claude Code). Para otros clientes, usa la cabecera.

Qué puedes pedirle

Una vez conectado, háblale como a alguien de tu equipo. Por ejemplo:

• «¿Cuánto dispersé ayer y cuántas fallaron?»
• «Cuadra el día de hoy»
• «¿Se entregó el webhook del último pago?»
• «¿Cuánto me queda para dispersar?»
• «Muéstrame los cobros BDV de hoy»

Si no sabes por dónde empezar, usa el prompt Qué puedo hacer (what_can_i_do): te resume qué puedes consultar y qué puedes operar en pruebas con tu key, y te ofrece seguir con get_started. Cada consulta aparece sólo si tu key tiene su scope.

Qué puede hacer el agente según tu key

Key	Qué ve
sk_test_ de tu cuenta de pruebas	Lectura y escritura, siempre con dinero simulado
sk_test_ de una cuenta real	Sólo lectura: comparte la contabilidad de tu cuenta real
sk_live_	Sólo lectura, con Connect o por cabecera
Sin key	Sólo información pública (ver Sin key)

Las sesiones del panel o de un componente embebido no entran (403).

Sin key

Si eliges Seguir sin API key, el agente sólo ve información pública: qué hace Bolívar Connect, la documentación, los entornos (pruebas y real) y cómo pedir una key. Nunca datos de una empresa, ni tasas ni cotizaciones.

Cuando le pidas algo de tu empresa, el agente usa bc_connect_my_company y Claude vuelve a abrir la página de Bolívar Connect para que pegues tu key. Si no se abre, ve a Ajustes › Conectores › Bolívar Connect, pulsa Desconectar y luego Connect, y elige Pegar mi API key.

Permisos

• Con una key sk_live_, o con una key de una cuenta real, el permiso es sólo de lectura, aunque la key tenga scopes de escritura.
• Con una sk_test_ de tu cuenta de pruebas la casilla Solo lectura viene desmarcada: el agente opera en pruebas, cada operación en dos pasos. Márcala si sólo quieres que consulte. Una conexión que hiciste con la casilla marcada sigue de sólo lectura; para operar, vuelve a pulsar Connect.
• El agente nunca tiene más scopes que tu key: si le quitas uno a la key, el agente también lo pierde.
• El permiso dura una hora y se renueva solo; la conexión vence a los 90 días como máximo y entonces hay que pulsar Connect otra vez.
• Las keys de plataforma y las que tienen admin no se pueden conectar.

Ver y revocar conexiones

Con una key con tenant:write:

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

Revocar la key también corta a Claude: un permiso nunca sobrevive a su key. Para cortar una sola conexión sin tocar la key, revócala aquí. En una cuenta real, revocar se hace con una key sk_live_: con una sk_test_ responde 403 insufficient_scope. En tu cuenta de pruebas funciona con sk_test_.

Herramientas

Los nombres, los argumentos y los campos de las herramientas están en inglés, como la API (el MCP la llama siempre con BC-Version: 2026-11-03). Si tu agente usaba los nombres viejos (bc_dispersar, bc_cotizar…), la tabla está en Migrar a los nombres en inglés.

• Documentación (cualquier key, y también sin key): bc_docs lista las páginas de esta documentación y devuelve una entera por slug, en español o en inglés; por ejemplo, guias/migrar-a-ingles. Sale de los mismos archivos que esta web, en la versión desplegada.
• Lectura: bc_whoami, bc_my_integration, bc_integration_checklist, bc_list_payments, bc_get_payment, bc_payment_metrics, bc_limits_usage, bc_list_banks, bc_get_quote, bc_list_beneficiaries, bc_get_beneficiary, bc_list_events, bc_get_event, bc_get_position, bc_get_inventory, bc_list_fundings, bc_get_sell_rate, bc_volume_and_fee, bc_reconcile_day y bc_list_daily_closes.
• Escritura (sólo cuenta de pruebas): bc_create_quote y bc_test_webhook; y en dos pasos (🔒) bc_set_webhook, bc_create_beneficiary, bc_create_payout y bc_set_sell_rate. Donde están disponibles, bc_sandbox_seed pide beneficiaries:write y bc_sandbox_resolve_payment, payments:write.
• Prefondeo por ticket y wallets de origen: de lectura, bc_list_prefunds, bc_get_prefund, bc_list_prefund_consumptions y bc_list_source_wallets; en dos pasos (🔒, sólo cuenta de pruebas, piden además prefondeos:write), bc_prefund_quote, bc_prefund_mark_sent, bc_register_source_wallet y bc_deactivate_source_wallet.
• Cobros BDV (lectura, piden bdv:read): bc_bdv_connection, bc_bdv_balance, bc_bdv_incoming_payments_today, bc_bdv_fees y bc_bdv_metrics.
• Gift cards: de lectura (piden giftcards:read), bc_giftcards_catalog, bc_giftcards_program, bc_list_giftcards y bc_get_giftcard, sin el enlace del regalo; en dos pasos (🔒, sólo cuenta de pruebas, piden además giftcards:write), bc_issue_giftcard (de prueba: no se canjea ni se cobra) y bc_set_giftcards_brand. El logo se sube por la API.

Las herramientas bc_sandbox_*

bc_sandbox_seed, bc_sandbox_resolve_payment y bc_sandbox_credit_prefund aparecen en qa.bolivarconnect.com con una key de tu cuenta de pruebas que tenga el scope de lo que simulan; en producción no existen. Para forzar un desenlace, pon TEST:SUBMITTED, TEST:UNKNOWN o TEST:TIMEOUT_AFTER_SUBMIT en el reference de bc_create_payout (ver el entorno de pruebas). En tu cuenta de pruebas no hay wallet: tu prefondeo ya viene cargado (bc_list_prefunds). Dispersa contra él; no mandes USDT.

Prompts: what_can_i_do, get_started, first_payout, reconcile_day, prefund y first_giftcard. Recursos: bc://guide/integration, bc://guide/mcp, bc://guide/funding-models, bc://guide/giftcards, bc://docs/es/guias/migrar-a-ingles, bc://docs/en/guias/migrar-a-ingles, bc://reference/errors, bc://reference/statuses y bc://openapi.

Las operaciones 🔒 van en dos pasos

El agente llama una vez sin confirmation y recibe un resumen armado por el servidor (monto, tasa, comisión, beneficiario, vencimiento) y un token. Sólo si tú apruebas ese resumen, repite la llamada con los mismos argumentos y el token: vale 2 minutos y una sola vez. Si la cotización vence en medio, hay que volver a cotizar y a preguntar. Todas llevan idempotencyKey obligatoria.

Topes y privacidad

• Topes del agente (por cuenta): 50.000,00 Bs por dispersión, 500.000,00 Bs y 50 operaciones por día (dispersiones y gift cards emitidas), y 10 escrituras por minuto. Además, 60 llamadas a herramientas por minuto por key (429 con Retry-After).
• Datos personales enmascarados: cédulas, RIF, cuentas y teléfonos salen con sus últimos 4 dígitos y los nombres de personas como iniciales. Para el dato completo, usa la API REST.
• Excepciones, sólo en el resumen que apruebas (lo ve únicamente la sesión que lo pidió; la confirmación se guarda enmascarada):
  • bc_create_beneficiary: los datos completos que tú diste (nombre, cédula, cuenta y teléfono), para que los compruebes antes de guardarlos.
  • bc_create_payout: el banco y los primeros y últimos 4 de la cuenta o el teléfono (0102••••6479), y el concepto (reference, opcional, de 3 a 30 caracteres) si lo pediste.
  • bc_set_webhook: la URL nueva tal como la escribiste, con su query.
  • bc_register_source_wallet y bc_deactivate_source_wallet: la dirección completa de la wallet, para compararla carácter por carácter.
• Las URLs salen sin query: toda URL que devuelve el MCP (la de tu webhook incluida) llega como protocolo//host/ruta, salvo la URL nueva en el resumen de bc_set_webhook.
• El enlace de una gift card nunca sale entero: al emitir en pruebas, testLink llega sin la clave del regalo (lo que va después de #k=). El enlace completo se pide por la API con includeLink=1.
• El secreto de tu webhook nunca pasa por el MCP: no hay herramienta para rotarlo ni para leerlo.
• Cada llamada queda registrada (herramienta, resultado y tiempo), sin los argumentos ni la respuesta.

Los errores propios del MCP (mcp_confirmation_expired, mcp_cap_exceeded, …) y qué hacer con cada uno están en el recurso bc://reference/errors; los de la API, en Errores.