Install Claude Code

Claude Code uses StateLode’s hosted Streamable HTTP endpoint directly. There are two surfaces — the claude CLI and the Claude desktop app — and they share the same endpoint. The default way in is Connect with StateLode: a browser sign-in, with no token to mint, paste, or rotate. Static tokens are still available for headless and CI use further down.

Config format and CLI verified against Claude Code’s MCP docs as of 2026-06.

Connect with StateLode (recommended)

Add the server without a token and let Claude Code run the sign-in. On the first tool call it opens your browser, you sign in to StateLode (via WorkOS) and pick a workspace, and Claude Code stores and refreshes the credential for you. Nothing lands in a file, nothing to rotate, and it survives restarts. Your role in that workspace sets access — owner, admin, and member get read + write; viewer is read-only.

Claude Code CLI

claude mcp add --scope user --transport http statelode https://api.statelode.dev/mcp

No --header, no token — that’s the point. --scope user is the flag that matters: it registers StateLode once for every project on this machine. Without it, claude mcp add defaults to local scope and saves the server only for the current directory, so every other repo opens with no StateLode tools. Flags go before the server name. Reach for --scope project only when you deliberately want a shared .mcp.json checked into one repo.

Then start a session and run /mcp. Select statelode → Authenticate to complete the browser consent. Manage it any time with claude mcp list, claude mcp get statelode, and /mcp.

Claude desktop app

Open Settings → Connectors → Add custom connector, give it the name statelode and the remote URL https://api.statelode.dev/mcp, and add it. Claude opens the StateLode sign-in; authorize the workspace and you’re done. Connectors you add in the Claude app (or at claude.ai/customize/connectors) also surface inside Claude Code under /mcp.

Static token (machine & CI)

Prefer Connect above for everyday use. Reach for a static statelode_live_… token when there is no browser for a consent flow — CI jobs, headless agents, or shared service accounts. Mint one in the dashboard and keep it out of git — see Token security. Don’t paste it into a Claude chat to “add the MCP”; use the command or config file below. (You can ask Claude Code to open your .mcp.json so you paste the config and token in yourself — see Let the agent open the file.)

Add the server with the token in the Authorization header. Put it in your environment first so it isn’t written into shell history as a literal:

export STATELODE_TOKEN="paste-your-token-here"

claude mcp add --scope user --transport http statelode https://api.statelode.dev/mcp \
  --header "Authorization: Bearer $STATELODE_TOKEN"

The CLI expands $STATELODE_TOKEN at add-time and stores the resolved value in ~/.claude.json (under the user scope). To keep the token out of any file entirely, use the project .mcp.json form below — Claude Code expands ${STATELODE_TOKEN} at runtime, so only the variable name is stored (this form is per-repo, so add it to each project).

Project-scoped .mcp.json (token stays in your env, not the file):

{
  "mcpServers": {
    "statelode": {
      "type": "http",
      "url": "https://api.statelode.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${STATELODE_TOKEN}"
      }
    }
  }
}

Verify

Ask Claude Code:

What active StateLode task should I work on in project statelode?

The first tool call should be task_search, followed by task_get for the selected task.

Troubleshooting

• /mcp shows statelode as needing auth — that’s expected on the Connect path until you finish the browser sign-in. Run /mcp, pick statelode, and choose Authenticate.
• Config parse error — a ${STATELODE_TOKEN} reference with the variable unset makes Claude Code refuse to load. Export the token in the shell you launch claude from, or use the ${STATELODE_TOKEN:-} default form while testing. (Connect avoids this — there’s no token in the config.)
• 401 / connection failed on the token path — if you set an Authorization header and the token is bad, Claude Code reports a failed connection rather than falling back to Connect. Re-mint the token and re-add, or drop the header and use Connect instead.