Connect Manager IA: ChatGPT, Claude, Gemini y Copilot con Ágora

Connect Manager IA (el servicio Connect Manager MCP) conecta asistentes de inteligencia artificial como Claude o ChatGPT con los datos de Ágora. Se instala en el servidor donde está Ágora, o en el del ACMS si es un grupo, publica un conector MCP en una dirección HTTPS propia y contesta siempre en solo lectura. Este manual es para el técnico que lo instala, gestiona la licencia y da acceso a las personas del cliente.

Qué hace la integración#

• Instala un servicio de Windows, «Connect Manager MCP», en el servidor de Ágora. Localiza solo la base de datos leyendo el hibernate.cfg.xml de Ágora: no hay que teclear ninguna cadena de conexión.
• Crea en SQL Server una cuenta de solo lectura (agora_mcp_ro) con contraseña aleatoria y comprueba, antes de terminar, que puede leer y que un UPDATE es rechazado. Si la cuenta pudiera escribir, la instalación se aborta.
• Publica el conector en https://mcp-{12 caracteres}.connectmanager.live/mcp con un túnel saliente propio: no necesita Zero Connect ni abrir puertos. La dirección se conserva al reinstalar o actualizar.
• Ofrece al asistente ocho herramientas: info_instalacion (ficha: versión de Ágora, locales, rango de fechas), ventas_resumen (ventas facturadas por local, día, hora, día de la semana, empleado, centro de venta, forma de pago, familia o producto, con fechas como ayer o mes_pasado), listar_informes, ejecutar_informe, listar_valores, buscar_esquema, describir_tabla y consulta_sql (un SELECT libre).
• Publica como informes el catálogo de FOS y los informes personalizados de la carpeta custom-queries de ese Ágora, que se releen cada 30 segundos: para añadir uno basta con dejar el XML en la carpeta.
• Ofrece siete análisis listos, que el asistente presenta como puntos de partida (en Claude, al escribir /): Radiografía del negocio, Cierre del día, Cierre del mes, Comparar locales, Descuentos e invitaciones, Franjas horarias y salas y Auditoría de fraude.
• Da al asistente las reglas de Ágora para no equivocarse con las cifras: filtrar por día de negocio (BusinessDay), que NetAmount lleva el IVA incluido, el borrado lógico, que lo cobrado es lo pagado menos el cambio, o que el fraude se presenta como indicio y nunca como acusación.
• Cada persona entra con su propia cuenta de Connect Manager (OAuth). El servidor lleva la lista de quién se conecta y permite retirarle el acceso.
• Se registra solo en el hub, que lleva la licencia: 30 días de prueba la primera vez que se instala en una máquina y activación por FOS.

Qué no hace#

• No escribe nada en Ágora: no crea tickets, no cambia precios ni borra datos. Lo impiden tres barreras a la vez: filtro de la sentencia, transacción que se deshace siempre y permisos denegados en SQL Server.
• No se actualiza solo: hay que instalar el MSI nuevo encima, y se conservan dirección y token.
• No calcula márgenes si la instalación no tiene escandallos (coste en las líneas): retira esas columnas y lo dice.
• Devuelve como mucho 1.000 filas por consulta durante la prueba y 2.000 con la licencia activa, y corta las consultas de más de 60 segundos. Los totales se piden ya agregados.
• Las cifras del día en curso pueden incluir tickets abiertos: lee sin bloquear el TPV.
• El producto solo trae pasos de alta para Claude y ChatGPT. Gemini, Copilot u otros asistentes funcionarán si admiten conectores MCP remotos con autorización OAuth, pero FOS no los documenta.
• El cliente final no puede autorizar su instalación por su cuenta: necesita una invitación o que FOS lo añada a la lista.

Requisitos#

• Servidor Windows de 64 bits con Ágora instalado y su SQL Server en marcha. En un grupo, el servidor del ACMS: una sola instalación cubre todos los locales. En un local suelto, su servidor de Ágora. El MSI se niega a instalarse si no encuentra el hibernate.cfg.xml.
• Permisos de administrador para el MSI. La cuenta administrativa de Ágora que guarda el hibernate.cfg.xml solo se usa para crear la cuenta de solo lectura; el servicio en marcha no la ve.
• Salida a Internet: HTTPS hacia hub.connectmanager.es (registro, licencia y autorización) y TCP hacia el servidor de túneles. No hay puertos de entrada ni VPN. Sin hub, el servicio aguanta 3 días con el último estado conocido.
• No hace falta instalar ningún runtime: el ejecutable es autocontenido.
• Cada persona necesita un asistente que admita conectores MCP remotos (Claude, o ChatGPT en modo desarrollador), con el plan que lo permita, y una cuenta de Connect Manager. Si no la tiene, se crea con la invitación.
• Quién hace qué: FOS entrega el instalador, controla la licencia (activar, ampliar la prueba, suspender) y puede añadir personas a la lista de la instalación. El técnico (FOS o distribuidor) instala el MSI, invita a las personas y comprueba el alta. El cliente decide quién usa el asistente y con qué cuenta.

