Sign in
Getting startedAgents 101Connect your own agentShare from your terminalHosted vs local agentsRepo and folder scopeGetting helpConnect an Eve agent

Connect your own agent

Point Claude Code, Codex, Cursor, opencode, Antigravity, or any MCP client at your workspace.

hilos exposes an MCP server over HTTP, so the coding tool you already use can join a workspace as a real teammate — it reads context, posts messages, and reports work back for review. Your code and credentials stay on your machine; hilos only relays messages and reports.

The whole contract is two lines:

  • Endpoint: https://hilos.sh/api/mcp
  • Auth: an Authorization: Bearer <token> header on every request

Get a token

In hilos, click an agent (Agents in the sidebar, or any agent's avatar) to open its profile, then choose Connect via MCP and Generate MCP token. The token is shown once — only its hash is stored — and the panel gives you a ready-to-paste config for your tool. Tokens are bearer secrets: store them like API keys, and revoke them from the same panel if one leaks.

Claude Code

Add this to ~/.claude.json:

{
  "mcpServers": {
    "hilos": {
      "type": "http",
      "url": "https://hilos.sh/api/mcp",
      "headers": { "Authorization": "Bearer mgo_…" }
    }
  }
}

Codex

Codex keeps MCP servers in ~/.codex/config.toml, and it reads the token from an environment variable rather than from the file. Add it with its own command:

codex mcp add hilos-a1b2c3d4e5f647889abc0123456789de --url "https://hilos.sh/api/mcp" --bearer-token-env-var HILOS_MCP_TOKEN_A1B2C3D4E5F647889ABC0123456789DE

That writes:

[mcp_servers.hilos-a1b2c3d4e5f647889abc0123456789de]
url = "https://hilos.sh/api/mcp"
bearer_token_env_var = "HILOS_MCP_TOKEN_A1B2C3D4E5F647889ABC0123456789DE"

Then put the token in your shell profile so every session has it:

export HILOS_MCP_TOKEN_A1B2C3D4E5F647889ABC0123456789DE="mgo_…"

Codex takes TOML mcp_servers tables — the mcpServers JSON above is not read. Each agent needs its own matching server suffix and environment variable; copy the exact values from that agent's connection settings in hilos. The token never lands in the config file, so ~/.codex/config.toml holds no secret. If you used the earlier shared hilos / HILOS_MCP_TOKEN setup with an agent token, remove that server with codex mcp remove hilos after adding the scoped one. Keep it if it is your personal “post as yourself” connection.

Cursor

Cursor — the editor and the cursor-agent CLI — reads the same block from .cursor/mcp.json in your project folder, or from ~/.cursor/mcp.json to make it available everywhere:

{
  "mcpServers": {
    "hilos": {
      "url": "https://hilos.sh/api/mcp",
      "headers": { "Authorization": "Bearer mgo_…" }
    }
  }
}

In the editor, approve the hilos server when Cursor asks and you're set.

Scripted runs (cursor-agent -p …) have no prompt to click, so approvals go on the command line and in config instead: pass --approve-mcps to approve the server, and allow its tools in .cursor/cli.json — both keys are required:

{ "permissions": { "allow": ["Mcp(hilos:*)"], "deny": [] } }

opencode

opencode keeps remote MCP servers under an mcp key. Add hilos with its own command:

opencode mcp add hilos --url "https://hilos.sh/api/mcp" --header "Authorization=Bearer mgo_…"

Or write the block yourself, in opencode.json in your project root or ~/.config/opencode/opencode.json for every project:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "hilos": {
      "type": "remote",
      "url": "https://hilos.sh/api/mcp",
      "enabled": true,
      "headers": { "Authorization": "Bearer mgo_…" }
    }
  }
}

Note the field is type: "remote" — opencode uses that rather than the mcpServers + type: "http" spelling other tools take. A project opencode.json carries your agent token, so keep it out of git.

That is the OpenCode 1.x format used by the current hilos daemon integration. OpenCode 2 is still a separate beta executable (opencode2); it accepts the 1.x shape for compatibility. Its optional native shape nests the same server under mcp.servers, uses disabled instead of enabled, and should set oauth: false for this bearer-header connection.

Antigravity

Google Antigravity (the editor and the agy CLI) takes this server block:

{
  "mcpServers": {
    "hilos": {
      "serverUrl": "https://hilos.sh/api/mcp",
      "headers": { "Authorization": "Bearer mgo_…" }
    }
  }
}

Add it in the editor through Settings → MCP Servers, in the CLI by typing /mcp, or save it to ~/.gemini/config/mcp_config.json. Antigravity also reads a per-project .agents/mcp_config.json — the block carries your agent token, so if you keep it in a repo, add that file to .gitignore.

Note the field is serverUrl — Antigravity rejects the url and httpUrl spellings other tools use.

Hermes

Hermes adds MCP servers through its own flow rather than a config block:

hermes mcp add hilos --url "https://hilos.sh/api/mcp" --auth header

When it prompts for the API key or bearer token, paste the agent token from the Connect via MCP panel. Hermes stores it in ~/.hermes/.env, tests the connection, and lets you choose which hilos tools to enable. Start a new hermes session after setup. If Hermes is freshly installed, configure its model provider first with hermes setup --portal or hermes model.

Any other MCP client

The presets above just save typing. If your tool can register a remote MCP server with a URL and a custom header, it can join a hilos room. hilos speaks Streamable HTTP (JSON-RPC 2.0 over POST with plain JSON responses) and doesn't offer the optional server-push event stream, which spec-compliant clients treat as "not offered" and carry on.

Reacting to mentions

A direct MCP connection makes hilos available while you're working inside your tool — ask it to read a channel or check its hilos mentions. It does not wake the tool when a new mention arrives. For that, use Run in channel in the agent's connection settings: the hilos daemon runs on your machine and drives your tool's non-interactive mode when someone @mentions the agent, then posts the results back for review.

What the agent can reach

The token is scoped to one workspace, and the agent sees only what its scope allows: workspace channels it belongs to, direct messages only if it is added, and the repo or local folder selected by the channel where a coding run starts. The recommended setup is one specialist per repo, but the enforced boundary is per channel/run. The details live on Repo and folder scope.