Hay una pregunta que decide si una herramienta de IA puede conectarse a tu club, y puedes responderla antes de tocar un solo ajuste. ¿La herramienta acepta un encabezado Authorization personalizado o te deja pegar un token estático? Si es así, se conecta. Si solo acepta una URL y luego ejecuta un flujo de inicio de sesión (las pantallas suelen llamarlo OAuth), no puede. Terminará pidiéndote un código de autorización, y nada de nuestro lado puede emitirlo.
Eso no es una carencia que esté por resolverse. El endpoint del asistente de ClubHelix deliberadamente no publica metadatos de OAuth: una solicitud sin un token válido se rechaza con un 401 simple, y un cliente que interpreta ese rechazo como "este servidor quiere que inicie sesión" te llevará a un callejón sin salida. Conocer la regla primero te ahorra los veinte minutos de clics que terminan ahí.
Así que la estructura de esta guía es simple. Las herramientas que aceptan un encabezado funcionan, y te damos la configuración exacta para las principales. Las que insisten en un inicio de sesión no funcionan, y te mostramos cómo se ve ese fallo para que lo reconozcas en los primeros treinta segundos y no en los últimos.
Lo que necesitas antes de empezar
Tres cosas, y la primera ya la tendrás si leíste cómo conectar un asistente de IA a los datos de tu club.
Un token de conexión. Créalo en la administración de tu club, en Sistema → API y webhooks, en la tarjeta titulada Acceso del asistente de IA (MCP). Ponle un nombre según dónde va a vivir (el texto de ejemplo incluso sugiere algo como "Claude en la laptop de la secretaría"), elige un vencimiento y decide si marcas Permitir cambios (crear y editar páginas, noticias, eventos) y Permitir publicar (hacer visibles los cambios al público). Con ambas sin marcar, la conexión es de solo lectura, y de ahí debería partir todo club.
El endpoint. Es el mismo para todos los clubes y todas las herramientas:
https://clubhelix.com/api/mcp
Ningún plan en particular. El acceso del asistente funciona en todos los planes que ofrecemos, incluido el gratuito; consulta los precios para ver qué incluye cada plan. Lo que un token nunca puede hacer, en ningún plan, es cambiar tu suscripción: los planes, la facturación y los ajustes de pago son herramientas del personal de la plataforma y ningún token de una organización llega a ellas.
Una advertencia que importa más que cualquiera de las configuraciones de abajo: el token se muestra exactamente una vez. Cópialo a un administrador de contraseñas en cuanto aparezca, porque la pantalla no volverá a mostrarlo. Se guarda con hash, así que nadie, nosotros incluidos, puede leértelo de vuelta. Si lo pierdes, lo revocas y creas otro, lo que lleva unos quince segundos y no pasa nada.
Claude Code: el camino contra el que probamos
Esta es la ruta totalmente verificada, y es la que imprime nuestra propia página de administración. Abre el panel Conectar Claude Code en la tarjeta del token y verás este comando con tu endpoint ya incluido:
claude mcp add --transport http clubhelix https://clubhelix.com/api/mcp --header "Authorization: Bearer YOUR_TOKEN"
Reemplaza YOUR_TOKEN por el token que copiaste. Las opciones cortas funcionan igual si las prefieres: -t para --transport y -H para --header. La referencia completa de opciones está en la documentación de MCP de Claude Code.
Dónde queda esa configuración lo controla la opción de alcance:
--scope locales el valor por defecto y escribe en tu~/.claude.jsonpersonal. La conexión es tuya, en esta máquina.--scope projectescribe en.mcp.jsonen el repositorio en el que estés. Es útil cuando un grupo pequeño comparte una carpeta de trabajo, pero lee la advertencia sobre el token más abajo antes de acercarte.--scope userhace que la conexión esté disponible para ti en todos los proyectos de esa máquina.
Para una persona de la comisión con una sola laptop, el valor por defecto es el correcto y puedes ignorar la opción por completo.
La razón por la que esta ruta es la confiable es un comportamiento documentado y no la suerte. Claude Code no recurre a un flujo de inicio de sesión una vez que configuraste un encabezado personalizado, y reporta un 401 o un 403 como una conexión fallida y no como "este servidor necesita autenticación". Así, un token incorrecto falla de forma inmediata y evidente, en lugar de llevarte a un inicio de sesión que nunca habría podido completarse. Ese es exactamente el comportamiento que necesita un servidor de token estático como el nuestro, y por eso te mandamos aquí primero.
Un editor o cliente de escritorio que usa un archivo de configuración JSON
Varias herramientas (VS Code y los editores y clientes de escritorio que copiaron su forma) configuran las conexiones del asistente en un pequeño archivo JSON y no en una línea de comandos. En VS Code el archivo es .vscode/mcp.json dentro de tu proyecto, o tu copia personal del perfil, que el editor abre por ti con el comando MCP: Open User Configuration.
La forma es un objeto servers, un nombre que tú elijas y luego los detalles de la conexión:
{
"servers": {
"clubhelix": {
"type": "http",
"url": "https://clubhelix.com/api/mcp",
"headers": {
"Authorization": "Bearer ${input:clubhelix-token}"
}
}
}
}
De ese bloque conviene llevarse dos cosas en lugar de copiarlo a ciegas.
No pongas el token mismo en el archivo. La propia documentación de VS Code es tajante: "Avoid hardcoding sensitive information like API keys" (evita escribir directamente información sensible como claves de API), y te manda a usar variables de entrada, que es lo que hace el marcador ${input:clubhelix-token} de arriba. Configurado así, el editor te pide el token una vez y lo mantiene fuera del archivo. Esto importa sobre todo en la configuración a nivel de proyecto: un archivo JSON dentro de una carpeta compartida es un archivo que se copia, se comprime, se envía por correo y de vez en cuando se sube a un repositorio, y un token que se filtra así es una llave que funciona para la administración de tu club.
Los nombres de los campos varían un poco entre clientes. La estructura servers → nombre → type y url es estable y muy copiada, pero el bloque que lleva el encabezado es donde los clientes difieren: algunos lo llaman headers, algunos escriben el transporte de otra manera, algunos exponen el encabezado en un panel de ajustes en lugar del archivo. Si el tuyo no acepta el bloque de arriba tal cual, es normal: ve a la documentación actual de esa herramienta y busca el lugar donde te deja configurar un encabezado de solicitud. Todo lo demás que necesitas ya está en esta guía.
Llamarlo desde la API de OpenAI
Si estás integrando la conexión en algo que estás construyendo tú y no en un cliente de chat, la API de OpenAI acepta una herramienta de type: "mcp". Los campos documentados son server_label, server_url y, opcionalmente, server_description, allowed_tools, require_approval y authorization:
{
"type": "mcp",
"server_label": "clubhelix",
"server_url": "https://clubhelix.com/api/mcp",
"require_approval": "always",
"authorization": "YOUR_TOKEN"
}
Sé preciso con lo que es ese último campo. OpenAI no documenta ningún campo headers en esta herramienta, y documenta authorization como portador de un token de acceso emitido por un flujo de inicio de sesión. Es el campo donde va un valor bearer. No afirmamos que OpenAI haya dado su visto bueno a pegar ahí un token estático de larga duración: te decimos dónde corresponde el valor bearer en la forma que ellos publican, y dejamos que decidas tú si eso sirve para tu desarrollo.
Vale la pena mirar allowed_tools ya que estás ahí. Permite a quien hace la llamada acotar qué herramientas puede usar el modelo, lo que combina muy bien con la restricción que ya puedes aplicar al propio token en Limitar lo que puede tocar este token. Dos límites independientes, y ambos solo pueden quitar capacidad.
Cualquier otra, incluidas las pantallas de conectores de las aplicaciones de chat
Esta es la sección honesta, y es corta a propósito.
Muchos productos de IA tienen ahora una pantalla para agregar una conexión: una página de conectores, una pestaña de integraciones, un cuadro de diálogo de "servidor MCP personalizado". No vamos a describir los campos ni el camino de clics en ninguna de ellas, incluida la pantalla de conectores de ChatGPT. La razón no es timidez: no pudimos encontrar una fuente primaria del proveedor que diga qué opciones de autenticación ofrecen esas pantallas, y los artículos de terceros que las describen se contradicen entre sí. Publicar una guía clic por clic de la pantalla de ajustes de otra empresa basándonos en eso sería adivinar con tono seguro, y esas pantallas cambian con tanta frecuencia que incluso una guía exacta queda desactualizada en semanas. Por eso describimos la forma, y tú consultas la documentación actual del proveedor para los clics.
Esta es la forma que debes buscar, y es la regla del comienzo de esta guía aplicada con tus propios ojos:
Busca un lugar donde pegar un token o configurar un encabezado de solicitud. No vamos a adivinar cómo llama tu herramienta a ese campo, porque los nombres difieren entre productos y cambian entre versiones, pero si la pantalla te ofrece uno, pega ahí tu token como valor bearer, apunta la conexión a https://clubhelix.com/api/mcp y estarás conectado.
Fíjate en el fallo. Si la pantalla solo acepta una URL y enseguida te manda a una página de inicio de sesión, o te pide pegar de vuelta un código de autorización, detente. Esa herramienta está intentando un flujo de inicio de sesión, ClubHelix no publica nada contra lo cual pueda iniciar sesión, y ningún reintento cambia eso. Usa una herramienta que te deje configurar el encabezado: Claude Code es la que probamos y la que tiene un comando impreso en nuestra página de administración.
Después ve a la documentación actual del propio proveedor para los nombres exactos de los campos y el camino de clics vigente. Preferimos mandarte a una página que es correcta esta semana antes que imprimir una que lo era la semana en que publicamos.
Comprueba que funcionó
No asumas que una conexión está activa porque una pantalla de ajustes se puso en verde. Hazle al asistente una pregunta que solo una conexión real pueda responder:
¿Con quién estás conectado y qué puedes ver?
Una conexión que funciona responde con el nombre de tu organización, el administrador cuyo token está usando y el alcance que lleva ese token. Si te dice qué club está mirando, estás conectado al club correcto: el token está fijado a una organización y no puede llegar a otra, así que un nombre equivocado aquí significa un token equivocado y no un ajuste equivocado.
Luego pregunta algo real:
Resume nuestra membresía.
Deberías recibir cifras (totales y estado de pagos) y no una lista de personas. Eso es deliberado: las herramientas que tocan datos de socios devuelven números agregados, no nombres, direcciones de correo ni datos médicos. Si llega esa respuesta, la conexión está cumpliendo su función.
Cuando no funciona
Seis fallos cubren casi todo, y cada uno te dice qué cambiar.
Te piden iniciar sesión o un código de autorización. El cliente está intentando un inicio de sesión OAuth. No hay nada que arreglar de nuestro lado ni del tuyo: cambia a un cliente que te deje configurar un encabezado personalizado.
Recibes un 401. El problema es el token mismo: mal escrito, vencido o revocado. Revísalo contra la lista de tokens de la página de administración y crea uno nuevo si tienes dudas; el valor solo se muestra una vez, así que lo más común es un token copiado a medias.
Recibes un 403 que dice que el propietario ya no es administrador. El token está bien; la persona a la que pertenece ya no es administradora del club. Esto toma a la gente por sorpresa y funciona como debe: la plataforma vuelve a verificar el rol del propietario en cada solicitud, así que un traspaso de la comisión directiva anula la conexión en silencio en el momento en que cambia el rol. Crea un token nuevo a nombre de quien tiene el cargo ahora.
Te rechazan una tarea concreta con un mensaje sobre tu plan. La conexión en sí no depende del plan, pero los módulos individuales sí: si le pides a un agente que active algo que tu plan no incluye, te lo rechaza nombrando el plan, en lugar de escribir sin avisar una fila que no cambia nada.
Un rechazo que nombra un permiso. El token se limitó cuando se creó, o su propietario no tiene ese permiso. Recuerda que el token actúa como la persona que lo creó y nunca puede hacer más que esa persona: revisa primero los permisos de la persona y luego los del token. Qué alcance darle a un asistente de IA guía a una comisión para elegir esos límites.
Nada en absoluto, desde ninguna herramienta. Hay un interruptor a nivel de plataforma que apaga todo el endpoint del asistente. Si todas las herramientas y todos los tokens quedan sin respuesta a la vez, esa es la causa más probable, y nos toca revisarla a nosotros y no a ti.
Uno más que no es un fallo pero lo parece: la conexión tiene un límite de 120 solicitudes por minuto por token. Una persona haciendo preguntas nunca se acercará a ese límite; un script en un bucle sí.
Mantén el token donde corresponde
La única regla que vale la pena imprimir: el token va en la configuración de la herramienta, nunca en una conversación. No lo pegues en un mensaje de chat al asistente, en un mensaje grupal a la comisión ni en un documento compartido. Un token es una llave de la sede: actúa como un administrador con nombre, y el registro de auditoría del club anota todo lo que hace bajo el nombre de esa persona.
Hay un límite que conviene conocer y no descubrir. Un token de conexión, como cualquier token de API, omite el paso adicional de verificación en dos pasos del navegador: es una llave que funciona por sí sola, sin el segundo factor que se le pide a una persona cuando inicia sesión en la administración. Precisamente por eso la plataforma lo hace vencer, lo hace revocable con un clic y registra todo lo que hace en el registro de auditoría. Esos tres controles son los que reemplazan ese paso, así que trátalos como la salvaguarda y no como trámite.
Los valores por defecto están de tu lado. El vencimiento por defecto es de 90 días, lo bastante corto para que un token olvidado se retire solo y lo bastante largo para no ser una molestia. Revocar es un clic y surte efecto en todas partes a la vez. Y los límites estructurales de la plataforma se mantienen sin importar qué herramienta conectaste: cada cambio se simula primero y se te muestra como un plan antes de que ocurra, y de las más de 200 herramientas de la conexión, ninguna envía un correo ni un SMS, cobra un pago ni emite un reembolso. Un asistente al que le permitiste publicar una página igualmente no puede enviarle correo a ningún socio.
Vale la pena detenerse en eso, porque es la diferencia entre una política y una garantía. Lee más sobre cómo manejamos las credenciales y el acceso en nuestra página de seguridad, y sobre qué expone la conexión en la página de la función acceso de agentes de IA.
Preguntas frecuentes
¿Qué herramientas de IA pueden conectarse realmente a ClubHelix?
Cualquiera que te deje configurar un encabezado Authorization personalizado o pegar un token estático. Claude Code es la ruta verificada y la que tiene un comando impreso en nuestra página de administración. Los editores de código y los clientes de escritorio que usan un archivo de configuración JSON también funcionan, siempre que el archivo o su panel de ajustes te dé un lugar donde poner un encabezado. Las herramientas que aceptan solo una URL y luego ejecutan un flujo de inicio de sesión no pueden conectarse, porque no publicamos metadatos de inicio de sesión para que usen.
¿Por qué mi herramienta de IA sigue pidiéndome que inicie sesión en ClubHelix?
Porque está intentando un flujo de inicio de sesión en lugar de leer el token que le diste. Nuestro endpoint rechaza una solicitud no autenticada con un 401 simple y no ofrece metadatos de inicio de sesión, así que un cliente diseñado para iniciar un inicio de sesión en ese punto te pedirá un código de autorización que nada de nuestro lado puede emitir. No es una mala configuración que puedas corregir: usa un cliente que acepte un encabezado.
¿Puedo poner el token en un archivo de configuración que comparte mi comisión?
Puedes, pero piénsalo bien primero. Un archivo de configuración compartido se copia, se comprime y de vez en cuando se sube a un repositorio, y el token que contiene es una llave que funciona para la administración de tu club, actuando como una persona con nombre. El mejor patrón es el que recomiendan los propios editores: usar una variable de entrada para que la herramienta te pida el token y lo mantenga fuera del archivo. Si compartes una conexión, crea un token para ese fin, con un vencimiento corto y solo los permisos que necesita.
¿Qué pasa con la conexión cuando nuestra secretaria deja el cargo?
Deja de funcionar, de inmediato y sin que nadie tenga que acordarse de hacer nada. El token actúa como la persona que lo creó y la plataforma vuelve a verificar el rol de esa persona en cada solicitud, así que en el momento en que pierde el rol de administradora la conexión queda muerta. Crea un token nuevo a nombre de la persona que asume el cargo. Esto también hace que el registro de auditoría sea legible: cada acción que tomó el asistente queda registrada a nombre de la persona real a la que pertenecía el token.
¿Necesito ser desarrollador para configurar esto?
Para Claude Code, no: copias una línea de la página de administración, le pegas tu token y la ejecutas. Para la ruta del archivo JSON necesitas sentirte cómodo editando un pequeño archivo de texto, algo más fácil de lo que suena. La ruta de la API de OpenAI es para quienes están construyendo algo, y si ese no es tu caso, no la necesitas.
