Set up Cognition in two minutes
Generate a scoped key, run one install command, and your coding agent is wired to the shared brain. Works in Claude Code, Codex, Cursor, and Gemini. This walks the whole flow and the three things that trip people up.
Cognition installs once and then runs in the background. There is no dashboard to babysit, no daily ritual, no separate app to keep open. You spend two minutes wiring it into the coding agent you already use, and from then on it loads your team's judgment at the start of meaningful work and quietly gets out of the way the rest of the time.
Under the hood, the install does two small things: it registers Cognition as an MCP server your agent can call, and it drops a local instruction file that tells the agent to load the latest hosted behavior at the start of each session. That second part is what keeps you current without ever re-installing, which we will come back to.
Before you start
You need exactly two things: a coding agent that speaks MCP (Claude Code, Codex, Cursor, or Gemini), and a terminal you can paste one line into. You do not need Docker, a database, an API server, or a credit card to start. If you can run a curl command, you can finish this page.
1. Generate a scoped key
Go to /start and create a key. You will choose between two scopes, and the choice matters more than it looks:
- Solo (a personal key, cog_me_*): scoped to you. Skills you capture are yours, private by default. Perfect for trying it out or for individual work.
- Team (an org key, cog_live_*): scoped to your organization. It can see and contribute to the team brain, so a skill one teammate approves becomes available to everyone on the org key.
The scope is not just billing. A cog_me_ key only ever sees your own skills. If you later join a team and recall comes back empty on something a colleague clearly taught, this is almost always why: you are on a personal key, not the org key. You can hold both and switch.
Treat the key like a password, because it is one. Do not paste it into a shared chat, a committed file, or a screenshot. The installer reads it from an environment variable precisely so it never has to live in a file you might commit.
2. Run the installer for your host
One command wires the MCP server and the local instruction file for your agent. Swap in your key and pick your host. Here is the Codex example:
COGNITION_KEY=cog_me_xxx curl -fsSL https://www.cognitionus.com/api/install/codex | sh
Each host has a matching installer at /api/install/{cursor,codex,gemini,claude}. The script is small and does three things you can verify afterward: it adds the Cognition MCP server to your host's config, it writes the managed instruction block that loads Cognition each session, and it prints what it changed so nothing happens behind your back.
If you would rather wire it by hand, the one value you must get right is the server URL. Use the www host, not the apex:
https://www.cognitionus.com/api/integrations/claude-code/mcp/v1
This is the single most common setup failure. cognitionus.com (the apex) issues a 307 redirect to www, and several MCP HTTP clients do not re-send the POST body across a redirect, so the handshake silently fails with a vague "failed to connect." The installer already uses www. If you wired it by hand and it will not connect, check this first.
3. Restart, then just work
Restart the agent so it picks up the new tools. MCP tool lists are cached when the agent process starts, so a brand-new chat in the same process is not always enough, a full restart is. After that, you do not have to do anything special:
- 1Start a real task the way you normally would.
- 2At the start of meaningful work the agent calls cognition_assist, which loads any approved skills and project context relevant to what you are doing.
- 3It applies that judgment as it works, and tells you whose pattern it borrowed when it matters.
- 4When it finishes, it reports the outcome, which is the signal that sharpens the brain over time.
4. Confirm it is live
You do not have to take it on faith. Type /cognition, or just ask in plain English, "is Cognition connected?" You will get the command palette, your current skills with their freshness, and a health summary. If the palette shows up, you are wired in.
If you want the fullest possible check in one shot, ask "is Cognition healthy?" (routes to /cognition:health). It tells you whether the backend is genuinely persisting receipts and consent rather than just simulating them, which is the difference between "connected" and "fully operational."
What to do if it is not working
Ninety percent of setup issues are one of three things. The fixes are one line each:
| Symptom | Likely cause | Fix |
|---|---|---|
| "Failed to connect" right after install | apex 307 redirect drops the POST | register the www URL, reconnect |
| Connected, but no tools show up | tool list cached at process start | fully restart the agent, not just a new chat |
| Connected, but recall is empty | personal key, or skill still a draft | use the org key, approve the skill |
If none of those land it, the full troubleshooting guide walks each failure mode in depth, including how to tell a local problem from a backend one in five seconds.
next steps