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 empezar 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 empezar 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 (que_puedo_hacer): te resume qué puedes consultar y qué puedes operar en pruebas con tu key, y te ofrece seguir con empezar. 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_conectar_mi_empresa 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/conexiones-mcp -H "x-api-key: $KEY"
curl -s -X DELETE $BASE/v1/tenant/conexiones-mcp/<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

• Lectura: 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 y bc_cuadres_cuenta_propia.
• Escritura (sólo cuenta de pruebas): bc_cotizar y bc_webhook_probar; y en dos pasos (🔒) bc_webhook_configurar, bc_beneficiario_crear, bc_dispersar y bc_tasa_venta_fijar. Donde están disponibles, bc_prueba_sembrar pide beneficiaries:write y bc_prueba_resolver_pago, payments:write.
• Prefondeo por ticket y wallets de origen: de lectura, bc_prefondeo_listar, bc_prefondeo_ver, bc_prefondeo_consumos y bc_prefondeo_wallets_listar; en dos pasos (🔒, sólo cuenta de pruebas, piden además prefondeos:write), bc_prefondeo_cotizar, bc_prefondeo_avisar_envio, bc_prefondeo_wallet_registrar y bc_prefondeo_wallet_baja.
• Cobros BDV (lectura, piden bdv:read): bc_bdv_conexion, bc_bdv_saldo, bc_bdv_pagos_hoy, bc_bdv_comisiones y bc_bdv_metricas.
• Gift cards: de lectura (piden giftcards:read), bc_giftcards_catalogo, bc_giftcards_programa, bc_giftcards_listar y bc_giftcard_ver, sin el enlace del regalo; en dos pasos (🔒, sólo cuenta de pruebas, piden además giftcards:write), bc_giftcard_emitir (de prueba: no se canjea ni se cobra) y bc_giftcards_marca_configurar. El logo se sube por la API.

Las herramientas bc_prueba_*

bc_prueba_sembrar, bc_prueba_resolver_pago y bc_prueba_cargar_prefondeo 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 PRUEBA:SUBMITTED, PRUEBA:UNKNOWN o PRUEBA:TIMEOUT_AFTER_SUBMIT en el reference de bc_dispersar (ver el entorno de pruebas). En tu cuenta de pruebas no hay wallet: tu prefondeo ya viene cargado (bc_prefondeo_listar). Dispersa contra él; no mandes USDT.

Prompts: que_puedo_hacer, empezar, primera_dispersion, cuadrar_dia, prefondeo y primera_giftcard. Recursos: bc://guia/integracion, bc://guia/mcp, bc://guia/modelos-de-fondeo, bc://guia/giftcards, bc://referencia/errores, bc://referencia/estados y bc://openapi.

Las operaciones 🔒 van en dos pasos

El agente llama una vez sin confirmacion 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_beneficiario_crear: los datos completos que tú diste (nombre, cédula, cuenta y teléfono), para que los compruebes antes de guardarlos.
  • bc_dispersar: 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_webhook_configurar: la URL nueva tal como la escribiste, con su query.
  • bc_prefondeo_wallet_registrar y bc_prefondeo_wallet_baja: 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_webhook_configurar.
• El enlace de una gift card nunca sale entero: al emitir en pruebas, enlace_prueba 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_confirmacion_vencida, mcp_tope_superado, …) y qué hacer con cada uno están en el recurso bc://referencia/errores; los de la API, en Errores.