Há uma pergunta que decide se qualquer ferramenta de IA consegue se conectar ao seu clube, e você pode respondê-la antes de mexer em uma única configuração. A ferramenta aceita um cabeçalho Authorization personalizado ou permite colar um token estático? Se sim, ela se conecta. Se ela só aceita uma URL e depois executa um fluxo de login (as telas costumam chamar isso de OAuth), não se conecta. Ela vai acabar pedindo um código de autorização, e nada do nosso lado consegue emitir um.
Isso não é uma lacuna à espera de ser preenchida. O endpoint do assistente do ClubHelix deliberadamente não publica metadados de OAuth: uma requisição sem token válido é recusada com um 401 simples, e um cliente que leia essa recusa como "este servidor quer que eu inicie um login" vai levar você a um beco sem saída. Conhecer a regra antes poupa os vinte minutos de cliques que terminam ali.
Por isso o formato deste guia é simples. As ferramentas que aceitam um cabeçalho funcionam, e damos a configuração exata das principais. As ferramentas que insistem em um login não funcionam, e contamos como essa falha aparece para você reconhecê-la nos primeiros trinta segundos, e não nos últimos.
O que você precisa antes de começar
Três coisas, e você já terá a primeira se leu como conectar um assistente de IA aos dados do seu clube.
Um token de conexão. Crie-o no painel do seu clube em Sistema → API e webhooks, no cartão chamado Acesso do assistente de IA (MCP). Dê a ele o nome do lugar onde vai ficar (o texto de exemplo até sugere algo como "Claude no notebook da secretária"), escolha uma validade e decida se vai marcar Permitir alterações (criar e editar páginas, notícias e eventos) e Permitir publicação (tornar as alterações visíveis ao público). Com as duas desmarcadas a conexão é somente leitura, que é por onde todo clube deve começar.
O endpoint. É o mesmo para todos os clubes e todas as ferramentas:
https://clubhelix.com/api/mcp
Nenhum plano em particular. O acesso do assistente funciona em todos os planos que oferecemos, inclusive o gratuito; veja os preços para saber o que cada plano inclui. O que um token nunca pode fazer, em nenhum plano, é alterar a sua assinatura: planos, cobrança e configurações de pagamento são ferramentas da equipe da plataforma, e nenhum token de organização chega a elas.
Um aviso que importa mais do que qualquer configuração abaixo: o token é exibido uma única vez. Copie-o para um gerenciador de senhas assim que aparecer, porque a tela não o mostrará de novo. Ele é guardado com hash, então ninguém, nem nós, consegue lê-lo de volta para você. Se perdê-lo, você o revoga e cria outro, o que leva uns quinze segundos e é perfeitamente normal.
Claude Code: o caminho que testamos
Este é o caminho totalmente verificado, e é o que a nossa própria página de administração imprime para você. Abra o painel Conectar o Claude Code no cartão de tokens e ele mostra este comando com o seu endpoint já no lugar:
claude mcp add --transport http clubhelix https://clubhelix.com/api/mcp --header "Authorization: Bearer YOUR_TOKEN"
Substitua YOUR_TOKEN pelo token que você copiou. As opções curtas funcionam do mesmo jeito, se você preferir: -t para --transport e -H para --header. A referência completa das opções está na documentação de MCP do Claude Code.
O destino dessa configuração é controlado pela opção de escopo:
--scope localé o padrão e grava no seu~/.claude.jsonpessoal. A conexão é sua, neste computador.--scope projectgrava em.mcp.jsonno repositório em que você está. Útil quando um grupo pequeno divide uma pasta de trabalho, mas leia o aviso sobre o token abaixo antes de chegar perto dele.--scope userdeixa a conexão disponível para você em todos os projetos nesse computador.
Para um dirigente de clube com um único notebook, o padrão está certo e você pode ignorar a opção por completo.
Este caminho é confiável por causa de um comportamento documentado, não por sorte. O Claude Code não recorre a um fluxo de login depois que você define um cabeçalho personalizado, e ele relata um 401 ou 403 como uma conexão que falhou, e não como "este servidor precisa de autenticação". Assim, um token errado falha de forma clara e imediata, em vez de jogar você num login que nunca poderia ser concluído. É exatamente o comportamento de que um servidor de token estático como o nosso precisa, e por isso indicamos este caminho primeiro.
Um editor ou cliente de desktop que usa um arquivo de configuração JSON
Várias ferramentas (o VS Code e os editores e clientes de desktop que copiaram o seu formato) configuram as conexões do assistente em um pequeno arquivo JSON, e não na linha de comando. No VS Code o arquivo é .vscode/mcp.json dentro do seu projeto, ou a cópia do seu perfil pessoal, que o editor abre para você pelo comando MCP: Open User Configuration.
O formato é um objeto servers, um nome à sua escolha e depois os detalhes da conexão:
{
"servers": {
"clubhelix": {
"type": "http",
"url": "https://clubhelix.com/api/mcp",
"headers": {
"Authorization": "Bearer ${input:clubhelix-token}"
}
}
}
}
Duas coisas a tirar desse bloco, em vez de copiá-lo às cegas.
Não coloque o próprio token no arquivo. A documentação do VS Code é direta quanto a isso ("Avoid hardcoding sensitive information like API keys") e indica variáveis de entrada, que é o que o marcador ${input:clubhelix-token} acima representa. Configurado assim, o editor pede o token uma vez e o mantém fora do arquivo. Isso importa mais na configuração do projeto: um arquivo JSON dentro de uma pasta compartilhada é um arquivo que é copiado, compactado, enviado por e-mail e, às vezes, enviado a um repositório, e um token que vaza assim é uma chave funcionando para o painel do seu clube.
Os nomes dos campos variam um pouco entre os clientes. A estrutura servers → nome → type e url é estável e muito copiada, mas o bloco que leva o cabeçalho é onde os clientes diferem: alguns o chamam de headers, alguns escrevem o transporte de outro jeito, alguns expõem o cabeçalho por um painel de configurações em vez do arquivo. Se a sua ferramenta não aceitar o bloco acima tal como está, isso é normal: vá à documentação atual dessa ferramenta e procure onde ela permite definir um cabeçalho de requisição. Todo o resto de que você precisa já está neste guia.
Chamando pela API da OpenAI
Se você está ligando a conexão a algo que está construindo, e não a um cliente de chat, a API da OpenAI aceita uma ferramenta do tipo type: "mcp". Os campos documentados são server_label, server_url e, opcionalmente, server_description, allowed_tools, require_approval e authorization:
{
"type": "mcp",
"server_label": "clubhelix",
"server_url": "https://clubhelix.com/api/mcp",
"require_approval": "always",
"authorization": "YOUR_TOKEN"
}
Seja preciso sobre o que é esse último campo. A OpenAI não documenta nenhum campo headers nessa ferramenta e documenta o authorization como portador de um token de acesso emitido por um fluxo de login. É o campo onde vai um valor bearer. Não estamos afirmando que a OpenAI aprovou colar ali um token estático de longa duração; estamos dizendo onde o valor bearer se encaixa no formato que ela publica, e deixando para você a avaliação de se isso serve para o seu projeto.
Vale olhar o allowed_tools enquanto você está ali. Ele permite que quem chama restrinja quais ferramentas o modelo pode usar, o que combina bem com a restrição que você já pode aplicar ao próprio token em Limitar o que este token pode acessar. São dois limites independentes, e ambos só podem tirar capacidade, nunca dar.
Qualquer outra coisa, inclusive as telas de conectores dos aplicativos de chat
Esta é a seção honesta, e é curta de propósito.
Muitos produtos de IA já têm uma tela para adicionar uma conexão: uma página de conectores, uma aba de integrações, uma janela de "servidor MCP personalizado". Não vamos descrever os campos nem o caminho de cliques de nenhuma delas, inclusive a tela de conectores do ChatGPT. O motivo não é timidez: não encontramos uma fonte primária do fornecedor dizendo quais opções de autenticação essas telas oferecem, e os textos de terceiros que as descrevem se contradizem. Publicar um passo a passo de cliques da tela de configuração de outra empresa com base nisso seria chutar em tom confiante, e essas telas mudam com frequência suficiente para que até um passo a passo correto fique desatualizado em semanas. Por isso descrevemos o formato, e você confere a documentação atual do fornecedor para os cliques.
Este é o formato a procurar, e é a regra do início deste guia aplicada com os seus próprios olhos:
Procure um lugar para colar um token ou definir um cabeçalho de requisição. Não vamos adivinhar como a sua ferramenta chama esse campo, porque os nomes diferem entre os produtos e mudam entre as versões; mas, se a tela oferecer um, cole o seu token ali como valor bearer, aponte a conexão para https://clubhelix.com/api/mcp e pronto, você está conectado.
Fique atento à falha. Se a tela aceita só uma URL e logo em seguida leva você a uma página de login, ou pede que você cole de volta um código de autorização, pare. Essa ferramenta está tentando um fluxo de login, o ClubHelix não publica nada para ela fazer login, e nenhuma quantidade de tentativas muda isso. Use uma ferramenta que permita definir o cabeçalho; o Claude Code é a que testamos e aquela para a qual o nosso painel imprime um comando.
Depois vá à documentação atual do próprio fornecedor para os nomes exatos dos campos e o caminho de cliques vigente. Preferimos mandar você a uma página que está certa esta semana a imprimir uma que estava certa na semana em que publicamos.
Confira se funcionou
Não presuma que uma conexão está ativa só porque uma tela de configurações ficou verde. Faça ao assistente uma pergunta que só uma conexão real consegue responder:
Com quem você está conectado e o que consegue ver?
Uma conexão funcionando responde com o nome da sua organização, o administrador cujo token está sendo usado e o escopo que esse token carrega. Se ele disser qual clube está vendo, você está conectado ao clube certo: o token é fixado a uma organização e não alcança outra, então um nome errado aqui significa um token errado, e não uma configuração errada.
Depois pergunte algo de verdade:
Resuma a nossa base de sócios.
Você deve receber contagens (totais e situação de pagamento) em vez de uma lista de pessoas. Isso é proposital: as ferramentas voltadas aos sócios devolvem números agregados, não nomes, endereços de e-mail ou dados médicos. Se essa resposta chegar, a conexão está cumprindo o seu papel.
Quando não funciona
Seis falhas cobrem quase tudo, e cada uma diz o que você deve mudar.
Pedem que você faça login ou informe um código de autorização. O cliente está tentando um login OAuth. Não há nada a corrigir do nosso lado nem do seu: troque por um cliente que permita definir um cabeçalho personalizado.
Você recebe um 401. O problema é o próprio token: digitado errado, expirado ou revogado. Confira-o na lista de tokens da página de administração e crie um novo na dúvida; o valor só é mostrado uma vez, então um token copiado pela metade é o culpado de sempre.
Você recebe um 403 dizendo que o dono não é mais administrador. O token está bom; a pessoa a quem ele pertence é que deixou de ser administradora do clube. Isso pega as pessoas de surpresa e está funcionando como deveria: a plataforma reverifica o papel do dono a cada requisição, então uma troca de diretoria derruba a conexão em silêncio assim que o papel muda. Crie um token novo em nome de quem ocupa o cargo agora.
Recusam uma tarefa específica com uma mensagem sobre o seu plano. A conexão em si não depende do plano, mas módulos individuais dependem: pedir a um agente que ative algo que o seu plano não inclui é recusado com o plano citado, em vez de gravar em silêncio uma linha que não muda nada.
Uma recusa que cita uma permissão. O token foi restringido quando foi criado, ou o dono dele não tem essa permissão. Lembre que o token age como o usuário que o criou e nunca pode fazer mais do que essa pessoa pode; então confira primeiro as permissões da pessoa e depois as do token. Qual escopo dar a um assistente de IA conduz uma diretoria na escolha desses limites.
Nada, em nenhuma ferramenta. Existe uma chave no nível da plataforma que desliga todo o endpoint do assistente. Se todas as ferramentas e todos os tokens ficam mudos de uma vez, essa é a causa mais provável, e cabe a nós verificar, não a você.
Mais um que não é uma falha, mas parece: a conexão tem limite de 120 requisições por minuto por token. Uma pessoa fazendo perguntas nunca chega perto disso; um script em loop chega.
Mantenha o token onde ele deve ficar
A única regra que vale imprimir: o token vai na configuração da ferramenta, nunca em uma conversa. Não o cole em uma mensagem de chat para o assistente, em uma mensagem de grupo da diretoria nem em um documento compartilhado. Um token é uma chave da sede do clube: ele age como um administrador identificado, e o registro de auditoria do clube grava tudo o que ele faz em nome dessa pessoa.
Há um limite que vale conhecer em vez de descobrir. Um token de conexão, como qualquer token de API, dispensa a etapa extra de autenticação em dois fatores do navegador: é uma chave que funciona sozinha, sem o segundo fator que se pede a uma pessoa quando ela entra no painel. É justamente por isso que a plataforma o faz expirar, o torna revogável com um clique e registra tudo o que ele faz no log de auditoria. Esses três controles substituem essa etapa extra, então trate-os como a salvaguarda, e não como burocracia.
Os padrões estão a seu favor. A validade padrão é de 90 dias, curta o bastante para que um token esquecido se aposente sozinho e longa o bastante para não incomodar. Revogar é um clique e vale em todo lugar de uma vez. E os limites estruturais da plataforma valem seja qual for a ferramenta conectada: toda alteração é simulada e mostrada a você como um plano antes de acontecer, e, das mais de 200 ferramentas da conexão, nenhuma envia e-mail ou SMS, recebe um pagamento ou faz um reembolso. Um assistente que você autorizou a publicar uma página ainda não consegue mandar e-mail a um único sócio.
Vale parar nisso, porque é a diferença entre uma política e uma garantia. Leia mais sobre como tratamos credenciais e acesso na nossa página de segurança e sobre o que a conexão expõe na página do recurso acesso para agentes de IA.
Perguntas frequentes
Quais ferramentas de IA conseguem de fato se conectar ao ClubHelix?
Qualquer ferramenta que permita definir um cabeçalho Authorization personalizado ou colar um token estático. O Claude Code é o caminho verificado e aquele para o qual o nosso painel imprime um comando. Editores de código e clientes de desktop que usam um arquivo de configuração JSON também funcionam, desde que o arquivo ou o painel de configurações dê um lugar para colocar um cabeçalho. Ferramentas que aceitam apenas uma URL e depois executam um fluxo de login não conseguem se conectar, porque não publicamos metadados de login para elas usarem.
Por que a minha ferramenta de IA insiste em pedir que eu faça login no ClubHelix?
Porque ela está tentando um fluxo de login em vez de ler o token que você deu. Nosso endpoint recusa uma requisição não autenticada com um 401 simples e não oferece metadados de login, então um cliente feito para iniciar um login nesse ponto vai pedir um código de autorização que nada aqui consegue emitir. Não é uma configuração errada que você possa corrigir: use um cliente que aceite um cabeçalho.
Posso colocar o token em um arquivo de configuração que a diretoria compartilha?
Pode, mas pense bem antes. Um arquivo de configuração compartilhado é copiado, compactado e às vezes enviado a um repositório, e o token que está nele é uma chave funcionando para o painel do seu clube, agindo como uma pessoa identificada. O melhor padrão é o que os próprios editores recomendam: usar uma variável de entrada, para que a ferramenta peça o token e o mantenha fora do arquivo. Se for mesmo compartilhar uma conexão, crie um token para essa finalidade, com validade curta e só as permissões de que ele precisa.
O que acontece com a conexão quando a nossa secretária deixa o cargo?
Ela para de funcionar, imediatamente e sem que ninguém precise lembrar de fazer nada. O token age como o usuário que o criou e a plataforma reverifica o papel dessa pessoa a cada requisição, então, no momento em que ela perde o papel de administradora, a conexão está morta. Crie um novo token em nome do dirigente que assume. É também por isso que a trilha de auditoria é legível: cada ação do assistente fica registrada em nome da pessoa real a quem o token pertencia.
Preciso ser desenvolvedor para configurar isso?
Para o Claude Code, não: você copia uma linha da página de administração, cola o seu token nela e executa. Para o caminho do arquivo JSON, é preciso se sentir à vontade para editar um pequeno arquivo de texto, o que é um obstáculo menor do que parece. O caminho da API da OpenAI é para quem está construindo algo, e, se esse não é o seu caso, você não precisa dele.
