Connect Claude Code

Claude Code connects to Octopus over HTTP. Sign in with your browser (recommended), or use a personal key on machines without a browser.

Sign in with your browser

1. Add Octopus for all your projects:

   claude mcp add --transport http --scope user octopus https://mcp.octopus-brain.com/mcp
   

2. Start Claude Code and type /mcp. Select octopus, then Authenticate.

3. Your browser opens octopus-brain.com: sign in, choose the teamspace and click Allow. Back in the terminal, Octopus shows as connected.

Check it anytime:

claude mcp list

About scopes: --scope user makes Octopus available in every project. Use --scope local (the default) for the current project only, or --scope project to share the server through the repository's .mcp.json — never with a key written in it.

Use a personal key

For servers, CI jobs or remote machines without a browser:

1. Generate a key on octopus-brain.com/connect (Personal keys → Generate a key). It's shown once: copy it.

2. Add Octopus with the key:

   claude mcp add --transport http --scope user octopus https://mcp.octopus-brain.com/mcp \
     --header "Authorization: Bearer osk_ext_…"
   

To keep the key out of shared files, reference an environment variable in .mcp.json:

{
  "mcpServers": {
    "octopus": {
      "type": "http",
      "url": "https://mcp.octopus-brain.com/mcp",
      "headers": { "Authorization": "Bearer ${OCTOPUS_API_KEY}" }
    }
  }
}

When an Authorization header is configured and rejected (revoked or expired key), Claude Code does not fall back to the browser sign-in. Remove the server with claude mcp remove octopus and add it again.

A key works in one teamspace, acts with your role and expires after 30, 90 or 180 days (90 by default).

Prompts and tools

• Say “use Octopus” or run /mcp__octopus__octopus to start: Claude Code loads the team's Octopus context first, then works.
• Octopus workflows appear as slash commands such as /mcp__octopus__catch_up — type /mcp__octopus__ to see them all.
• Claude Code loads MCP tools on demand (tool search), so the Octopus catalog doesn't fill your context.
• Very large results are saved to a file by Claude Code. Raise MAX_MCP_OUTPUT_TOKENS if you want more inline.

Remove

claude mcp remove octopus

Then disconnect the app or revoke the key at octopus-brain.com/account.