Troubleshooting: connection, stale tools, keys, and recall
The handful of issues that trip people up and the exact fix for each, from the apex redirect that breaks MCP to recall that comes back empty, plus how to tell a local problem from a backend one in five seconds.
Almost every problem people hit is one of four things, and each has a one-line fix. Start with the quick reference, then drop into the section for your symptom. There is a fifth section for telling local problems from backend ones, which saves you from chasing the wrong fix.
Quick reference
| Symptom | Cause | Fix |
|---|---|---|
| "Failed to connect" after install | redirect or marketing host drops the POST | register the stable API URL |
| New features or tools missing | local block / tool list stale | /cognition:update, then full restart |
| Recall empty on taught items | key scope or unapproved draft | use the org key, approve the skill |
| Unsure if backend is recording | persisted vs simulated | /cognition:health |
"Failed to connect" right after install
This is the most common one, and it is almost always a redirect or marketing-domain issue. Several MCP HTTP clients do not re-issue the POST body on a redirect, so the handshake fails with an unhelpful connection error. The endpoint your client must point at is the stable API host directly:
https://www.cognitionus.com/api/integrations/claude-code/mcp/v1
If you used the installer, it already uses this host, so look elsewhere. If you wired the server by hand, this is your fix: switch the endpoint to the stable API URL and reconnect. It catches the large majority of "it just will not connect" reports.
New features or tools are missing
Hosted behavior updates instantly for everyone, but three local layers can lag behind: the managed instruction block, your client_stub_version, and the cached tool list. Reconcile them in one command:
/cognition:update (or: "update Cognition")
After updating, a fresh chat is not always enough. The tool list is cached at the process level when the agent starts, so a full agent restart is what reloads it. This is the single most common false alarm: people refresh the chat, see the old tools, and assume the update failed when it just needs a restart.
Recall returns no match on things you just taught
Two usual culprits, in order of likelihood. First, key scope: a personal key (cog_me_*) only sees your own skills, so anything a teammate taught needs the org key (cog_live_*), or the skill promoted to team visibility. Second, approval state: a skill that is still a draft lives in the author's private workspace and is invisible to recall until it is approved.
- On a team and missing a colleague's skill? Confirm you are on the org key, not your personal one.
- Missing your own just-captured skill? Confirm you approved it, rather than leaving it as a draft.
- Still nothing? Check that the skill's trigger actually matches the situation you are testing; a too-narrow trigger will not fire.
Telling local from backend in five seconds
When you are not sure whether the problem is your install or something server-side, do not guess. Ask:
/cognition:health (or: "is Cognition healthy?")
If health comes back clean, the problem is local, your connection, key, or cached tools, and the sections above apply. If health flags a missing ledger or migration, the issue is backend and the report tells you the next action. Either way you have stopped chasing the wrong half of the system.
When you do file an issue or ask for help, run /cognition:what-did-you-use first and include the relevant ledger lines. They show exactly what fired and what it loaded, which turns a vague "it is not working" into a diagnosable report.
Next steps