¿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 enhttps://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 comoAuthorization: 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.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 puentemcp-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:
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.
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: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.