Conectar um assistente de IA

Conecte um assistente de IA ao ClubHelix e você pode administrar a sua organização a partir de um chat no seu próprio computador: pergunte quantos sócios precisam renovar, escreva a notícia desta semana ou arrume uma página. Você usa o seu próprio plano do Claude ou do ChatGPT, e o assistente só consegue ver e fazer o que você consegue.

Se você ainda não conectou nenhum, o seu painel mostra um cartão Gerencie o seu clube pelo Claude ou pelo ChatGPT com um link para esta página. Feche-o com o × e ele fica fechado para você nesta organização.

Esta página guia você do começo ao fim. Ela também explica a única regra que diz de antemão se uma ferramenta vai funcionar ou não.

A regra que decide tudo

O ClubHelix autentica uma conexão de IA com um token que você cola, enviado como um cabeçalho Authorization. De propósito, não oferecemos um fluxo de login para conexões de IA.

Então, antes de começar:

• Se a ferramenta deixa você definir um cabeçalho personalizado, ou colar um token, ela vai conectar. O Claude Code, os clientes de editor que usam um arquivo de configuração JSON e qualquer coisa que nos chame a partir de código entram nesse grupo.
• Se a ferramenta só pede um endereço web e depois tenta fazer você entrar, ela não vai conectar. Ela vai levar você a um ciclo de login, ou pedir um "código de autorização" — e não há nada que emita um. Não é um problema do seu lado e nenhuma configuração sua resolve; é simplesmente o tipo errado de conexão para este endpoint.

Quando você estiver diante de uma tela de configurações desconhecida, é isso que deve procurar: algum lugar para colocar um token ou um cabeçalho.

Na prática, isso significa:

Quem pode usar

Um administrador pleno da organização, em qualquer plano — inclusive o Free. O token age como a pessoa que o criou, então nunca consegue ver ou fazer mais do que ela, e para de funcionar no momento em que ela deixa de ser administradora aqui.

Uma coisa que ele nunca pode fazer, seja qual for o plano e o que você marcar: alterar a sua assinatura. Planos, cobrança e configurações de pagamento são território da equipe da plataforma, fora do alcance do token de qualquer organização.

O que você precisa antes

1. O token. Criado na página API e webhooks. Ele começa com chmx_ e é mostrado uma única vez, então copie-o antes de sair da tela. Perdeu? Revogue-o e crie outro.
2. O endereço. https://clubhelix.com/api/mcp
3. Um lugar seguro para guardá-lo. O token vai na configuração da sua ferramenta ou em um gerenciador de senhas. Nunca cole o token em uma mensagem de chat — isso coloca uma chave funcionando na transcrição de uma conversa.

Passo a passo

O guia completo, do começo ao fim

Reserve uns dez minutos. Você precisa ser administrador aqui e precisa de um computador em que possa instalar um app.

1. Escolha a sua ferramenta. Se você paga pelo Claude, use o Claude Code ou o Claude Desktop. Se paga pelo ChatGPT, use o Codex. A tabela acima explica por quê.
2. Instale e entre com a sua conta do Claude ou do ChatGPT. A página de instalação de cada fornecedor guia você nisso, e você só faz isso uma vez.
3. Crie um token aqui. No painel, abra API e webhooks (o link Criar um token do cartão do painel leva direto para lá). Em Acesso de assistente de IA (MCP):
   • Dê ao token um nome que diga onde ele vai ficar, como Claude no notebook da secretaria.
   • Deixe Expira em com 90 dias.
   • Marque Permitir alterações se quiser que o assistente crie e edite páginas, notícias e eventos. Deixe desmarcado para começar só com leitura.
   • Por enquanto, deixe Permitir publicação desmarcado. Assim o assistente pode preparar o trabalho, e uma pessoa continua apertando o botão de publicar.
   • Clique em Criar token.
