Skip to main content

¿Qué es el servidor MCP de OnePay?

El Model Context Protocol (MCP) es un estándar abierto que permite conectar asistentes de IA a herramientas externas. OnePay expone un servidor MCP en https://mcp.onepay.la que les da acceso a tu información de pagos en tiempo real y, según tus permisos, les permite ejecutar las mismas acciones que haces en el panel de OnePay. Una vez conectado, puedes pedirle a Claude cosas como:
  • “¿Cuál es mi saldo disponible?”
  • “Muéstrame los cobros pendientes de esta semana”
  • “¿Qué pasó con el pago INV-2026-001?”
  • “Lista los últimos 5 desembolsos fallidos”
  • “Reenvía el cobro de Juan Pérez”

Prerrequisitos

  • Cuenta de OnePay con un rol que pueda ver Desarrolladores → API Keys en el panel
  • Claude Desktop, Cursor u otro cliente MCP compatible que permita enviar un header Authorization
  • Para Claude Desktop: Node.js instalado (se usa npx)

Elige tu credencial

El servidor acepta dos tipos de credencial en el mismo endpoint, enviadas como Authorization: Bearer <credencial>: Para conectar un asistente como Claude Desktop, usa un token de agente. Usa una llave sk_ solo si quieres que el asistente únicamente consulte información. El prefijo define el entorno: agent_test_ / sk_test_ trabajan con datos de prueba y agent_live_ / sk_live_ con producción. Las llaves públicas (pk_) y las llaves de solo lectura del panel (rk_) se rechazan.

Crear un token de agente

1. Entra al panel de OnePay y abre Desarrolladores → API Keys. 2. En la sección Tokens de agente (MCP), pulsa Crear token y ponle un nombre que te diga dónde lo usas (por ejemplo, Claude Desktop en mi portátil). 3. Copia el token en ese momento. Se muestra una sola vez y no se puede volver a ver.
El token se crea en el entorno que tengas activo en el panel. Para obtener un agent_test_ activa antes el modo de pruebas; si no, recibirás un agent_live_. Si tu empresa aún no está activa en producción, el panel trabaja siempre en modo de pruebas y solo podrás crear tokens agent_test_.Empieza con un agent_test_: las acciones de escritura del asistente son reales y, en producción, mueven dinero y notifican a tus clientes.

Conectar Claude Desktop

Claude Desktop lee los servidores MCP de un archivo de configuración y arranca cada uno como un proceso local. Para conectarlo a un servidor remoto como el de OnePay se usa el puente mcp-remote, que Claude Desktop ejecuta con npx. 1. Abre el archivo de configuración. En Claude Desktop: Settings → Developer → Edit Config. O directamente: 2. Agrega el servidor OnePay dentro de mcpServers y reemplaza agent_live_TU_TOKEN por tu token:
El valor Bearer … va en env y no directamente en args porque Claude Desktop puede romper los argumentos que contienen espacios. 3. Cierra Claude Desktop por completo (Cmd+Q en macOS; en Windows, desde la bandeja del sistema) y vuelve a abrirlo. Cerrar solo la ventana no recarga la configuración. 4. Abre un chat nuevo y pregunta “¿Cuál es mi saldo disponible?”. Claude te pedirá permiso para usar la herramienta de OnePay; apruébala y verás tu saldo. En Settings → Developer el servidor onepay debe aparecer como activo.
Si usas nvm, fnm o asdf, Claude Desktop no hereda el PATH de tu terminal y puede no encontrar npx. En ese caso pon la ruta absoluta en command: obtenla con which npx (por ejemplo, /Users/tu-usuario/.nvm/versions/node/v24.14.1/bin/npx).
Claude pide aprobación antes de ejecutar cada herramienta. En las que escriben (crear, reenviar, cancelar, aprobar), revisa los argumentos antes de aceptar.

Conectar Cursor

Agrega esto a ~/.cursor/mcp.json, con tu propio token en vez del marcador:

Herramientas disponibles

El servidor expone más de 200 herramientas, las mismas capacidades del panel. Cuáles ves depende de tu usuario y de tu rol. Algunas áreas: Las herramientas trabajan siempre sobre tu empresa activa, y las acciones de escritura aplican los mismos permisos que el panel. El prefijo del token fija el entorno: un token agent_test_ solo ve y modifica datos de prueba. Con una llave sk_, las herramientas que escriben o que dependen de un usuario responden con un error.

Ejemplos de conversación

Una vez conectado, puedes preguntar en lenguaje natural: Ver saldo:
“¿Cuánto tengo disponible en mi billetera de OnePay?”
Revisar cobros:
“Lista los 10 cobros más recientes que están pendientes”
“¿Hay algún cobro fallido esta semana?”
Investigar un pago:
“Busca el cobro con referencia FACT-2026-0412”
“¿Qué pasó con el cobro del cliente Juan García de ayer?”
Revisar desembolsos:
“Muéstrame los desembolsos que están procesando hoy”
“¿Cuántos desembolsos fallaron esta semana?”
Ejecutar una acción (solo con token de agente):
“Reenvía el cobro FACT-2026-0412 a su cliente”

Verificar la conexión

Puedes probar directamente desde terminal, con tu propio token:
Si la conexión es exitosa, verás los nombres de las primeras herramientas: la respuesta viene paginada y no trae las más de 200 de una vez.

Solución de problemas


Seguridad

  • Un token de agente actúa en tu nombre: las acciones de escritura aplican tus permisos del panel. Trátalo como una contraseña y no lo compartas ni lo subas a un repositorio.
  • Las herramientas operan sobre la empresa activa de tu usuario; el prefijo del token fija el entorno (pruebas o producción).
  • Las llaves sk_ son de solo lectura en el MCP: no pueden crear, modificar ni eliminar datos.
  • Los tokens de agente no vencen solos. Si pierdes un equipo o ya no usas un token, revócalo desde Desarrolladores → API Keys → Tokens de agente (MCP): el asistente pierde el acceso de inmediato.
  • Crea un token por cada asistente o equipo, con un nombre descriptivo, para saber cuál revocar.