Datos que necesitamos#

Configuración paso a paso#

En el servidor de Ágora#

1. Copia ConnectManagerMCP-Setup.msi (te lo facilita FOS) al servidor de Ágora o del ACMS.
2. Instálalo como administrador con doble clic (licencia, progreso y final) o en silencio: msiexec /i ConnectManagerMCP-Setup.msi /qn NOMBRE="Grupo Demo" PUERTO=8787. Admite NOMBRE, PUERTO, BIND, LOGINSQL y HIBERNATECONFIG.
3. El instalador deja todo en C:\ConnectManager\MCP: localiza Ágora, crea y verifica la cuenta de solo lectura, escribe la configuración restringida a Administradores y SYSTEM, genera el subdominio y el token de la instalación, añade exclusiones de Windows Defender para la carpeta y sus dos ejecutables, y registra el servicio con inicio automático retrasado (SQL Server tiene que estar arriba antes) y reinicio ante fallos.
4. Al terminar, deja marcada Abrir la pagina de cuentas y conexion. Se abre http://127.0.0.1:8787/usuarios, que solo funciona desde el propio servidor. Arriba está la dirección pública del conector con el botón Copiar y una franja con el estado de la licencia (En prueba y los días que quedan), el nombre de la instalación, el número de locales y el botón Comprobar licencia. Debajo, las pestañas Conectar y Cuentas.

[!TIP] Si la instalación falla, el motivo queda en C:\ProgramData\Connect Manager MCP\ultimo-error-instalacion.txt, en instalacion.log de esa misma carpeta y en el Visor de eventos (Aplicación, origen «Connect Manager MCP», id 1001).

En Connect Manager (lo hace FOS)#

1. Al arrancar, el servicio se registra solo. La instalación aparece en /admin → ZeroTunnel → Conectores MCP con estado En prueba y los días que quedan, tipo (ACMS o Standalone), locales, TPV, versión, túnel y Último latido. Late cada hora: si pasan más de dos sin latido, sale en rojo.
2. Acciones de cada fila: Datos de conexión, Quién tiene acceso (sesiones abiertas y Revocar los marcados), Usuarios permitidos (personas que pueden autorizar esta instalación, además de FOS y el distribuidor), Marcar como activa, Ampliar prueba (Días a añadir, 15 por defecto), Suspender, Reactivar y Corregir datos fiscales.
3. Antes de que acabe la prueba (el panel la pinta en ámbar 7 días antes), Marcar como activa. El hub avisa al servicio en el momento; si el aviso no llega, se entera en su siguiente consulta. En el servidor, Comprobar licencia lo fuerza.

[!WARNING] El token de Datos de conexión es el del cliente de Zero Connect y da acceso a toda su API. No hace falta para conectar un asistente: no lo envíes al cliente.

Dar acceso a las personas#

Pueden autorizar una instalación los usuarios de FOS con acceso global, los usuarios del distribuidor del cliente y las personas que estén en la lista de esa instalación. Al resto se les invita desde la pestaña Cuentas de la página del servidor:

1. Invitar por correo: escribe el correo y pulsa Invitar. El hub envía un enlace que vale 7 días y un solo uso (como mucho 10 invitaciones por instalación y hora). Al aceptarlo, la persona crea su cuenta de Connect Manager, sin acceso a ningún panel, y queda autorizada para esta instalación y ninguna otra. Si el correo no sale (por ejemplo, porque la instalación aún no se ha registrado en el hub), la página lo dice y la persona queda solo en la lista del servidor: repite la invitación más tarde o pide a FOS que la añada en Usuarios permitidos.
2. Autorizarme a mí → Entrar con mi cuenta de Connect Manager: para que el técnico se autorice desde el propio servidor.
3. La tabla enseña Cuenta, Estado (con acceso o sin conectarse todavía) y Última vez. Retirar acceso corta a esa persona en su siguiente petición; Quitar borra una invitación pendiente. Si sale el bloque Sin acceso, son cuentas que se han conectado y esperan Dar acceso.

Por defecto decide Connect Manager: quien puede autorizar entra y queda anotado en la lista. Si el cliente quiere aprobar además cada cuenta en el servidor, FOS cambia ExigirAutorizacion a auto o siempre en connect-manager-mcp.json.

En el asistente#

La pestaña Conectar lo resume: la dirección de arriba es lo único que hay que pegar en el asistente.