4. Copie o token na hora. Ele começa com chmx_ e só é mostrado uma vez. Guarde-o em um gerenciador de senhas, nunca em um chat.
5. Adicione o ClubHelix à sua ferramenta seguindo a seção dela abaixo.
6. Confira se funcionou. Pergunte "Com quem você está conectado e o que consegue ver?" (veja Confira se funcionou).
7. Experimente uma tarefa real, como "Resuma a situação dos nossos sócios" ou "Escreva uma notícia sobre o mutirão de sábado". Com Permitir alterações marcado, os rascunhos aparecem no painel para você revisar.

Assim que você tiver um token ativo, o cartão do painel deixa de aparecer.

Claude Code (com um plano do Claude)

Este é o caminho que usamos nos nossos testes, e a página do painel mostra a linha exata para você em Conectar o Claude Code. É um único comando:

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

Troque YOUR_TOKEN pelo token que você copiou. -t é a forma curta de --transport e -H de --header, se preferir.

Adicione --scope para escolher onde a conexão fica salva:

• --scope local (o padrão) — só para você, na pasta em que você está trabalhando.
• --scope user — disponível em todos os lugares em que você trabalha.
• --scope project — salvo no próprio projeto e compartilhado com qualquer pessoa que tenha acesso a ele. Não use esta opção com um token colado, ou você terá versionado uma chave.

Como você definiu um cabeçalho, o Claude Code não vai tentar fazer você entrar, que é exatamente o que queremos.

Codex (com um plano do ChatGPT)

O Codex é o assistente de programação da OpenAI. Ele roda no terminal, em uma extensão de editor e no app Codex, e você entra nele com a sua conta do ChatGPT. Os três leem o mesmo arquivo de configuração, então você configura isso uma única vez.

1. Coloque o token em uma variável de ambiente em vez de no arquivo. No Mac ou no Linux, adicione esta linha ao seu perfil do shell (~/.zshrc ou ~/.bashrc) e abra um novo terminal:

   export CLUBHELIX_MCP_TOKEN="YOUR_TOKEN"
   

   No Windows, adicione uma variável de ambiente de usuário chamada CLUBHELIX_MCP_TOKEN em Propriedades do Sistema → Variáveis de Ambiente e reinicie o Codex.

2. Adicione o ClubHelix a ~/.codex/config.toml (crie o arquivo se ele não existir):

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

   O Codex lê a variável e a envia como Authorization: Bearer … para você, então o token nunca fica no arquivo.

3. Reinicie o Codex e faça a pergunta de verificação abaixo.

Isto é o Codex, não a janela de chat em chatgpt.com. A tela de conectores do app de chat só oferece login, então não consegue conectar.

Claude Desktop

A tela Connectors do Claude Desktop só oferece login, então, em vez disso, você adiciona o ClubHelix ao arquivo de configuração dele por meio de uma pequena ponte chamada mcp-remote. A ponte precisa do Node.js instalado.

1. No Claude Desktop, abra Settings → Developer → Edit Config. Isso abre o claude_desktop_config.json.

2. Adicione uma entrada clubhelix (mantenha as entradas que já existirem):

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

   De propósito, não há espaço depois de Authorization:. Alguns sistemas dividem o argumento em um espaço, e aí o token chega quebrado.

3. Feche o Claude Desktop por completo e abra de novo. Ele só lê o arquivo ao iniciar. O ClubHelix então aparece na lista de ferramentas de um novo chat.

O token fica guardado em texto simples nesse arquivo, então só faça isso em um computador que seja seu.

Um cliente que usa um arquivo de configuração JSON

As ferramentas baseadas em editor geralmente guardam as conexões MCP em um pequeno arquivo JSON. O formato segue a mesma ideia em todo lugar — um nome, o endereço e um bloco de cabeçalhos:

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

Os nomes exatos das chaves variam um pouco entre as ferramentas, então consulte a documentação da sua em vez de supor. Duas coisas valem a pena seja qual for a ferramenta:

• Mantenha o token fora do arquivo se o arquivo for compartilhado. A maioria dessas ferramentas aceita um prompt ou uma variável para segredos. Os editores que compartilham a configuração pelo controle de versão avisam sobre isso por um bom motivo — um token em um arquivo versionado é um token que você entregou para outras pessoas.
• Reinicie a ferramenta depois de editar o arquivo. A maioria só o lê ao iniciar.

Chamar a gente a partir do seu próprio código

Se você está desenvolvendo algo em vez de configurar um app, a conexão é uma definição de ferramenta: um tipo mcp, um rótulo, o nosso endereço e o token como valor de autorização. Na principal API, isso aparece como server_url mais authorization. Observe que esse campo é documentado pelo fornecedor como um token de acesso OAuth; é o campo que carrega o valor bearer, que é o que o nosso token é.

Qualquer outra ferramenta, inclusive apps de chat com tela de conectores

Essas telas mudam com frequência, então, de propósito, não publicamos um passo a passo clique por clique que ficaria desatualizado em poucas semanas. Em vez disso, aplique a regra do início:

1. Procure um campo para um token, uma chave de API ou um cabeçalho personalizado. Se houver, cole o token ali (como Bearer YOUR_TOKEN se ele pedir o valor inteiro do cabeçalho).
2. Se a única opção for informar um endereço web e fazer login, esta ferramenta não consegue se conectar ao ClubHelix hoje.
3. Consulte a documentação atual da sua ferramenta para ver qual dessas opções ela oferece — a página do próprio fornecedor está sempre mais atualizada que a nossa.

Confira se funcionou

Pergunte ao assistente:

Com quem você está conectado e o que consegue ver?

Uma conexão que funciona informa o nome da sua organização, o administrador dono do token e os escopos que ele tem. Depois, experimente algo real: "Resuma a situação dos nossos sócios."

Quando não funciona

Referência de campos

Dicas e perguntas frequentes

Posso usar o mesmo token no notebook e no celular? Pode, mas é melhor não. Crie um token para cada lugar onde ele vai ficar e dê um nome de acordo, para que revogar o de um notebook perdido não corte todo o resto.

Qual deve ser a validade? Noventa dias é o padrão e um hábito sensato — obriga a uma revisão rápida em vez de deixar uma chave ativa para sempre. "Nunca" está disponível, e é a resposta certa muito menos vezes do que parece.

Posso mudar o que um token pode fazer depois de criá-lo? Não. Os escopos e limites são fixados quando o token é criado. Crie um novo token com as configurações que você quer, troque na sua ferramenta e depois revogue o antigo.

Colei o token em um chat sem querer. E agora? Revogue-o na página API e webhooks e crie um novo. A revogação vale na hora, em todo lugar.

Conectar um assistente deixa ele mandar e-mails para os nossos sócios? Não. Nada nesta conexão consegue enviar um e-mail ou uma mensagem de texto, receber um pagamento ou fazer um reembolso — seja o que for que você marque. Um assistente pode escrever o rascunho de um comunicado; uma pessoa escolhe o público e aperta enviar.

Posso usar o site do ChatGPT ou do claude.ai em vez de um app no meu computador? Hoje, não. As telas de conectores deles só oferecem um fluxo de login, e o ClubHelix se conecta com um token. Use o Codex com o seu plano do ChatGPT, ou o Claude Code ou o Claude Desktop com o seu plano do Claude.

O cartão do painel voltou. Ele aparece enquanto você não tem um token ativo aqui. Se o seu token expirou ou foi revogado, crie um novo e o cartão some de novo. Se você fechou o cartão com ×, ele continua fechado mesmo sem token.

Um coadministrador se conectou. Por que eu ainda vejo o cartão? Um token age como a pessoa que o criou, então cada administrador se conecta com o próprio token.

Quais ferramentas vocês testam de fato? O Claude, incluindo o Claude Code. Qualquer outra coisa que fale o mesmo padrão aberto e deixe você definir um cabeçalho deve funcionar, mas não podemos garantir que a tela de configurações de um app específico se comporte como o fornecedor descreve.