From 2f504247edf32291768dcc37090024e6b6c97090 Mon Sep 17 00:00:00 2001 From: iris Date: Thu, 2 Jul 2026 12:42:14 +0200 Subject: [PATCH] docs(turn-loop): document optional HTTP MCP transport (httpPort) When hyperhive.mcp.httpPort is set in agent.nix, the hive-mcp-http systemd daemon runs the embedded MCP server as a persistent streamable- HTTP service; claude-mcp-config.json points at the HTTP URL instead of spawning a stdio child per turn. Document both modes in the subcommand list and the on-boot files section. --- docs/turn-loop.md | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/docs/turn-loop.md b/docs/turn-loop.md index e221233b..06e8be61 100644 --- a/docs/turn-loop.md +++ b/docs/turn-loop.md @@ -66,8 +66,10 @@ Three subcommands: - `serve` — long-running harness loop (the inbox poll + claude-pump + ack/requeue cycle described above). -- `mcp` — stdio MCP server claude spawns via `--mcp-config` per - turn. Same binary, different mode. +- `mcp` — MCP server. Default: stdio child claude spawns via + `--mcp-config` per turn. With `--http `, runs as a persistent + streamable-HTTP daemon instead (used by the `hive-mcp-http` + systemd unit when `hyperhive.mcp.httpPort` is set). - `wake --from --body ` — push a message into our own inbox so the next turn fires with the given body. Used by co-process daemons (matrix bridge, scraper, webhook listeners) @@ -267,9 +269,13 @@ next turn picks it up like any other inbox message. `hive_ag3nt::turn::write_*` writes two files next to the per-agent socket at `/run/hive/` once at startup: -- `claude-mcp-config.json` — re-invokes the running binary as `mcp` - child (so the same binary serves as harness + as claude's MCP - child process). +- `claude-mcp-config.json` — by default re-invokes the running binary + as `mcp` stdio child (so the same binary serves as harness + MCP + server per turn). When `hyperhive.mcp.httpPort` is set in the + agent's NixOS config, the config instead points claude at the + persistent `hive-mcp-http` daemon (`http://127.0.0.1:{port}/mcp`) + — no stdio child per turn; trades the per-turn re-registration race + for a hard dependency on the daemon's uptime (`Restart=always`). - `claude-system-prompt.md` — rendered from `hive-ag3nt/prompts/system.md` by `hive_ag3nt::prompt::render`: HTML-comment markers (`...`,