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.