Conectar un asistente de IA

Conecta un asistente de IA a ClubHelix y podrás gestionar tu organización desde un chat en tu propia computadora: preguntar cuántos socios tienen que renovar, redactar la noticia de esta semana u ordenar una página. Usas tu propio plan de Claude o ChatGPT, y el asistente solo puede ver y hacer lo que tú puedes.

Si todavía no conectaste ninguno, tu panel de administración muestra una tarjeta Gestiona tu club desde Claude o ChatGPT que enlaza a esta página. Ciérrala con la × y queda cerrada para ti en esta organización.

Esta página te guía de principio a fin. También explica la única regla que te dice de antemano si una herramienta en particular va a funcionar o no.

La regla que lo decide todo

ClubHelix autentica una conexión de IA con un token que pegas, enviado como encabezado Authorization. A propósito, no ofrecemos un flujo de inicio de sesión para las conexiones de IA.

Así que, antes de empezar:

• Si la herramienta te deja definir un encabezado personalizado, o pegar un token, se va a conectar. Claude Code, los clientes de editor que usan un archivo de configuración JSON y cualquier cosa que nos llame desde código están en este grupo.
• Si la herramienta solo te pide una dirección web y después intenta que inicies sesión, no se va a conectar. Te va a hacer dar vueltas en un ciclo de inicio de sesión o te va a pedir un "código de autorización", y no hay nada que lo emita. No es una falla de tu lado y ningún ajuste tuyo lo arregla; simplemente es el tipo de conexión equivocado para este endpoint.

Cuando estés frente a una pantalla de configuración que no conoces, eso es lo que tienes que buscar: algún lugar donde poner un token o un encabezado.

En la práctica, eso significa:

Quién puede usar esto

Un administrador pleno de la organización, en cualquier plan, incluido el Free. El token actúa como la persona que lo creó, así que nunca puede ver ni hacer más que ella, y deja de funcionar en el momento en que esa persona deja de ser administrador aquí.

Hay una cosa que nunca puede hacer, sea cual sea el plan y marques lo que marques: cambiar tu suscripción. Los planes, la facturación y la configuración de pagos son terreno del personal de la plataforma, fuera del alcance del token de cualquier organización.

Qué necesitas primero

1. El token. Se crea en la página API y webhooks. Empieza con chmx_ y se muestra una sola vez, así que cópialo antes de salir de la pantalla. ¿Lo perdiste? Revócalo y crea otro.
2. La dirección. https://clubhelix.com/api/mcp
3. Un lugar seguro para guardarlo. El token va en la configuración de tu herramienta o en un administrador de contraseñas. Nunca lo pegues en un mensaje de chat: eso deja una clave válida en la transcripción de una conversación.

Paso a paso

La guía completa, de principio a fin

Reserva unos diez minutos. Necesitas ser administrador aquí y tener una computadora donde puedas instalar una app.

1. Elige tu herramienta. Si pagas Claude, usa Claude Code o Claude Desktop. Si pagas ChatGPT, usa Codex. La tabla de arriba explica por qué.
2. Instálala e inicia sesión con tu cuenta de Claude o ChatGPT. La página de instalación de cada proveedor te guía, y solo lo haces una vez.
3. Crea un token aquí. En la administración, abre API y webhooks (el enlace Crear un token de la tarjeta del panel te lleva directo). En Acceso del asistente de IA (MCP):
   • Ponle al token un nombre que diga dónde va a estar, como Claude en la laptop del secretario.
   • Deja Vence en 90 días.
   • Marca Permitir cambios si quieres que el asistente cree y edite páginas, noticias y eventos. Déjalo sin marcar para empezar en modo de solo lectura.
   • Por ahora, deja Permitir publicar sin marcar. Así el asistente puede preparar el trabajo y una persona sigue siendo quien presiona publicar.
   • Presiona Crear token.
4. Copia el token de inmediato. Empieza con chmx_ y se muestra una sola vez. Guárdalo en un administrador de contraseñas, nunca en un chat.
5. Agrega ClubHelix a tu herramienta siguiendo la sección de tu herramienta, más abajo.
6. Comprueba que funcione. Pregunta "¿Como quién estás conectado y qué puedes ver?" (consulta Comprueba que funcione).
7. Prueba una tarea real, como "Resume nuestra membresía" o "Redacta una noticia sobre la jornada de trabajo voluntario del sábado". Con Permitir cambios marcado, los borradores aparecen en la administración para que los revises.

