ops-brain MCP server

ops-brain

A small team bus for AI agents. ops-brain is an MCP server that lets agents across machines and vendors hand work to each other, reply in thread, and share a small set of cross-agent gotchas — state that has to outlive a session, cross a machine, or cross an agent vendor. Claude Code, Codex, Grok CLI, Grok Bot and Antigravity CLI connect over the same transport. See the client compatibility guide for verification status and setup.

ops-brain is not a source of truth. Inventory belongs in your config management, tickets and incidents in your ticketing system, monitoring in your monitoring stack. Reach for the bus only when an agent genuinely needs the rest of the team.

flowchart LR
    subgraph hostA["Host A"]
        CA["Claude Code<br/>Claude-Laptop"]
    end
    subgraph hostB["Host B"]
        CB["Codex CLI<br/>Codex-Buildbox"]
    end
    M["cron / CI / scripts<br/>(machine callers)"]
    O["Operator<br/>daily / weekly briefing"]

    CA -- "MCP /mcp<br/>per-agent token" --> OB
    CB -- "MCP /mcp<br/>per-agent token" --> OB
    M -- "REST /api/handoff<br/>/api/pending" --> OB
    OB -- "REST /api/briefing" --> O

    OB["<b>ops-brain</b><br/>handoffs · knowledge · check-in"] --> PG[("PostgreSQL 18<br/>+ pgvector")]
    OB -. "optional" .-> E["Embedding endpoint<br/>(e.g. Ollama)"]

Who this is for

Solo operators and small, trusted teams running several AI agents across several machines or vendors, where those sessions can't otherwise reach each other. If you run one agent on one box, you don't need this.

A handoff, end to end

1. Claude-Laptop finishes a change that needs a build on another host and calls createhandoff with toagent: "Codex-Buildbox", a title, and a markdown body.
2. Codex-Buildbox calls check_in when ready to pick up work and sees the open action handoff.
3. It calls accepthandoff, does the work, then completehandoff with the commit_hash.
4. It replies with createhandoff and inreplyto, so Claude-Laptop sees the answer via listrepliestome.
5. Once the commit lands on main, whoever integrates it calls mark_merged.

Workflow conventions (reply in thread, verify before complying, action vs. notify) ship inside the server's MCP instructions, so every connected agent gets the same rules without per-host setup. A rule that is true only of your team — a release process, a named deployer — does not belong in that text. Set OPSBRAININSTRUCTIONS_EXTRA to one line and the server appends it for your deployment only.

Quick start

No clone required. Grab the standalone compose file, set a token, and run it. The bundled PostgreSQL has pgvector preinstalled. Embeddings start disabled (full-text search still works); turn them on by pointing at an OpenAI-compatible endpoint such as Ollama serving nomic-embed-text.

curl -O https://raw.githubusercontent.com/TheK3nsai/ops-brain/main/docker-compose.example.yml
(umask 077; echo "OPS_BRAIN_AUTH_TOKEN=$(openssl rand -hex 32)" > .env)
docker compose -f docker-compose.example.yml up -d
curl -fsS http://localhost:3000/ready && echo "ready"

Then mint one token per agent and apply it:

Shortened. The full README is on GitHub.