Install Claude Code

Let your agent do the setup

Paste this into Claude Code:

Set up StateLode in this coding environment.
Read and follow https://statelode.dev/docs/agent-setup/
First tell me which client and which surface you are running in — for example a terminal CLI or a desktop app. Ask me if you cannot tell from the environment, and do not guess: for some clients the surface changes the config and the sign-in step.
Do every setup step you can yourself. Do not ask me to edit config files, run commands you can run, or paste secrets into chat.
Pause only for browser sign-in or OAuth consent, a client restart you cannot safely perform yourself, or a genuinely ambiguous client, surface, or project choice. Give me one exact action, wait for me to finish it, then continue.
Finish only after you verify the MCP connection, discover the workspace and projects, and make the current repo ready to use StateLode.

Claude Code should handle the CLI/config and verification. You handle only browser consent or a restart it cannot perform. The steps below are the manual fallback and troubleshooting reference.

Claude Code uses StateLode’s hosted Streamable HTTP endpoint directly. 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.

Know which surface you’re on

Three things carry the Claude name and they do not authenticate the same way. Picking the wrong one is the most common reason setup “finishes” and StateLode still doesn’t work.

Surface	How StateLode is added	Where the credential lives
Claude Code CLI (claude in a terminal)	claude mcp add + claude mcp login	~/.claude.json + your OS credential store
Claude Code desktop app	the same two commands — shared with the CLI	the same store as the CLI
Claude app / claude.ai (the chat app)	Settings → Connectors → Add custom connector	your Claude account, server-side

The first two are one installation. They read the same ~/.claude.json and the same credential store, so you add and authenticate once and both surfaces pick it up. You do not repeat the setup in the desktop app.

The third is genuinely separate. A connector added in the Claude app is attached to your Claude account, not your machine — it shows up inside Claude Code as claude.ai statelode, and it is neither created nor authenticated by the CLI commands below. See Claude app connectors.

Connect with StateLode (recommended)

This is the path for both the Claude Code CLI and the Claude Code desktop app. Run the commands in any terminal; the desktop app inherits the result.

1. Add the server

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.

2. Sign in

claude mcp add only writes the server entry — it does not authenticate. Until you run this, StateLode sits at “Needs authentication” no matter how many times you restart:

claude mcp login statelode

That opens your browser, you sign in to StateLode (via WorkOS), 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 the workspace sets access — owner, admin, and member get read + write; viewer is read-only.

Run it once. It covers the CLI and the desktop app together.

Inside an interactive claude session you can instead run /mcp and select statelode → Authenticate. That’s the same flow through a terminal dialog. Prefer claude mcp login — it’s a plain command, so a setup agent can run it for you, and it works from the desktop app’s terminal where the /mcp picker isn’t reachable.

3. Verify

claude mcp list

statelode must read ✔ Connected. If the Claude Code desktop app was already open, restart it now so it picks up the new credential. Manage the server any time with claude mcp get statelode, claude mcp login statelode, and claude mcp logout statelode.

Claude app connector (optional)

Only if you also want StateLode inside the Claude chat app or on claude.ai — this is not required for Claude Code and does not replace the steps above. 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 added there also surface inside Claude Code, listed with a claude.ai prefix.

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

First confirm the connection itself with claude mcp list (see step 3 above), then 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

• statelode shows “Needs authentication” — the server entry exists but no one signed in. claude mcp add does not authenticate. Run claude mcp login statelode, then restart the Claude Code desktop app if it was open. Restarting alone never fixes this.
• “I authenticated but it still doesn’t work” — check what you signed into. Signing in to the StateLode dashboard in your browser is not the same as authorizing the MCP client; only claude mcp login statelode (or /mcp → Authenticate) stores a credential for Claude Code. Confirm with claude mcp list.
• “Do I have to set it up again in the desktop app?” — no. The CLI and the Claude Code desktop app share one config and one credential store. Set it up once, then restart the app. Only the separate Claude app / claude.ai connector needs its own authorization.
• 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.