Claude:

1. Abre Configuración y entra en Conectores.
2. Pulsa Añadir conector personalizado.
3. Pega la dirección (acaba en /mcp) y acepta.
4. Se abre el acceso de Connect Manager: entra con tu correo y contraseña.
5. Confirma la instalación a la que das acceso.

ChatGPT:

1. En Configuración › Conectores, abre Configuración avanzada y activa el modo desarrollador.
2. Vuelve a Conectores y pulsa Crear.
3. Pon un nombre, pega la dirección en URL del servidor MCP y elige OAuth como autenticación.
4. Autoriza con tu cuenta y pulsa Permitir acceso.

Otros asistentes (Gemini, Copilot o cualquiera compatible con MCP): añade un servidor o conector MCP remoto con la misma dirección y autenticación OAuth. El asistente descubre solo el servidor de autorización de Connect Manager.

En todos, la pantalla de Connect Manager pregunta «¿Le das acceso a los datos de Ágora de este local?», enseña el nombre y el subdominio de la instalación y lo que podrá hacer el asistente (explorar tablas y columnas, listar y ejecutar los informes del catálogo y hacer consultas SELECT libres, según cubra la licencia) y recuerda «Solo consulta: no puede modificar ni borrar nada en Ágora.». Pulsa Autorizar.

Cómo funciona#

Cuando alguien añade el conector, el asistente llama a la dirección sin credenciales. El servicio contesta que hace falta autorización y le indica el servidor que la da: el hub de Connect Manager. El asistente abre el acceso del hub (OAuth con PKCE), la persona entra con su cuenta y confirma, y el hub comprueba que puede autorizar esa instalación y que la licencia está viva. Si todo está bien, emite un token de una hora firmado para esa instalación y solo esa, con los permisos que cubre la licencia, más un token de renovación que caduca tras 180 días sin uso. Desde ahí, cada pregunta se convierte en llamadas a herramientas. El servicio valida el token en local (firma, emisor, destinatario y permisos), mira la lista de cuentas de la instalación y consulta la base de datos con la cuenta de solo lectura. Todo el tráfico entra por la dirección pública y el túnel lo entrega al puerto local del servicio.

sequenceDiagram
    participant U as Persona
    participant IA as Asistente
    participant MCP as Connect Manager MCP
    participant HUB as Hub Connect Manager
    participant DB as Base de datos de Ágora
    U->>IA: Añade el conector con la dirección del MCP
    IA->>MCP: Primera llamada sin token
    MCP-->>IA: 401 con el servidor de autorización
    IA->>HUB: Pide autorización OAuth con PKCE
    U->>HUB: Entra con su cuenta y confirma la instalación
    HUB-->>IA: Token de una hora y token de renovación
    U->>IA: Pregunta por las ventas de ayer
    IA->>MCP: Llama a una herramienta con el token
    MCP->>MCP: Valida token, permisos y lista de cuentas
    MCP->>DB: SELECT con la cuenta de solo lectura
    DB-->>MCP: Filas
    MCP-->>IA: Tabla con totales y periodo resuelto
    IA-->>U: Respuesta en lenguaje natural

Cada consulta se ejecuta sin bloquear el TPV, con un tope de filas y de 60 segundos, y dentro de una transacción que se deshace siempre. Toda tabla lleva la suma de sus columnas y avisa si está cortada, y las consultas repetidas en el mismo minuto se sirven de memoria.

Informes y análisis disponibles#

El catálogo de FOS viaja con el instalador, en la carpeta informes, y el asistente lo ve agrupado así:

• Ventas: Ventas diarias por usuario, Ventas por centro de venta, Ventas por Local, Familia y Producto y Detalle de líneas vendidas.
• Auditoría: Auditoría de fraude por usuario y Descuentos por usuario y tipo.
• KPIs FOS: IQT - Índice de Calidad del Ticket, RPM - Rentabilidad por minuto, Aprovechamiento de cubierto, Score de venta sugerida por camarero, Mesa Perfecta por camarero, Valor futuro del cliente (CLV 12m), Incidencias en mesa por local, Composición gastronómica por local, Potencial desaprovechado por camarero, IGT - Índice Global del Ticket y Monitor de cocina - tiempos por familia.

A esos se suman los informes personalizados de la carpeta custom-queries de ese Ágora, tal cual. Los análisis listos están en la carpeta guiones, que cada actualización reescribe; los hechos a medida para un cliente van en guiones-cliente, que el instalador no toca, y si se llaman igual que uno de FOS, manda el del cliente.

Licencia y registro#