Cuando tienes un token activo, la tarjeta del panel deja de aparecer.

Claude Code (con un plan de Claude)

Es la opción con la que hacemos las pruebas, y la página de administración te muestra la línea exacta en Conectar Claude Code. Es un solo comando:

claude mcp add --transport http clubhelix https://clubhelix.com/api/mcp --header "Authorization: Bearer YOUR_TOKEN"

Reemplaza YOUR_TOKEN por el token que copiaste. Si prefieres, -t es la forma corta de --transport y -H la de --header.

Agrega --scope para elegir dónde se guarda la conexión:

• --scope local (el predeterminado): solo para ti, en la carpeta en la que estás trabajando.
• --scope user: disponible en todos los lugares donde trabajas.
• --scope project: se guarda en el propio proyecto y se comparte con cualquiera que lo tenga. No uses esta opción con un token pegado, o habrás confirmado una clave en el repositorio.

Como definiste un encabezado, Claude Code no va a intentar que inicies sesión, que es exactamente lo que queremos.

Codex (con un plan de ChatGPT)

Codex es el asistente de programación de OpenAI. Funciona en la terminal, en una extensión de editor y en la app de Codex, y entras con tu cuenta de ChatGPT. Los tres leen el mismo archivo de configuración, así que lo configuras una sola vez.

1. Pon el token en una variable de entorno en lugar de en el archivo. En Mac o Linux, agrega esta línea a tu perfil de shell (~/.zshrc o ~/.bashrc) y abre una terminal nueva:

   export CLUBHELIX_MCP_TOKEN="YOUR_TOKEN"
   

   En Windows, agrega una variable de entorno de usuario llamada CLUBHELIX_MCP_TOKEN en Propiedades del sistema → Variables de entorno y reinicia Codex.

2. Agrega ClubHelix a ~/.codex/config.toml (crea el archivo si no existe):

   [mcp_servers.clubhelix]
   url = "https://clubhelix.com/api/mcp"
   bearer_token_env_var = "CLUBHELIX_MCP_TOKEN"
   

   Codex lee la variable y la envía por ti como Authorization: Bearer …, así el token nunca queda en el archivo.

3. Reinicia Codex y hazle la pregunta de comprobación de abajo.

Esto es Codex, no la ventana de chat de chatgpt.com. La pantalla de conectores de la app de chat solo ofrece iniciar sesión, así que no puede conectarse.

Claude Desktop

La pantalla Connectors de Claude Desktop solo ofrece iniciar sesión, así que en su lugar agregas ClubHelix a su archivo de configuración mediante un pequeño puente llamado mcp-remote. El puente necesita tener Node.js instalado.

1. En Claude Desktop, abre Settings → Developer → Edit Config. Se abre claude_desktop_config.json.

2. Agrega una entrada clubhelix (conserva las entradas que ya haya):

   {
     "mcpServers": {
       "clubhelix": {
         "command": "npx",
         "args": [
           "-y",
           "mcp-remote",
           "https://clubhelix.com/api/mcp",
           "--header",
           "Authorization:${CLUBHELIX_AUTH}"
         ],
         "env": { "CLUBHELIX_AUTH": "Bearer YOUR_TOKEN" }
       }
     }
   }
   

   A propósito, no hay espacio después de Authorization:. Algunos sistemas cortan el argumento en un espacio, y entonces el token llega roto.

3. Cierra Claude Desktop por completo y vuelve a abrirlo. Solo lee el archivo al iniciar. Después, ClubHelix aparece en la lista de herramientas de un chat nuevo.

El token queda guardado en texto plano en ese archivo, así que haz esto solo en una computadora que sea tuya.

Un cliente que usa un archivo de configuración JSON

Las herramientas basadas en editores suelen guardar las conexiones MCP en un pequeño archivo JSON. La forma es la misma idea en todas partes: un nombre, la dirección y un bloque de encabezados:

{
  "servers": {
    "clubhelix": {
      "type": "http",
      "url": "https://clubhelix.com/api/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

Los nombres exactos de las claves cambian un poco de una herramienta a otra, así que revisa la documentación de tu herramienta en lugar de suponer. Hay dos cosas que conviene hacer sea cual sea la herramienta:

• Deja el token fuera del archivo si el archivo se comparte. La mayoría de estas herramientas admiten una solicitud o una variable para los secretos. Los editores que comparten la configuración a través del control de versiones advierten sobre esto con razón: un token en un archivo confirmado es un token que regalaste.
• Reinicia la herramienta después de editar el archivo. La mayoría solo lo lee al iniciar.

Llamarnos desde tu propio código

Si estás construyendo algo en lugar de configurar una app, la conexión es una definición de herramienta: un tipo mcp, una etiqueta, nuestra dirección y el token como valor de autorización. En la API principal se ve como server_url más authorization. Ten en cuenta que su proveedor documenta ese campo como un token de acceso OAuth; es el campo que lleva el valor bearer, que es lo que es el nuestro.

Cualquier otra herramienta, incluidas las apps de chat con pantalla de conectores

Estas pantallas cambian seguido, así que a propósito no publicamos una guía clic por clic que quedaría desactualizada en unas semanas. En su lugar, aplica la regla del principio:

1. Busca un campo para un token, una clave de API o un encabezado personalizado. Si lo hay, pega ahí el token (como Bearer YOUR_TOKEN si pide el valor completo del encabezado).
2. Si la única opción es escribir una dirección web e iniciar sesión, esa herramienta hoy no puede conectarse a ClubHelix.
3. Revisa la documentación actual de tu herramienta para ver cuál de las dos ofrece: la página del propio proveedor siempre está más actualizada que la nuestra.

Comprueba que funcione

Pregúntale al asistente:

¿Como quién estás conectado y qué puedes ver?

Una conexión que funciona nombra tu organización, el administrador dueño del token y los alcances que tiene. Después prueba algo real: "Resume nuestra membresía."

Cuando no funciona

Referencia de campos

Consejos y preguntas frecuentes

¿Puedo usar el mismo token en mi laptop y en mi celular? Puedes, pero es mejor no hacerlo. Crea un token por cada lugar donde va a estar y ponle un nombre acorde, así revocar el de una laptop perdida no corta todo lo demás.

¿Qué vencimiento conviene? Noventa días es el predeterminado y un buen hábito: obliga a hacer una revisión breve en lugar de dejar una clave activa para siempre. "Nunca" está disponible, y es la respuesta correcta muchas menos veces de lo que parece.

¿Puedo cambiar lo que puede hacer un token después de crearlo? No. Los alcances y los límites se fijan cuando se crea el token. Crea un token nuevo con la configuración que quieres, cambia tu herramienta al nuevo y después revoca el anterior.

Pegué el token en un chat sin querer. ¿Y ahora? Revócalo en la página API y webhooks y crea uno nuevo. La revocación tiene efecto de inmediato, en todas partes.

¿Conectar un asistente le permite enviar correos a nuestros socios? No. Nada en esta conexión puede enviar un correo o un mensaje de texto, cobrar un pago ni hacer un reembolso, marques lo que marques. Un asistente puede redactar una difusión; una persona elige la audiencia y presiona enviar.

¿Puedo usar el sitio web de ChatGPT o de claude.ai en lugar de una app en mi computadora? Hoy no. Sus pantallas de conectores solo ofrecen un flujo de inicio de sesión, y ClubHelix se conecta con un token. Usa Codex con tu plan de ChatGPT, o Claude Code o Claude Desktop con tu plan de Claude.

La tarjeta del panel volvió a aparecer. Se muestra mientras no tengas un token activo aquí. Si tu token venció o se revocó, crea uno nuevo y la tarjeta vuelve a desaparecer. Si cerraste la tarjeta con la ×, queda cerrada aunque no tengas token.

Otro administrador se conectó. ¿Por qué sigo viendo la tarjeta? Un token actúa como la persona que lo creó, así que cada administrador se conecta con el suyo.

¿Qué herramientas prueban realmente? Claude, incluido Claude Code. Cualquier otra que hable el mismo estándar abierto y te deje definir un encabezado debería funcionar, pero no podemos garantizar que la pantalla de configuración de una app en particular se comporte como la describe su proveedor.