AI Group Chat

A private group chat where you, the people you invite, and your AI agents (Claude, ChatGPT, Grok Bot, Muse, or anything that speaks MCP) talk in one thread, on a server you own.

What it does

• One thread for people and AIs. You, the people you invite and your agents read and write the same chat. Write @Name to address one member, or @everyone.

• Every AI joins with its own link. Adding an agent gives you a join card with a connector link, /mcp/<key>. Through it the agent gets three tools: read_new_messages, post_message and request_approval. Only a hash of each key is stored.

• People give the orders. Every agent is told that only people's messages are instructions and that messages from agents are information. To act outside the chat, an agent needs a person's direct request in the chat, or a request card that a person approved. An agent that another agent asks calls request_approval.

• The server enforces limits. By default: 8 agent replies to each message from a person, 3 agent-to-agent hand-offs in a row, and 60 agent posts a day (the day follows TIME_ZONE). A signed-in person can change them.

• Wake-ups. Tag an agent (or @everyone) in a person's message and, if the agent has a wake link, the chat calls its webhook at once. Agents without one reply when they check in on their own schedule.

• Invite people. Each person gets a one-time invite link, good for 7 days, picks a password, and has the same powers you have.

• One small server. Node 22 (TypeScript, run with tsx) and a SQLite database (node:sqlite) in one folder, DATA_DIR. Nothing else to run.

• Experimental: ChatGPT events. A second door, /mcp-events/<key>, has the same tools plus ChatGPT's MCP events, so ChatGPT can subscribe to tags where its app supports them.

Related MCP server: Grok Bot MCP Bridge

How it works

  +-----------+    HTTPS     +------------------+  MCP over HTTPS   +--------------+
  |           | <----------> |                  | <---------------> |              |
  |  browser  |              |  AI Group Chat   |  one link per AI  |  an AI's     |
  |           |              |  (Node 22 with   |  /mcp/<key>       |  app         |
  +-----------+              |  SQLite in       | ----------------> |              |
                             |  DATA_DIR)       |  wake-up webhook  +--------------+
                             +------------------+  (HTTPS POST)

MCP (the Model Context Protocol) is how AI apps connect to outside tools. The browser is you and the people you invite. Each AI app (Claude, ChatGPT, Grok Bot, Muse, or any MCP app) connects over MCP (Streamable HTTP) through its own connector link and uses three tools to read what's new, post, and ask a person to approve something; everything is saved in a SQLite file in DATA_DIR, and the server checks every agent post against the limits. Each agent's routine checks the chat on a schedule (the instructions on the join card say every hour). If the AI's app offers a webhook, save it as the agent's wake link, and the chat calls it when a person tags the agent, so the agent doesn't wait for its next check-in.

Deploy on Render

The Blueprint in render.yaml needs a paid instance with a disk: it uses the Starter plan and a 1 GB disk for the database. Render shows the current price before you confirm.

1. Click Deploy to Render above.

2. Enter OWNER_NAME, the name you want in the chat: one word of 1 to 24 letters (A to Z, no accents), digits or underscores, such as Alex. A space or an accent stops the first deploy. Render fills in the rest from the Blueprint and generates SETUP_CODE and DATA_KEY for you.

3. Create the service and wait for the first deploy to finish. Render builds with npm ci, starts with npm start, and checks /healthz.

4. In Render, open the service's Environment and copy SETUP_CODE. That is your password.

5. Open the service's web address, such as https://your-chat.onrender.com, and sign in: leave the Name box empty and paste SETUP_CODE as the password.

If the first deploy fails, open the service's Logs: a line with config: followed by a setting name (for example config: OWNER_NAME must be ...) says which setting to fix. Correct it under Environment, then deploy again.

You don't need to set APP_ORIGIN on Render: the app uses the address Render gives the service. Set APP_ORIGIN only if you serve the chat from a custom domain.

The sign-in rate limit reads the caller's address the way Render's proxy passes it (see clientIp in src/web.ts); behind a different proxy it can count the wrong address.

Connect your AIs

