feat(mcp): opt-in HTTP (streamable) transport so clients auto-reconnect (#440)

[CheeryProgrammer]

Closes #440.

Problem

MCP is stdio-only; the documented deploy runs docker compose exec app /brainiac-mcp — a subprocess inside the app container. Every docker compose up -d / brainiac update recreates the container, killing that subprocess in every connected client. MCP clients do not auto-restart stdio servers (they do auto-reconnect HTTP/SSE ones), so every routine update forced a manual reconnect in every session.

Change

Serve the same tool surface over streamable HTTP at POST/GET /mcp on the app's existing chi router (mcp.NewStreamableHTTPHandler wrapping mcpserver.New). Clients register it as an HTTP transport and reconnect automatically across restarts.

• Opt-in: HTTP.mcp config / MCP_HTTP env (+ compose passthrough). Off by default; stdio stays the default transport — no behaviour change unless enabled.
• Token-gated: reuses bearerAuth(AUTH_TOKEN) — the endpoint exposes write tools and the app binds 127.0.0.1.
• Fail-closed config: MCP_HTTP requires AUTH_TOKEN, and is Layer-1 only — rejected when hard-isolation principals are configured, since a single-principal HTTP surface would bypass the per-request isolation /api enforces (Layer 2 (future): hard visibility isolation for teams (read-scope + security) #120/Layer 2 foundation: per-token principal + enforced read-wall + write-pin (#120) #185).
• v1 scope: ingest tool omitted over HTTP (nil importFn; stdio MCP + CLI keep it).

Verification (live, built from source)

$ curl -s -o /dev/null -w '%{http_code}' -XPOST localhost:8088/mcp -d '<initialize>'      # 401  (no token)
$ curl -s -XPOST localhost:8088/mcp -H 'Authorization: Bearer <token>' -d '<initialize>'   # {"serverInfo":{"name":"brainiac",...}}

Startup logs MCP over HTTP ON: …. Unit tests: /mcp bearer gate (401 without/with bad token; initialize returns serverInfo with a valid token), not-mounted-by-default, and config fail-closed guards. Full suite green (config/server/mcpserver/core/store).

Register it

claude mcp add --transport http brainiac http://localhost:8088/mcp \
  --header "Authorization: Bearer $AUTH_TOKEN"

→ survives brainiac update with no manual /mcp.

Follow-ups (in #440, out of scope here)

• Per-connection principal resolved from the bearer token (hard-isolation over HTTP).
• ingest tool parity over HTTP MCP.

---

🤖 Generated with Claude Code