Troubleshooting and smoke¶
Live hub: https://conductor-konstant.hectorsanchez.eu/connect.md
Bootstrap: https://conductor-konstant.hectorsanchez.eu/connect/bootstrap.md
Offline: docs/guides/connect/troubleshooting.md
Agents: relative links like ../connecting.md 401 on the live host — use
absolute /connect/... URLs only.
Smoke¶
Downloadable script (preferred — no repo clone)¶
Requires CONDUCTOR_MCP_AUTH_TOKEN already exported (length-checked):
curl -fsS https://conductor-konstant.hectorsanchez.eu/connect/mcp-smoke.sh | bash
From a cloned repo: ./scripts/mcp-smoke.sh
The script prints only status classes (OK / FAIL), never the token.
Manual¶
export MCP_BASE="https://conductor-konstant.hectorsanchez.eu"
curl -fsS "$MCP_BASE/health"
curl -fsS "$MCP_BASE/connect/status"
curl -sS -o /dev/null -w "%{http_code}\n" "$MCP_BASE/mcp" # expect 401 without auth
Authenticated initialize (Streamable HTTP). Capture Mcp-Session-Id from the
response headers for tools/list. Expect tool name setup.
If curl fails verbosely, do not paste stderr into chat when it may contain the Authorization header — re-run with redacted logging or the smoke script.
Public DNS / Tailscale¶
If public DNS fails on the agent host, use Tailscale Funnel with a Host header
(see Konstant runbook 00-connect-from-any-machine.md):
curl -fsS -H 'Host: conductor-konstant.hectorsanchez.eu' \
https://konstant-server.tail64860f.ts.net/health
Failure matrix¶
| Symptom | Likely cause | Fix |
|---|---|---|
| Relative link returns 401 | Resolved to /connecting.md etc. |
Use absolute https://…/connect/….md URLs |
| secret-gate fails on Windows | PowerShell 5.1 | Use pwsh 7.2+ (bootstrap) |
| Auth prompt never appears | Hidden agent TTY | Human runs secret-gate auth in a visible terminal |
CONDUCTOR_MCP_AUTH_TOKEN missing |
Forgot eval/Invoke-Expression refresh |
Re-run export from bootstrap |
| OpenCode error echoes token | Wrong header Authorization: Bearer |
Use Authorization=Bearer … or JSON {env:…} |
| Codex cannot fetch connect URL | workspace-write sandbox |
--sandbox danger-full-access |
| Codex: not a trusted directory | Non-git workdir | Add --skip-git-repo-check |
Nested codex exec hangs / slow |
Using nested agent as smoke | Prefer mcp-smoke.sh first |
Tools missing after mcp add |
Client not restarted | Exit and launch a new process from the exporting shell |
HTTP 401 on /mcp |
Token unset / wrong / not inherited | Length-check env in parent of the client |
| HTTP 400 on second MCP call | Missing Mcp-Session-Id |
Reuse session header from initialize |
Looking for list_business_lines |
Stale docs / archived compiler | Only setup exists now |
Connect status endpoint¶
GET /connect/status returns non-secret service facts (version, tool names,
endpoints). It does not know whether your local secret-gate session is
valid — that stays client-side (secret-gate status).