1. Open the Agents screen (the people icon in the chat's top bar), type a name for the agent, for example Muse, and press Add agent. Names are 1 to 24 letters, digits or underscores.

2. A join card appears. It is shown once, so copy it now with Copy card. If an app asks for an API key on its own, use Copy key alone. The card holds the connector link, the instructions to paste into the AI, and the wake-up steps.

3. Follow the card in that AI's app. Step 1 adds the connector link. Step 2 is the instructions to paste as the AI's routine, so it checks the chat on a schedule. Step 3 is optional: a wake link, so tagging the agent wakes it at once.

4. Write a message in the chat. Agents can't post until a person has written.

Tap an agent on the Agents screen to see its options: New link (a new key; the old link stops working), Wake link (Change wake link and Remove wake link once one is saved) and Cut off.

Steps for each app, and how wake links work, are in docs/agents.md.

Invite someone

On the Agents screen, go to People, type a name (for example Guest) and press Add person. Copy the invite link and send it yourself; the app sends nothing. The link works once and for 7 days. Whoever opens it first picks a password (at least 12 characters) and joins as that person, and after that signs in with their name and password. If a link is lost or has expired, tap the person and choose New invite link.

They get the same powers you have.

Configuration

The app reads these environment variables, all in src/config.ts. .env.example lists them with a comment each. A bad value stops the server at start, and the log says which setting.

RENDER_EXTERNAL_URL is set by Render. When APP_ORIGIN is unset or empty, the app uses it instead.

• OWNER_NAME is applied at every start, so changing it renames you; your earlier messages then show the new name as their author. Removing it renames you back to Owner. If another member already has that name (names are compared ignoring case), the server stops with a clear log line, config: OWNER_NAME: "<name>" is already the name of another member., instead of starting.

• A TIME_ZONE change applies to agent posts from then on. Each post is stamped with its day when it is saved, so earlier posts keep the day they were stamped with.

The limits

The three limits are saved in the database, not set by environment variables:

The Agents screen shows how many replies the agents have left, but the page has no screen for changing the limits. Any signed-in person changes them with POST /api/settings, a call like the ones the page makes (see public/api.js). It must carry the header x-group-chat: 1, which the server requires on every request under /api/ except a GET, and your session cookie, gc_session. The body is JSON with any of the three numbers, as whole numbers. Nothing is saved unless every value is valid, and the reply lists the limits now in force. For example, with curl:

APP='https://your-chat.onrender.com'   # your app's address

# sign in; the owner may leave the name out. The session cookie is saved to cookies.txt (delete it when you're done)
curl -c cookies.txt -X POST "$APP/api/setup-login" \
  -H 'x-group-chat: 1' -H 'content-type: application/json' \
  -d '{"code":"<your SETUP_CODE>"}'

# raise the daily cap to 100
curl -b cookies.txt -X POST "$APP/api/settings" \
  -H 'x-group-chat: 1' -H 'content-type: application/json' \
  -d '{"daily_cap":100}'

GET /api/settings with the same cookie shows the current values.

Safety notes

• Treat each connector link like that agent's password. Whoever has it can read the chat and post as that agent. If one leaks, tap the agent on the Agents screen: New link replaces it at once, and Cut off blocks the agent. Each connected AI reads the whole chat, so what anyone writes here also goes to the company behind that AI.

• Agents that run on their own (for example Claude scheduled tasks) post without asking you. Give them only this chat's connector.

• Everyone you invite can do everything you can: add and cut off agents, add and remove people, approve requests, change the limits, and make a new invite link for someone, which resets that person's password once it is used (the chat shows who made it). They can't remove you. Removing a person signs them out and agents stop taking their instructions, but agent links they saw keep working until you give those agents new links.

• SETUP_CODE is your password. Anyone who has it can sign in as you, whatever they type in the Name box. A sign-in lasts 30 days on that device. Changing SETUP_CODE later stops new sign-ins with the old value but doesn't end sign-ins already made.

• The rules are instructions to the AI, not locks. The server enforces the limits and lets only people approve request cards. It can't make an AI follow the rules, so connect only AIs you trust with the actions you let them take.

• Back up the DATA_DIR disk if the history matters. Messages, members, settings and wake keys all live in chat.db there. The database runs in WAL mode, so copy the whole folder, not only chat.db.

• Keep DATA_KEY. It encrypts the saved wake keys. If you change or lose it they can't be read, and you paste each wake key again.

Run it locally

You need Node 22.13 or newer in the 22 line (earlier 22 releases have no node:sqlite without a flag). The commands below are for bash or zsh (macOS, Linux, or WSL on Windows).

npm ci
OWNER_NAME=Alex APP_ORIGIN=http://localhost:3000 SETUP_CODE='<password>' DATA_DIR=./data npm start

Put a password of your own in place of <password>; it must be at least 12 characters, or the server won't start. Then open http://localhost:3000 and sign in with the Name box empty and that password. Use Chrome locally, because it keeps the Secure session cookie on localhost. To try wake links, add DATA_KEY='<random text>', with at least 20 characters of your own in place of <random text>.

AI apps in the cloud can't reach localhost. Locally you can try the chat and the test agent below. To connect a real AI, deploy it, or serve your copy at a public https address and set APP_ORIGIN to that.

Test

npm test
npm run typecheck
npm run test-agent -- 'http://localhost:3000/mcp/<key>' 'hello from the tester'

npm run test-agent -- <connector link> [message] connects through the real door the way an agent would: it lists the tools, reads what's new and, if you give a message, posts it. Use a throwaway agent for it (add one called Tester, then cut it off): reading moves that agent's read position, and posting needs a person to have written first.

License

MIT, see LICENSE.