Servidor MCP para Ágora (Connect Manager IA): instalación

Connect Manager IA (el servicio Connect Manager MCP) conecta asistentes de IA como Claude o ChatGPT con los datos de Ágora. Se instala en el servidor de Ágora o del ACMS, publica un conector MCP en una dirección HTTPS propia y solo lee. Este manual es para el técnico que lo instala y da los accesos.

Los pasos de cada asistente para el usuario final están en sus guías: Claude, ChatGPT, Microsoft Copilot, Gemini y cualquier otro asistente MCP. Este manual se revisó el 08-10-2026 con la documentación oficial de cada asistente de esa fecha.

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, todas marcadas como de solo lectura: 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 como plantillas de preguntas MCP: 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. Claude los presenta al escribir /; en los asistentes que no muestran plantillas se pega su texto (los siete análisis).
• 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.
• No todos los asistentes admiten conectores propios. A 08-10-2026, la app gratuita de Microsoft Copilot no los admite (hace falta Microsoft 365 Copilot o Copilot Studio, configurados por un administrador) y la app de Gemini solo los admite en Estados Unidos y en inglés (en España, Gemini Enterprise, configurado por un administrador).
• 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 una cuenta de Connect Manager (si no la tiene, se crea con la invitación) y un asistente que admita conectores MCP remotos con OAuth:
  • Claude: todos los planes; el gratuito admite un solo conector personalizado y en Team o Enterprise lo añade el propietario.
  • ChatGPT: en la web, con un plan que permita servidores MCP propios; en Business, Enterprise y Edu lo habilita el administrador del espacio de trabajo.
  • Microsoft 365 Copilot (conector federado) o Copilot Studio, y Gemini Enterprise: los configura el administrador del cliente con un cliente OAuth que prepara FOS.
  • Otros (Perplexity, Le Chat de Mistral, Cursor, VS Code, Claude Code): si cumplen los requisitos de autorización de abajo.
• Quién hace qué: FOS entrega el instalador, controla la licencia (activar, ampliar la prueba, suspender), puede añadir personas a la lista de la instalación y prepara los clientes OAuth de Copilot y Gemini. 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 el correo «Te han dado acceso a los datos de…» con un enlace que vale 7 días y un solo uso (como mucho 10 invitaciones por instalación y hora) y la dirección del conector. Al aceptarlo (Crear mi cuenta o Confirmar el acceso), 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.

El correo de invitación habla de «pegar la dirección en Claude», pero la dirección es la misma para cualquier asistente. 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. El acceso de FOS y del distribuidor no sale de esa lista, así que no se puede retirar desde la página de cuentas.

En el asistente#

La pestaña Conectar lo resume: la dirección de arriba es lo único que hay que pegar en el asistente. La página del servidor todavía enseña la ruta antigua de ChatGPT; la vigente es la de abajo.

Claude (todos los planes; guía completa en Conectar Claude a Ágora paso a paso):

1. Entra en Personalizar › Conectores (Customize › Connectors) y pulsa Añadir conector personalizado. En Team y Enterprise lo añade el propietario en Configuración de la organización › Conectores › Añadir › Personalizado, y cada persona pulsa Conectar.
2. Pega la dirección (acaba en /mcp).
3. Si el diálogo pregunta por el cliente OAuth, elige Registrar automáticamente (Register automatically): el hub admite el registro dinámico pero no anuncia los documentos de metadatos de cliente que usa la identidad publicada de Claude. Si solo enseña identificador y secreto, déjalos vacíos.
4. Se abre el acceso de Connect Manager: entra con tu correo y contraseña y autoriza la instalación.

ChatGPT (solo en la web; guía completa en ChatGPT conectado a Ágora):

1. En chatgpt.com, abre Plugins, pulsa + y elige Add custom MCP server.
2. Pon un nombre, pega la dirección en Server URL (no uses Tunnel) y elige OAuth.
3. Acepta el aviso con I understand and want to continue y pulsa Create as a plugin.
4. Autoriza con tu cuenta de Connect Manager. En cada conversación, se invoca escribiendo @ y eligiendo el plugin.

Si la cuenta aún enseña la versión anterior, la ruta es Configuración › Apps (o Conectores) › Configuración avanzada › modo desarrollador y, después, Crear con la dirección en URL del servidor MCP y autenticación OAuth.

Microsoft Copilot y Gemini: no los añade cada persona. En Microsoft 365 Copilot, un administrador global o de IA crea un conector federado (Portal para desarrolladores de Teams y Centro de administración de Microsoft 365); en Copilot Studio, se añade como herramienta MCP de un agente; en Gemini Enterprise, un administrador con el rol Discovery Engine Editor crea un almacén Custom MCP Server. Detalle en Microsoft Copilot y Gemini.

Otros asistentes (Perplexity, Le Chat, Cursor, VS Code, Claude Code): añade un conector o servidor MCP remoto con la misma dirección y autenticación OAuth (guía).

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.

Datos de autorización para administradores#

Para configurar Copilot, Gemini u otro cliente a mano, o para diagnosticar un fallo de autorización:

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 y resource
    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: anota cada herramienta usada, su tiempo, sus filas y el error si lo hubo, pero no los datos devueltos.

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 tu asistente con tu cuenta (en Claude es lo más rápido) 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#

¿Qué dirección se pega en el asistente?#

La que sale arriba en http://127.0.0.1:8787/usuarios, con el botón Copiar: https://mcp-{12 caracteres}.connectmanager.live/mcp. Es la misma para todas las personas y todos los asistentes de esa instalación, y también viaja en el correo de invitación.

¿Dónde están los pasos de cada asistente?#

En sus guías del portal de IA: Claude, ChatGPT, Microsoft Copilot, Gemini y otros asistentes MCP. Este manual solo resume el alta.

¿Funciona con Gemini o con Copilot?#

Con sus versiones de empresa y configurado por un administrador: Microsoft 365 Copilot o Copilot Studio, y Gemini Enterprise. A 08-10-2026, la app gratuita de Copilot no admite conectores propios y la app de Gemini solo los admite en Estados Unidos y en inglés. La configuración se valida en el entorno del cliente antes de darla por buena.

¿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
• Uso: Cómo preguntar a la IA por los datos de Ágora, Los 7 análisis listos y Usar la IA con los datos del restaurante sin riesgos
• Zero Connect: conectar Ágora sin abrir puertos
• Seguridad de red y direcciones IP en Connect Manager
• Especificación oficial de MCP: modelcontextprotocol.io

Fuentes#

• Anthropic, «Get started with custom connectors using remote MCP», support.claude.com, y «Authentication for connectors», claude.com/docs, consultados el 08-10-2026.
• OpenAI, «Add custom MCP server», developers.openai.com, consultado el 08-10-2026.
• Microsoft Learn, «Set up custom federated connectors», learn.microsoft.com (actualizada el 25-09-2026), y «Connect your agent to an existing MCP server», learn.microsoft.com (actualizada el 19-08-2026), consultadas el 08-10-2026.
• Google, ayuda de Gemini (apps personalizadas), support.google.com, y «Set up a custom MCP server» de Gemini Enterprise, docs.cloud.google.com (actualizada el 05-10-2026), consultadas el 08-10-2026.
• Connect Manager MCP y hub de Connect Manager: instalador, herramientas, análisis, informes, autorización OAuth e invitaciones, versión del 08-10-2026.