ai-brain-user — participant client (MCP)

A stdio MCP server you connect to your CLI agent (Claude Code, Codex, Google Antigravity, or any MCP-capable agent) so it can work inside your team's shared offensive-intelligence workspace — recon notes, findings, and an autonomous solver, all coordinated on the server and executed on your machine.

Follow the steps in order. By the end your agent has the ctf_* workspace tools plus consult_brain and ctf_agent.

1. What you need

Three things, on the machine you'll run tools from (for example, your Kali box):

Node.js 20 or newer, and git. Check with node -v. Node 22.5+ additionally turns on the offline note queue + presence heartbeat (they use Node's built-in node:sqlite); on Node 20 everything else works.
- Using nvm? Agents launch the MCP with the PATH they were started with — often the system Node (v20), not your nvm shell's. Run nvm alias default 22 (or point the MCP command at an absolute node path) so the agent uses the Node you expect.
An account on this workspace. Ask your team admin to add you (they open Team → Add member); they'll give you your email and a one-time temporary password.
OpenRouter + Jina API keys (free tiers are fine): three OpenRouter keys from openrouter.ai and one Jina key from jina.ai. Research and reasoning run on your quota, so you provide your own.

Open your team's dashboard (e.g. https://mcp.sansec.uz) and sign in with your email and the temporary password from your admin. The dashboard is where you do steps 3 and 4.

3. Add your provider keys

On Settings → Connect keys, add one OpenRouter key for each task tier — high priority (deep reasoning), medium / low (chat + memory), and images (vision) — plus one Jina key (web research).

This is required: until all four keys are in, your API key won't issue and the AI tools stay locked. Add more keys to a tier for extra rate-limit failover. (You can also do this from the terminal after step 5: node dist/cli.js keys.)

4. Generate your API key

On Settings → Connect API keys, click Generate and copy the key — it's shown once. It already carries your workspace, so you never set BRAIN_CTF.

Your key locks to the first computer that uses it (it binds to a device id stored in BRAIN_STATE_DIR). A copied token won't work from another machine — to move it, revoke the key and generate a new one there. This makes a leaked token useless elsewhere and lets the backend tie every request to one user on one device.

5. Get the client

On your machine, clone the repo and install dependencies. The MCP runs from the prebuilt dist/cli.js bundle — plain node, no tsx, fast cold start.

git clone https://github.com/sanjarbiy/ai-brain-user
cd ai-brain-user
npm install

(To rebuild the bundle after editing the source: npm run build.)

6. Connect the MCP to your agent

Run the command for your agent from inside the cloned ai-brain-user folder, so $(pwd) becomes the absolute path on its own (no hand-editing) and $(openssl rand -hex 32) generates a local encryption key. Replace only the server URL and mcp_your_generated_key (from step 4).

BRAIN_STATE_DIR is any writable path (~ and $HOME are both accepted). BRAIN_VAULT_KEY is optional — it encrypts local session/offline storage only.

Claude Code

cd ai-brain-user
claude mcp add mcp-console -s user \
  --env BRAIN_SERVER=https://your-team-server.example \
  --env BRAIN_TOKEN=mcp_your_generated_key \
  --env BRAIN_STATE_DIR=$HOME/.mcp-console \
  --env BRAIN_VAULT_KEY=$(openssl rand -hex 32) \
  -- node "$(pwd)/dist/cli.js" mcp

-s user registers it for your whole account. Without it, claude mcp add defaults to local (project) scope — the server binds to the current directory and vanishes when you open Claude Code elsewhere. Restart Claude Code.

Codex CLI

cd ai-brain-user
codex mcp add mcp-console \
  --env BRAIN_SERVER=https://your-team-server.example \
  --env BRAIN_TOKEN=mcp_your_generated_key \
  --env BRAIN_STATE_DIR=$HOME/.mcp-console \
  --env BRAIN_VAULT_KEY=$(openssl rand -hex 32) \
  -- node "$(pwd)/dist/cli.js" mcp

Or edit ~/.codex/config.toml (Windows: C:\Users\you\.codex\config.toml) — use a real absolute path to dist/cli.js:

[mcp_servers.mcp-console]
command = "node"
args = ["/absolute/path/ai-brain-user/dist/cli.js", "mcp"]

[mcp_servers.mcp-console.env]
BRAIN_SERVER = "https://your-team-server.example"
BRAIN_TOKEN = "mcp_your_generated_key"
BRAIN_STATE_DIR = "/home/you/.mcp-console"
BRAIN_VAULT_KEY = "<64-hex>"

The prebuilt bundle starts instantly, so the old startup_timeout_sec = 60 workaround is no longer needed. Restart Codex.

Google Antigravity ("agy")

Edit ~/.gemini/config/mcp_config.json (Windows: C:\Users\you\.gemini\config\mcp_config.json) — or in the IDE open … → MCP Servers → View raw config, or in the CLI type /mcp. This is static JSON (no shell expansion), so use a real absolute path (run pwd in the repo) and a real 64-hex BRAIN_VAULT_KEY:

{
  "mcpServers": {
    "mcp-console": {
      "command": "node",
      "args": ["/absolute/path/ai-brain-user/dist/cli.js", "mcp"],
      "env": {
        "BRAIN_SERVER": "https://your-team-server.example",
        "BRAIN_TOKEN": "mcp_your_generated_key",
        "BRAIN_STATE_DIR": "/home/you/.mcp-console",
        "BRAIN_VAULT_KEY": "<64-hex>"
      }
    }
  }
}

On Windows use forward slashes in the path. Save, then reload from the Manage MCP Servers panel (IDE) or /mcp (CLI).

hackerai

hackerai does not connect external MCP servers — it runs its own built-in tools in a sandbox. Use this client as a shell command in its terminal instead (see node dist/cli.js help), or add it as a native tool by patching the hackerai source (advanced).

7. Verify & troubleshoot

Restart your agent so it loads the server, then:

claude mcp list           # look for: mcp-console … ✔ Connected
node dist/cli.js doctor   # api, identity, workspace — all green

A tool returns 424 "add your key" → finish step 3 (you're missing a tier or the Jina key).
Your agent says "failed to connect" but node dist/cli.js doctor works in your terminal → the agent launched a different Node. Set nvm alias default 22, or use an absolute node path in the MCP command.
localStateSupported: false in doctor → you're on Node < 22.5; the MCP still works, only the offline queue/presence are off.

Safety

ctf_agent runs commands as local shell on your machine (guarded only against host-destructive commands like rm -rf /). Enable it only on a host where you accept local command execution. The client logs to stderr, not stdout — stdio MCP multiplexes JSON-RPC over stdout.

From source (development)

node --import tsx client/src/cli.ts help    # run the TypeScript directly with tsx (no build)
npm run build                               # regenerate dist/cli.js after editing client/src