← Back to home

Setup

Connect WorkBrain to your IDE so its agent can use your project memory while you work. Pick the path that matches your tooling — they all hit the same remote MCP endpoint at https://www.workbrain.app/api/mcp.

1. Prerequisites

You need an API key (starts with wbk_). If you don't have one yet, redeem an invitation at /signup — you'll receive your key once. If you already have an account, create or review keys at /account/api-keys.

We never display the raw key after creation. If you lose it, create another and revoke the old one. There's no recovery path.

2. Cursor

Cursor has a 1-click install for MCP servers — no terminal, no JSON editing.

Option A — One-click (recommended)

Go to /account/api-keys and click Create key. The success banner shows an Add to Cursor button — that opens Cursor with the MCP config already filled in. Confirm the prompt and you're done.

Option B — Manual fallback

If the deep link doesn't open Cursor (corp policy, missing handler), edit ~/.cursor/mcp.json and merge:

~/.cursor/mcp.json
{
  "mcpServers": {
    "workbrain": {
      "url": "https://www.workbrain.app/api/mcp",
      "headers": {
        "Authorization": "Bearer wbk_PASTE_YOUR_KEY_HERE"
      }
    }
  }
}

Replace wbk_PASTE_YOUR_KEY_HERE with your real key. Restart Cursor.

3. Claude Code (CLI)

If you live in the terminal, this is the fastest path.

Step 1 — Install Claude Code

shell
npm install -g @anthropic-ai/claude-code

Requires Node 20+ globally. On Linux/macOS the binary lands in your Node prefix. Verify with claude --version.

Step 2 — Register WorkBrain at user scope

shell
claude mcp add workbrain --scope user --transport http \
  https://www.workbrain.app/api/mcp \
  --header "Authorization: Bearer wbk_PASTE_YOUR_KEY_HERE"

Replace wbk_PASTE_YOUR_KEY_HERE with your real key. --scope user means the registration applies to any folder you open Claude Code in — you don't need to repeat it per project.

4. Claude Code (VS Code extension)

The VS Code extension reads the same configuration as the CLI (~/.claude.json), so registering once via the CLI covers both.

  1. Install the extension from the VS Code Marketplace ("Claude Code").
  2. Run the CLI register command above, even if you only intend to use VS Code.
  3. Reload the VS Code window (Cmd/Ctrl+Shift+P → "Reload Window") so the extension picks up the new config.
  4. Open the Claude Code chat panel (right sidebar) and type /mcp — workbrain should be listed with ✓ Connected.

5. Claude Desktop

Claude Desktop reads its MCP config from claude_desktop_config.json. To find the file: Settings → Developer → Edit Config.

claude_desktop_config.json
{
  "mcpServers": {
    "workbrain": {
      "type": "http",
      "url": "https://www.workbrain.app/api/mcp",
      "headers": {
        "Authorization": "Bearer wbk_PASTE_YOUR_KEY_HERE"
      }
    }
  }
}

Replace wbk_PASTE_YOUR_KEY_HERE with your real key. Save the file and restart Claude Desktop.

6. Verify it works

From any folder (it's user-scoped, so any folder works):

shell
cd /tmp && claude mcp list

Expected output:

output
workbrain: https://www.workbrain.app/api/mcp (HTTP) - ✓ Connected

Inside Claude Code (CLI or VS Code chat), type /mcp. The workbrain server should be listed with five tools:

7. First steps

  1. Create your first project at /projects/new. Pick a client slug (e.g. your customer) and project slug (e.g. the system you're working on).
  2. Open the project in your IDE and ask Claude to ingest your first ticket. Plain text:
    prompt
    Use workbrain.ingest_paste in projectSlug "<your-slug>" to save:

TICKET-1234: <title>
<paste body here>
  3. Once you have 2-3 docs, run compose_context on one and ask for a plan. That's the moment WorkBrain pays off.

Don't try to seed everything at once. Add tickets as you work, decisions as you make them, and canon (/projects/<client>/<project>/canon) when you have 15 min between meetings.

8. Troubleshooting

claude mcp list doesn't show workbrain

You may have run claude mcp add without --scope user — that registers it only for the current folder. Re-run the command with the flag. You can also inspect ~/.claude.json to confirm the entry is in mcpServers.

workbrain shows but says "Not connected" or 401

Your API key is rejected. Possible causes: revoked, mistyped, or extra whitespace when pasted. Verify the key is still active at /account/api-keys; if not, create a new one and re-run claude mcp add (Claude Code overwrites the existing entry on re-add).

Cursor "Add to Cursor" button doesn't open the app

Browser blocked the deep link, or Cursor isn't installed. Use the manual JSON fallback above (~/.cursor/mcp.json) and restart Cursor.

Tools call returns "project_not_found"

The projectSlug you passed doesn't match any project under your user. Check /projects for the exact slugs (lowercase, dashes, no spaces). Cross-user projects are invisible by design.

The agent ignores my canon / doesn't reference my conventions

Make sure you populated canon at /projects/<client>/<project>/canon. The model respects it best when called via compose_context — that bundles canon explicitly. A bare search won't include it.

Something off in this guide? Tell Carlos. We'll keep it updated as the platform evolves.