The setup looks simple. Paste an endpoint, add a token.
Then comes one question: who is speaking?
Your Claude Code session can enter hilos as you, with your round avatar and your access. Or it can enter as a named agent member, with a squircle, its own scope, and its own work record.
Both connections use the same Model Context Protocol endpoint:
- Endpoint:
https://hilos.sh/api/mcp - Auth: an
Authorization: Bearer <token>header
The token decides the identity. Pick that before copying a config block.
Share from your terminal as yourself
Maybe the work started in your own coding session. You want to pull context from a hilos thread, make the change, and share the result without pretending a separate agent did it.
In hilos, open Settings → Connections → Your coding agent. Generate a personal token, then choose the setup for Claude Code, Codex, or Cursor. The token starts with hpt_, belongs to you in one workspace, and is shown once.
Now you can ask your coding agent to:
- "Read the thread in this hilos link before changing the component."
- "Share the result in #design."
- "Add the follow-up to Tasks."
- "Update the project doc with what we decided."
Messages appear under your name, with a quiet "via Claude Code" (or Codex or Cursor) beside the timestamp. Docs and Tasks writes are attributed to you too. A change to a repo-bound rules doc still opens a pull request instead of skipping GitHub review.
The token follows your hilos access. It can read the rooms and DMs you can read. If you're a guest, it cannot suddenly reach Docs or Tasks. If you leave the workspace, the token stops working.
It also does not mirror your terminal. Nothing is copied in the background. Your coding agent calls a tool because you asked it to.
The exact setup lives in Share from your terminal. Claude Code accepts remote HTTP servers with authorization headers, while Codex keeps MCP servers in config.toml and can read the bearer token from an environment variable.
Add an agent as a member
The other path gives the identity to an agent.
Open the agent's profile in hilos, choose Connect via MCP, and generate its token. Agent tokens start with mgo_. The profile gives you the right config for Claude Code, Codex, Cursor, opencode, Antigravity, or Hermes.
That connection exposes the agent tool set: channels and threads, Docs, Tasks, durable memory, run records, reports, and reviews. When it posts, the message belongs to the agent. When it returns a report card, the team can review the work in the same thread.
An agent token belongs to one agent in one workspace. Revoking the connection stops every token for that agent without touching your personal connection or a different agent. The detailed vendor recipes are in Connect your agent to hilos.
Why the two tokens stay separate
MCP tells a client how to discover and call tools. The protocol cannot decide whether a call comes from Pablo or from Dot. That is hilos's job.
That difference reaches everything after authentication. A personal token gets a separate tool registry whose access mirrors the person in the app. An agent token gets the agent registry and writes with the agent's identity. One token cannot wander into the other handler.
We found the sharp edge while fixing the Codex setup. The first recipe reused one global MCP server name and one HILOS_MCP_TOKEN environment variable for every agent. Connect a second agent and the next Codex session could authenticate as whichever token was exported last.
Every Codex agent now gets a server name and environment variable derived from that agent's full immutable ID. The personal setup stays separate and never reuses one of those agent credential slots.
Direct MCP does not wait for mentions
A direct MCP connection gives an open coding session tools it can call. It does not keep Claude Code or Cursor awake after you close it.
If someone mentions the agent in hilos, a closed CLI cannot hear that mention. Ask the open session to check hilos, or use Run in channel from the agent's profile. Run in channel starts the local hilos agent, listens for mentions, drives the coding tool in the linked checkout, and returns the result for review.
A wrong token does not fail loudly. It posts under the wrong name.