Toda comisión directiva tiene a alguien así. La persona que arregló la laptop del marcador, escribió la macro que ordena la planilla de inscripciones y ahora hace la pregunta incisiva al final de la reunión: "a ver, si la plataforma tiene una API, ¿para qué necesitamos esto de la conexión con IA?"
Es una pregunta justa y merece una respuesta de verdad, no un folleto. Una plataforma para clubes puede ofrecer tres tipos de conexión realmente distintos. No son versiones que compiten de la misma idea: resuelven tres problemas diferentes, y elegir la equivocada es la forma en que un voluntario pierde un fin de semana construyendo algo que la plataforma ya estaba dispuesta a darle. Esta guía presenta las tres, lado a lado, en un lenguaje que una comisión directiva puede seguir, y es honesta sobre los casos en que una conexión con IA es directamente la herramienta equivocada.
Pedir, recibir y preguntar
Si quitas la jerga, las tres formas se reducen a quién inicia la conversación.
- Una clave de API REST permite que tu código saque datos cuando tu código decida pedirlos. Tú escribes el código y hace exactamente lo que escribiste.
- Un webhook permite que la plataforma envíe un mensaje a tu sistema en el momento en que algo ocurre: se asocia un socio, se paga un pedido, alguien registra su entrada.
- Un token MCP permite que un asistente de IA pida cosas de un menú que publica la plataforma, y cada solicitud se vuelve a verificar contra los permisos vigentes de la persona dueña del token. No escribes nada de código.
Pedir, recibir y preguntar. Esa es toda la clasificación, y una vez que tienes esos tres verbos en la cabeza, el resto de esta guía es detalle.
Una nota práctica antes del detalle: en ClubHelix las tres viven en la misma pantalla del panel de administración (Sistema → API y webhooks), y esa página solo la ven las personas con el rol de administrador de la organización. Sin embargo, no comparten plan: la conexión con el asistente está disponible en todos los planes, mientras que la clave REST y los webhooks requieren Pro. Un moderador no puede llegar a ella, y tampoco alguien que tenga un permiso especial. Si estás evaluando estas opciones, es una sola pantalla para mirar, no tres.
Forma uno: una clave de API de solo lectura
Una clave de API es la más antigua y la menos misteriosa de las tres. Creas una clave en el panel, se te muestra una sola vez y la envías como encabezado Authorization: Bearer chk_… en solicitudes HTTPS comunes a /api/v1/…. En ClubHelix esas claves son de solo lectura, y los recursos a los que llegan son socios, tipos de socio, eventos, pedidos y registros de entrada.
Ese "solo lectura" importa más de lo que parece. Una clave que solo puede leer es una clave a la que no se le puede hacer borrar nada, a la que no se puede engañar para que cambie un precio y que no se convierte en un incidente si termina pegada en la ventana de chat equivocada. Igual puede filtrar datos, y por eso se puede revocar, pero el alcance de un error está limitado por diseño y no por buenas intenciones.
Aquello en lo que una clave de API es realmente buena es todo lo que quieres que sea determinista y repetible. Una planilla que actualiza los números de socios para el informe de tesorería. Una pantalla en la sede social con los partidos de esta noche. Un tablero que le gusta al presidente porque son los mismos once números en los mismos once recuadros cada semana. El código hace lo que escribiste, para siempre, sin opiniones.
La contrapartida es que alguien tiene que escribirlo y alguien tiene que mantenerlo funcionando. Una clave además funciona solo a pedido: no sabe nada hasta que tu código pregunta, así que si quieres enterarte de un pago segundos después de que ocurra, una clave implica consultar el mismo endpoint una y otra vez y descartar la respuesta cuando nada cambió. Ese es el problema que la siguiente forma existe para resolver.
Forma dos: webhooks
Un webhook invierte la relación. En lugar de que tu código le pregunte a la plataforma "¿hay algo nuevo?", la plataforma envía un pequeño mensaje JSON a una URL que tú indicas, cuando la cosa realmente ocurre.
En ClubHelix agregas un endpoint (tiene que ser una URL https://) y eliges qué eventos debe recibir. Si dejas el filtro vacío, se suscribe a todo. Los eventos disponibles hoy son:
member.createdymember.updatedmembership_order.paiddonation.paidshop_order.paidfacility_booking.paidraffle_order.paidprogram_enrolment.paidprogram_pass.paidcheckin.created
Cada entrega es un cuerpo JSON que lleva el nombre del evento, la organización a la que pertenece, los datos de ese evento y una marca de tiempo. Va firmada con el secreto propio de tu endpoint (un resumen HMAC-SHA256 de los bytes exactos que enviamos, en un encabezado X-ClubHelix-Signature), para que tu receptor pueda verificar que el mensaje realmente vino de nosotros antes de actuar. Las entregas fallidas se reintentan hasta cinco veces. La pantalla del panel tiene un botón Enviar evento de prueba y un registro de las entregas recientes con sus códigos de respuesta, para que veas si tu lado respondió o se cayó.
Los webhooks son la respuesta correcta siempre que la frase que tienes en la cabeza empiece con "avísale a mi sistema cuando…". Avísale a la planilla de turnos cuando se inscribe un entrenador. Avísale a la herramienta contable cuando se paga un pedido. Enciende una pantalla en el hall cuando alguien registra su entrada. También son la respuesta honesta para todo lo que tiene que funcionar sin supervisión, de noche, todas las noches, durante las próximas tres temporadas: una máquina que reacciona a eventos es exactamente el tipo de cosa que debería ser una máquina.
La contrapartida aquí es que necesitas algo que esté siempre escuchando y siempre accesible desde internet, y que tiene que verificar esa firma y tolerar que el mismo evento llegue dos veces. Las entregas se ponen en cola y no son instantáneas, así que piensa en "a los pocos minutos del evento", no en "el mismo milisegundo". Para la mayoría de los usos de un club eso no se distingue de lo instantáneo; para un molinete de acceso, sí.
Puedes leer más sobre qué se conecta con qué en la página de integraciones.
Forma tres: un token MCP
La tercera forma es la nueva, y vale la pena entenderla bien en lugar de por analogía.
MCP significa Model Context Protocol. Es un estándar abierto que permite que un asistente de IA use un software, no haciendo clic en una pantalla como si fuera una persona ni recibiendo la contraseña de alguien, sino leyendo un menú de herramientas que publica el propio software. El asistente ve el menú, elige la herramienta que corresponde a lo que le pidieron y envía la solicitud. La plataforma decide entonces, en el momento, si esa solicitud está permitida.
Así que la división del trabajo es completamente distinta a la de una clave de API. Con una clave, decides de antemano exactamente qué llamadas hacer y en qué orden, y lo dejas escrito como código. Con MCP, dices lo que quieres en una frase ("¿qué socios no renovaron y cuánto vendimos en la tienda el mes pasado?") y el asistente averigua qué herramientas llamar. Tú no escribes nada.
En ClubHelix la conexión es un token con el prefijo chmx_, creado en la misma pantalla del panel, con un nombre, un vencimiento (el predeterminado es de 90 días) y dos casillas que empiezan desactivadas: Permitir cambios y Permitir publicar. Las dos desactivadas significan un asistente de solo lectura. Permitir cambios le deja crear y editar contenido sin decidir qué se publica: puede escribir un borrador y puede corregir la redacción de una noticia o de un evento que ya está publicado, pero no puede poner algo nuevo en el sitio ni quitar algo de él. Permitir publicar, que se suma a los cambios, es lo que le permite hacer algo visible al público. También hay un panel opcional para limitar el token todavía más, permiso por permiso, cuya propia redacción en pantalla es la descripción más clara: si no marcas nada, el token puede hacer todo lo que tú puedes hacer; si marcas algunos, solo puede hacer esas cosas.
Si quieres el paso a paso completo (crear el token, pegar el comando de conexión, comprobar que funcionó), está en nuestra guía para conectar un asistente de IA a los datos de tu club. Esta guía trata sobre si quieres uno, no sobre cómo crearlo.
Por qué el menú fijo es toda la historia de la seguridad
Esta es la parte que suele cerrar la discusión con el miembro técnico de la comisión directiva, porque es una afirmación estructural y no una promesa.
El menú lo escribe la plataforma, no el asistente. Un asistente no puede inventar una herramienta. Si "eliminar a todos los socios" no está en el menú, no es algo que se pueda pedir: ni con una instrucción ingeniosa, ni por accidente, ni por un asistente al que le metieron una instrucción maliciosa escondida en una página web. El conjunto de acciones posibles es finito, es nuestro y es el mismo para todos.
Cada solicitud se verifica cuando llega, no cuando se creó el token. Esta es la diferencia entre una llave y una trampilla abierta. Un token actúa como la persona que lo creó, contra la respuesta vigente a "¿puede esta persona hacer esto, ahora mismo, en esta organización?". Si le quitas a esa persona el rol de administrador, el token deja de funcionar en su siguiente solicitud. No hay que acordarse de nada, ni revocar ni limpiar nada para que eso pase, aunque revocarlo es un clic si igual quieres eliminarlo. Las escrituras dependen del permiso específico que necesitan, y la limitación propia del token se aplica por encima; limitar solo puede quitar capacidades, nunca agregarlas. El mismo modelo de roles y permisos que gobierna lo que una persona ve en el panel es el que gobierna al asistente.
Y el menú tiene un límite firme. Hay más de 200 herramientas, y ninguna envía un correo electrónico o un SMS, cobra un pago o hace un reembolso. Dilo en voz alta en una reunión de la comisión directiva, porque es la frase que hace comprensible el riesgo: un agente con permiso de publicación puede publicar una página y aun así no puede enviarle ni un solo correo a un socio. Las herramientas que mencionan el correo y los SMS son reportes de entrega, listas de bloqueo y lecturas de configuración. Las difusiones se redactan, nunca se envían.
Hay dos protecciones más que vale la pena nombrar. Toda herramienta que cambia algo hace una prueba por defecto: informa lo que haría y se detiene, y solo sigue cuando se le indica explícitamente que confirme, lo que significa que una persona ve el plan antes de que ocurra el cambio. Y cada lectura y cada escritura quedan en el registro de auditoría del club con el nombre de la persona real, así que "¿qué hizo el asistente el martes?" es una pregunta con respuesta. Las conexiones además tienen un límite de 120 solicitudes por minuto por token.
Cómo elegir
| Comparado en | Clave de API REST | Webhooks | Token MCP |
|---|---|---|---|
| Quién escribe el código | Tú | Tú | Nadie |
| Quién lo inicia | Tu código | La plataforma | La persona que pregunta |
| Dirección | Pedir, a demanda | Recibir, cuando ocurre el evento | Preguntar, conversando |
| ¿Puede cambiar datos? | No: solo lectura | No: solo saliente | Solo si marcas las casillas |
| Funciona sin supervisión | Sí | Sí | No: lo maneja una persona |
| Mejor para | Reportes y tableros repetibles | "Avísale a mi sistema cuando pase X" | Preguntas puntuales y trabajo de redacción |
| Peor para | Enterarse de algo en el segundo en que ocurre | Todo lo conversacional | Todo lo que tenga que correr a las 2 a. m., idéntico, para siempre |
Y en formato "elige esto si":
- Elige una clave de solo lectura si tienes a alguien que escribe algo de código y quieres los mismos números con la misma forma, en un horario que tú controlas.
- Elige webhooks si otro sistema necesita reaccionar a los eventos del club: contabilidad, turnos, una pantalla, un flujo de mensajes que manejas en otro lado.
- Elige un token MCP si el trabajo es una persona haciendo preguntas, comparando esta temporada con la anterior, redactando un boletín a partir de números reales u ordenando un lote de páginas: trabajo cuya forma cambia cada vez que lo haces.
- Elige más de uno si eso es lo que necesita el trabajo. No son alternativas, y nada impide que un club tenga un flujo nocturno por webhook y una conexión con un asistente al mismo tiempo.
Dónde MCP es la herramienta equivocada, sinceramente
Una conexión con un agente no reemplaza a las otras dos, y preferimos decirlo antes que venderte lo que no corresponde.
Una sincronización nocturna va en un webhook. Si el requisito es "cada pedido pagado tiene que aparecer en la contabilidad dentro de la hora, sin supervisión, para siempre", lo que quieres es una máquina que reaccione a un evento, no un asistente al que hay que preguntarle. A los agentes los maneja una persona con una pregunta; a una tarea programada la maneja un reloj.
Un reporte fijo va en una clave de API. Si once números van a los mismos once recuadros cada semana, escríbelo una vez y deja de pensar en eso. El determinismo es una virtud, y el código la tiene de una forma que una conversación no tiene.
Y nada debería hacerlo un agente si a una persona no se le permitiría hacerlo. Un token es el propio acceso de una persona, limitado. Nunca es una forma de esquivar un permiso, ni una forma de darle a un ayudante poderes que su rol no tiene.
Los límites que conviene leer antes de crear nada
Tres advertencias, dichas con claridad en lugar de escondidas.
Un token MCP omite la verificación adicional en dos pasos que se te pide al iniciar sesión en el panel desde el navegador, como cualquier token de API, porque ahí no hay un navegador que la pida. Justamente por eso los tokens vencen, se revocan con un clic y cada solicitud queda auditada. Dales un vencimiento razonable y trata cada uno como una copia de la llave de la sede social.
Las herramientas de datos de socios devuelven datos agregados (conteos por estado y por situación de pago), no nombres, direcciones de correo ni datos médicos. Es un mínimo deliberado, y conviene saberlo antes de hacerse expectativas sobre lo que un asistente te puede decir. Nuestra guía sobre seguridad y privacidad de la IA para clubes profundiza en las preguntas que debería hacerse una comisión directiva.
La pantalla es solo para administradores en todos los casos. La conexión con un asistente de IA funciona en todos los planes, incluido el gratuito; la clave REST y los webhooks son una función del plan Pro, porque ambos son grifos de datos masivos hacia otro sistema. Nuestra página de precios tiene el detalle.
Preguntas frecuentes
¿MCP no es simplemente una API con pasos extra?
Usa la misma tubería, pero el centro del diseño es otro. Una API es un contrato entre la plataforma y el código que tú escribiste, así que la pregunta de seguridad es si tu código es correcto. MCP es un contrato entre la plataforma y un software que toma sus propias decisiones, así que la pregunta de seguridad pasa a ser si la plataforma se niega como corresponde. Por eso las funciones interesantes son las negativas: un menú fijo, una verificación de permisos en vivo en cada solicitud, una prueba antes de cada cambio y una entrada de auditoría para todo. Podrías construir la misma disciplina a mano sobre una API. La gracia de un estándar abierto es que no tienes que hacerlo, y que cualquier asistente compatible recibe el mismo trato.
¿Podemos usar las tres al mismo tiempo?
Sí, y la mayoría de los clubes que llegan hasta aquí terminan haciendo exactamente eso. Un webhook alimenta la herramienta contable, una clave de solo lectura mueve la pantalla del hall y un token de asistente le permite al secretario hacer preguntas y redactar la noticia de la semana que viene. Se crean, se listan y se revocan desde la misma pantalla del panel, y cada uno es independiente: revocar el token del asistente no toca el webhook.
¿Qué pasa si roban un token?
Revócalo, en esa pantalla, con un clic. Después mira el registro de auditoría para ver qué se hizo con él. Lo que limita el daño mientras tanto es que el token nunca pudo hacer más que la persona a la que pertenece, y que ningún token de ningún tipo puede enviar un correo o un SMS, cobrar un pago o hacer un reembolso. Esas herramientas simplemente no existen en el menú. Si nunca marcaste "Permitir publicar", tampoco pudo hacer nada visible al público.
¿Necesitamos un desarrollador para algo de esto?
Para una clave de API o un webhook, sí: alguien tiene que escribir el código que los usa. Para un token MCP, no, y ese es el cambio real. Crear uno es completar un nombre, elegir un vencimiento y decidir si dejas dos casillas desactivadas; conectarlo es pegar una línea en el asistente. Si un club debería conectar uno es una decisión de la comisión directiva sobre los datos de los socios, no una decisión técnica, y por eso preferimos que leas la guía de seguridad y la página de acceso para agentes de IA antes del paso a paso.
¿Con cuál debería empezar un club pequeño?
Por lo general, con ninguna, y es una respuesta legítima. La mayoría de los clubes llegan más lejos usando lo que el panel ya hace que conectando cualquier cosa. Si algo realmente falta, empieza por la forma que coincide con la frase que repites: "ojalá pudiera ver…" es una clave o un reporte, "ojalá le avisara al otro sistema cuando…" es un webhook, y "ojalá pudiera simplemente preguntar…" es un asistente.
