cware-hil-mcp

Human-in-the-loop MCP hub for Claude Code agents, answered in Obsidian.

Agents call MCP tools to ask a human a question, request approval, or report status. This standalone hub holds the queue and exposes an MCP endpoint; the Obsidian plugin is the human's UI.

Claude Code agents ──HTTP /mcp──▶  hub (Node, :22360)  ◀──ws /bridge──  Obsidian plugin
                                   └ SQLite queue (survives restarts)

Shared domain types + the bridge protocol live in cware-hil-lib (a git dependency).

Build

npm install
npm run build

Requires Node ≥ 22 (developed on Node 26; the hub uses the built-in node:sqlite, so there is no native build step).

Related MCP server: Obsidian Claude Code MCP Server

Run

node dist/cli.js start            # or: cc-hitl start  (once linked/installed)
node dist/cli.js status           # health check
node dist/cli.js stop
node dist/cli.js token            # print the bearer token

State lives in ~/.cc-hitl/ (hub.json holds the token; hub.db is the queue). The hub binds to 127.0.0.1 by default; override with --host <addr> or CC_HITL_HOST (e.g. 0.0.0.0 to accept connections from other machines).

There's a browser setup page at http://<host>:<port>/setup that builds the connection snippets for you (paste your token — it never leaves the browser).

Docker

export CC_HITL_TOKEN=$(openssl rand -hex 24)
docker compose up -d --build
docker compose exec hub node dist/cli.js status

The container binds 0.0.0.0 and compose publishes it on 127.0.0.1:22360. State persists in the hub-data volume (CC_HITL_HOME=/data). Without compose:

docker build -t cware-hil-mcp .
docker run -d --name cc-hitl -p 127.0.0.1:22360:22360 \
  -e CC_HITL_TOKEN=$CC_HITL_TOKEN -v cc-hitl-data:/data cware-hil-mcp

Exposing beyond loopback: once published on a LAN/public interface, the bearer token is the only thing protecting /mcp and /bridge. Use a strong CC_HITL_TOKEN and put a TLS reverse proxy in front.

Connect Claude Code

cc-hitl start prints the exact command (or use the /setup page). In your project:

claude mcp add --transport http --scope project hitl http://127.0.0.1:22360/mcp \
  --header "Authorization: Bearer <token>"

Set a long per-server timeout (the printed snippet uses 24h) because the ask tools block until a human answers.

Tools agents get

• ask_user(prompt, title?, agent_label?) — open question, returns typed text. Blocks.

• ask_choice(prompt, choices[], multi?, …) — pick one/several (+ optional note). Blocks.

• request_approval(title, body, diff?) — approve/reject + comment. Blocks.

• notify(message, level?) — fire-and-forget notice. Non-blocking.

• update_status(label?, status?, current_task?, progress?, done?) — dashboard feed. Non-blocking.

Test

npm test        # builds, then runs the integration + resilience suites

These spawn a real hub on a temp CC_HITL_HOME and drive each tool through an MCP client + bridge WebSocket client.