Al arrancar, el servicio se da de alta en el hub con los datos de la instalación: identificador del equipo, versión, subdominio, versión de Ágora, número de locales y TPV, datos fiscales y licencias de Ágora. El alta es única por máquina: reinstalar en el mismo equipo no reinicia la prueba. Después late cada hora y consulta la licencia cada 6 horas, con un desfase aleatorio para que los servidores no llamen todos a la vez. Cuando FOS activa, amplía o suspende, el hub avisa al servicio para que vuelva a preguntar en ese momento.

sequenceDiagram
    participant MCP as Connect Manager MCP
    participant HUB as Hub Connect Manager
    MCP->>HUB: Alta al arrancar con los datos de la instalación
    HUB-->>MCP: Estado de la licencia, 30 días de prueba la primera vez
    loop Cada hora
        MCP->>HUB: Latido con versión, túnel y uso
        HUB-->>MCP: Estado de la licencia
    end
    loop Cada 6 horas
        MCP->>HUB: Consulta de licencia
    end
    HUB->>MCP: Aviso de cambio al activar o suspender
    MCP->>HUB: Vuelve a consultar la licencia

• En prueba: todo funciona, con 1.000 filas por consulta. Al vencer, el conector deja de servir datos en su siguiente consulta al hub (como mucho, una hora) y el hub no deja autorizar ni renovar, con el mensaje «El periodo de prueba ha terminado. Contacta con FOS para activar la licencia.» (o «…ha vencido…»).
• Activa: sin caducidad. El tope pasa a 2.000 filas, que es el de la configuración del servidor.
• Suspendida o cancelada: deja de servir en su siguiente consulta (como mucho, una hora) y el hub revoca las sesiones abiertas. Al reactivar, el servicio vuelve a funcionar, pero cada persona tiene que autorizar de nuevo el conector.
• Sin hub: sigue con el último estado conocido durante 3 días.

El túnel lo lanza y lo vigila el propio servicio: si se cae, lo reinicia con esperas crecientes, y al parar el servicio se cierra con él. Su estado (publicado, arrancado, caido, error…) se ve en http://127.0.0.1:8787/health desde el servidor. El registro del servicio está en C:\ConnectManager\MCP\logs.

Comprobar que funciona#

1. En http://127.0.0.1:8787/usuarios sale la dirección pública y la franja de licencia dice En prueba o Licencia activa.
2. En http://127.0.0.1:8787/health, desde el servidor, el estado es ok, el túnel publicado y la licencia habilitada.
3. En Conectores MCP, el Último latido está en verde.
4. Añade el conector en Claude o ChatGPT con tu cuenta y lanza Radiografía del negocio o pregunta «¿Cuánto vendimos ayer por local?». La respuesta tiene que citar locales y fechas reales.
5. En la pestaña Cuentas apareces con acceso y con la hora de tu última consulta.
6. Pide al asistente que cambie un precio: tiene que contestar que no puede, porque el servidor es de solo lectura.

Errores frecuentes y solución#

Preguntas frecuentes#

¿Cómo conecto Claude a mi TPV Ágora?#

Instala Connect Manager IA en el servidor de Ágora, copia la dirección que sale en su página de cuentas y añádela en Claude como conector personalizado (Configuración → Conectores → Añadir conector personalizado). Entra con tu cuenta de Connect Manager y autoriza la instalación.

¿Cómo conecto ChatGPT con Ágora?#

Activa el modo desarrollador en Configuración › Conectores › Configuración avanzada, crea un conector con la dirección del MCP en URL del servidor MCP y autenticación OAuth, y autoriza con tu cuenta.

¿Funciona con Gemini o con Copilot?#

El servicio sigue el estándar MCP con autorización OAuth, así que funciona con cualquier asistente que admita conectores MCP remotos de ese tipo. El producto solo trae los pasos de Claude y ChatGPT; para los demás, consulta la documentación del asistente.

¿La IA puede modificar o borrar datos de Ágora?#

No. La cuenta de base de datos tiene la escritura denegada, solo se admiten sentencias SELECT y todo se ejecuta en una transacción que se deshace siempre.

¿Qué pasa cuando terminan los 30 días de prueba?#

Si FOS no ha activado la licencia, el conector deja de responder con datos y no se puede autorizar. Al activarla, vuelve a funcionar sin reinstalar ni volver a autorizar.

¿Se instala en cada local o en el ACMS?#

En un grupo con ACMS, una sola vez en el servidor del ACMS: ve todos los locales. En un local sin ACMS, en su servidor de Ágora.

Referencias#

• Connect Manager IA
• Fichas del catálogo: Claude, ChatGPT, Google Gemini y Microsoft Copilot
• Zero Connect: conectar Ágora sin abrir puertos
• Seguridad de red y direcciones IP en Connect Manager
• Especificación oficial de MCP: modelcontextprotocol.io