Connecting an AI assistant

Connect an AI assistant to ClubHelix and you can run your organisation from a chat on your own computer: ask how many members are due to renew, draft this week's news, or tidy up a page. You use your own Claude or ChatGPT plan, and the assistant can only see and do what you can.

If you have not connected one yet, your admin dashboard shows a Manage your club from Claude or ChatGPT card that links here. Close it with the × and it stays closed for you at this organisation.

This page walks you through it from start to finish. It also explains the one rule that tells you in advance whether a particular tool will work at all.

The rule that decides everything

ClubHelix authenticates an AI connection with a token you paste in, sent as an Authorization header. We deliberately do not run a sign-in flow for AI connections.

So, before you start:

• If the tool lets you set a custom header, or paste a token, it will connect. Claude Code, editor clients that use a JSON config file, and anything calling us from code all fall in this group.
• If the tool only asks for a web address and then tries to sign you in, it will not connect. It will send you round a sign-in loop, or ask for an "authorisation code" — there is nothing to issue one. That is not a fault at your end and no setting on your side fixes it; it is simply the wrong kind of connection for this endpoint.

When you are looking at an unfamiliar settings screen, that is the thing to hunt for: somewhere to put a token or a header.

In practice that means:

Who can use this

A full admin of the organisation, on any plan — including Free. The token acts as the person who created it, so it can never see or do more than they can, and it stops working the moment they stop being an admin here.

One thing it can never do, whatever the plan and whatever you tick: change your subscription. Plans, billing and payment settings are platform-staff territory, out of reach of any organisation's token.

What you need first

1. The token. Created on the API & webhooks page. It starts with chmx_ and is shown exactly once, so copy it before you leave the screen. Lost it? Revoke it and make another.
2. The address. https://clubhelix.com/api/mcp
3. Somewhere safe to keep it. The token goes in your tool's configuration or a password manager. Never paste it into a chat message — that puts a working key into a conversation transcript.

Step by step

The walkthrough, start to finish

Set aside about ten minutes. You need to be an admin here, and you need a computer where you can install an app.

