r/koios
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs(hecate): note the OAuth-DCR startup hang and trailing slash

Browse Source 
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) <noreply@anthropic.com>
This commit is contained in:
Robert Helewka
2026-07-26 19:34:00 -04:00
parent db59266527
commit 616d7580a2
1 changed files with 2 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/tools/hecate.md
View File

@@ -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. - **`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. - **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. - **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. - **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.