Troubleshooting — Codens Help

Symptom	What to check
MCP tools don't appear in the agent	Make sure `mcpServers.codens.command` in `~/.claude/settings.json` points to the actual `codens-mcp` binary. Confirm with `which codens-mcp`.
Login fails with `expired_token`	Device Code Flow's `user_code` has a 15-minute lifetime. Open https://auth.codens.ai/device right after running `codens-mcp login` and paste the code. If it keeps expiring, open the URL first, then run the CLI, and paste immediately. A new code is issued each login attempt.
`UNAUTHORIZED` repeatedly	Token likely expired. Check with `codens-mcp whoami` and re-run `codens-mcp login` if it fails. Token is stored at `~/.purple-codens/credentials.json`.
Cross-service `UNAUTHORIZED` / `ORG_NOT_FOUND`	Red / Blue / Green / Purple each issue independent `organization_id`. Don't pass `organization_id` — codens-mcp v0.7.5+ resolves it automatically. If you belong to multiple orgs, the tool returns a candidate list to choose from.
workflow run stuck at "pending"	The Fargate / VPS pool may be saturated. Check `purple_workflow({ action: "get_run_status", run_id })`. If it hasn't moved for 15+ minutes, contact us with the `run_id`.
PR was created but tests fail	Purple's fix_verify loop auto-improves the patch a few times. If it still fails, re-run via `red_bug_report({ action: "create" })` → `red_bug_fix_plan({ action: "submit_to_purple" })` as a fresh chain.
Notion sync isn't reflecting (Green)	Verify the Notion link with `green_notion({ action: "status" })`. If unlinked, run `green_notion({ action: "link" })` and complete OAuth in the returned URL (workspace admin required).
E2E test runner can't reach the target site	Add Blue's outbound IPs to your environment's allow list. Dashboard → Project → Environments → IP allow list shows the IPs.
Sentry webhook isn't reaching Red	Confirm Sentry's Internal Integration signing secret matches the value in Red's dashboard. Header verification failures show up in Red's activity log (Project → Activity log).