1. Pick your tool. If you pay for Claude, use Claude Code or Claude Desktop. If you pay for ChatGPT, use Codex. The table above explains why.
2. Install it and sign in with your Claude or ChatGPT account. Each vendor's install page walks you through this, and you only do it once.
3. Create a token here. In the admin, open API & webhooks (the dashboard card's Create a token link goes straight there). Under AI assistant access (MCP):
   • Give the token a name that says where it will live, such as Claude on the secretary's laptop.
   • Leave Expires at 90 days.
   • Tick Allow changes if you want the assistant to create and edit pages, news and events. Leave it unticked to start read-only.
   • Leave Allow publishing unticked for now. The assistant can then prepare work, and a person still presses publish.
   • Press Create token.
4. Copy the token straight away. It starts with chmx_ and is shown only once. Keep it in a password manager, never in a chat.
5. Add ClubHelix to your tool by following the section for your tool below.
6. Check it worked. Ask "Who are you connected as, and what can you see?" (see Check it worked).
7. Try a real job, such as "Summarise our membership" or "Draft a news post about Saturday's working bee". With Allow changes ticked, drafts appear in the admin for you to review.

Once you have an active token, the dashboard card stops showing.

Claude Code (with a Claude plan)

This is the path we test against, and the admin page prints the exact line for you under Connect Claude Code. It is one command:

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

Replace YOUR_TOKEN with the token you copied. -t is short for --transport and -H for --header if you prefer.

Add --scope to choose where the connection is saved:

• --scope local (the default) — just for you, in the folder you are working in.
• --scope user — available everywhere you work.
• --scope project — saved in the project itself and shared with anyone who has it. Do not use this one with a token pasted in, or you have committed a key.

Because you have set a header, Claude Code will not try to sign you in, which is exactly what we want.

Codex (with a ChatGPT plan)

Codex is OpenAI's coding assistant. It runs in the terminal, in an editor extension and in the Codex app, and you sign in to it with your ChatGPT account. All three read the same configuration file, so you set this up once.

1. Put the token in an environment variable rather than in the file. On a Mac or Linux, add this line to your shell profile (~/.zshrc or ~/.bashrc), then open a new terminal:

   export CLUBHELIX_MCP_TOKEN="YOUR_TOKEN"
   

   On Windows, add a user environment variable named CLUBHELIX_MCP_TOKEN in System Properties → Environment Variables, then restart Codex.

2. Add ClubHelix to ~/.codex/config.toml (create the file if it does not exist):

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

   Codex reads the variable and sends it as Authorization: Bearer … for you, so the token never sits in the file.

3. Restart Codex, then ask it the check question below.

This is Codex, not the chat window at chatgpt.com. The chat app's connectors screen only offers sign-in, so it cannot connect.

Claude Desktop

Claude Desktop's Connectors screen only offers sign-in, so instead you add ClubHelix to its configuration file through a small bridge called mcp-remote. The bridge needs Node.js installed.

1. In Claude Desktop open Settings → Developer → Edit Config. This opens claude_desktop_config.json.

2. Add a clubhelix entry (keep any entries that are already there):

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

   There is deliberately no space after Authorization:. Some systems split the argument at a space, and the token then arrives broken.

3. Quit Claude Desktop completely and reopen it. It reads the file only at startup. ClubHelix then appears in the tools list of a new chat.

The token is stored in plain text in that file, so only do this on a computer that is yours.

A client that uses a JSON configuration file

Editor-based tools generally keep MCP connections in a small JSON file. The shape is the same idea everywhere — a name, the address, and a headers block:

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

The exact key names differ a little between tools, so check your tool's own documentation rather than assuming. Two things are worth doing whatever the tool:

• Keep the token out of the file if the file is shared. Most of these tools support a prompt or variable for secrets. Editors that share a config through source control warn about this for good reason — a token in a committed file is a token you have given away.
• Restart the tool after editing the file. Most only read it at startup.

Calling us from your own code

If you are building something rather than configuring an app, the connection is a tool definition: a type of mcp, a label, our address, and the token as the authorisation value. In the major API this looks like server_url plus authorization. Note that this field is documented by its vendor as an OAuth access token; it is the field that carries the bearer value, which is what ours is.

Any other tool, including chat apps with a connectors screen

These screens change often, so we deliberately do not print a click-by-click walkthrough that would be out of date within weeks. Instead, apply the rule at the top:

1. Look for a field for a token, an API key, or a custom header. If there is one, paste the token there (as Bearer YOUR_TOKEN if it is asking for a whole header value).
2. If the only option is to enter a web address and sign in, this tool cannot connect to ClubHelix today.
3. Check your tool's current documentation for which of those it offers — the vendor's own page is always fresher than ours.

Check it worked

Ask the assistant:

Who are you connected as, and what can you see?

A working connection names your organisation, the admin who owns the token, and the scopes it carries. Then try something real: "Summarise our membership."

When it does not work

Field reference

Tips & FAQ

Can I use the same token on my laptop and my phone? You can, but it is better not to. Make one token per place it lives and name it accordingly, so revoking the one on a lost laptop does not cut off everything else.

What should the expiry be? Ninety days is the default and a sensible habit — it forces a short review rather than leaving a key alive forever. "Never" is available, and is the right answer far less often than it looks.

Can I change what a token may do after making it? No. Scopes and limits are fixed when the token is created. Make a new token with the settings you want, switch your tool over, then revoke the old one.

I pasted the token into a chat by accident. What now? Revoke it on the API & webhooks page and create a new one. Revoking takes effect immediately, everywhere.

Does connecting an assistant let it email our members? No. Nothing on this connection can send an email or a text message, take a payment or issue a refund — whatever you tick. An assistant can draft a broadcast; a person chooses the audience and presses send.

Can I use the ChatGPT or claude.ai website instead of an app on my computer? Not today. Their connector screens only offer a sign-in flow, and ClubHelix connects with a token. Use Codex with your ChatGPT plan, or Claude Code or Claude Desktop with your Claude plan.

The dashboard card came back. It shows while you have no active token here. If your token expired or was revoked, create a new one and the card goes away again. If you closed the card with ×, it stays closed even with no token.

A co-admin connected. Why do I still see the card? A token acts as the person who created it, so each admin connects with their own.

Which tools do you actually test? Claude, including Claude Code. Anything else that speaks the same open standard and lets you set a header should work, but we cannot promise a specific app's settings screen behaves as its vendor describes.