From 616d7580a25b0d5a47f1e5cfa3a34202036e432d Mon Sep 17 00:00:00 2001 From: Robert Helewka Date: Sun, 26 Jul 2026 19:34:00 -0400 Subject: [PATCH] docs(hecate): note the OAuth-DCR startup hang and trailing slash MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Verified against the live Virgo dev instance while testing Sophia: with no bearer token, Hecate answers 401, fast-agent reads that as an auth challenge and falls back to OAuth dynamic client registration, then blocks waiting for a browser callback on 127.0.0.1:3030 that never arrives on a headless host. The agent never finishes starting — so a missing PAT is a startup failure, not a per-tool one. Same trap as the Daedalus MCP server. Also noted that /mcp answers 307 to /mcp/, so the trailing slash avoids a redirect on every call. Co-Authored-By: Claude Opus 5 (1M context) --- docs/tools/hecate.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/tools/hecate.md b/docs/tools/hecate.md index 3282ab6..b4d729b 100644 --- a/docs/tools/hecate.md +++ b/docs/tools/hecate.md @@ -131,4 +131,6 @@ External non-agent clients (the Theia kiosk, a scheduled wallboard prompt) conne - **`room=""` is the whole house.** Easy to trigger accidentally by omitting the argument. - **Timers survive restarts; cron occurrences do not.** Past-due timers fire on startup; a 7 AM schedule missed during an outage is *not* replayed at 2 PM. Deliberate. - **Auth is owner-only.** The `/mcp` mount sits behind an ASGI guard — a valid non-owner credential gets **403**, not 401. Agents authenticate with an owner-scoped PAT (`hecate_pat_…`) as a static bearer header; Pallas does not forward inbound auth downstream. +- **A missing PAT hangs agent startup — it does not just fail the tool.** With no bearer, Hecate answers 401; fast-agent reads that as an auth challenge and falls back to OAuth dynamic client registration, then blocks waiting for a browser callback on `127.0.0.1:3030`. On a headless host that callback never arrives and the agent never finishes starting. Verified 2026-07-26. The static bearer is the fix — this is the same trap as the Daedalus MCP server. +- **Use the trailing slash** (`/mcp/`). `/mcp` answers 307 to `/mcp/`, so omitting it adds a redirect to every call. - **The server sends its own instructions.** Hecate's FastMCP server ships `_SERVER_INSTRUCTIONS` describing room/device resolution to every client automatically. Don't duplicate that guidance verbatim in an agent prompt — add only what it doesn't say.