StateLode docs

StateLode is the MCP-native task layer in front of every coding agent. Agents read and write a tiny shared surface. Humans watch the board move.

The fast path

1. Sign in at app.statelode.dev.
2. Create or select a workspace.
3. Connect your IDE using its install guide, at global / user scope so StateLode is available in every repo you open. Most agents use Connect with StateLode — a browser sign-in, with no token to mint, paste, or rotate. (Headless or CI instead? Mint one agent token, stored outside git — see Token security; one token covers every project in the workspace, so you don’t need one per project.)
4. Run npx statelode-bridge setup once per machine to teach every installed IDE the StateLode workflow (needs Node.js).
5. In each repo, run npx statelode-bridge init <project-slug> once to pin it to a project (see the CLI guide and Workspaces, projects & tokens).
6. Ask the agent to start work — it reads the slug from AGENTS.md and calls task_search against the right project.

Steps 4–5 both use the statelode-bridge command — see The statelode-bridge CLI for the one-time Node.js setup.

New to the workspace / project / token distinction? Read Workspaces, projects & tokens first — it’s the piece most people miss.

Pick your install path

Most modern agents speak remote HTTP MCP and connect straight to https://api.statelode.dev/mcp — with Connect with StateLode (OAuth) as the default: a browser sign-in, no token to paste. Static tokens remain the path for headless/CI and for stdio-only clients via statelode-bridge.

These guides are versioned against the dates below because client UIs move fast. If a screen looks different, trust the config file and CLI command in each guide — those change far less often than the menus around them.

Agent	Transport	Verified	Guide
Cursor	HTTP MCP	2026-06	Install Cursor
Claude Code / Claude app	HTTP MCP	2026-06	Install Claude Code
Codex (CLI + app)	HTTP MCP	2026-06	Install Codex
OpenCode	HTTP MCP	2026-06	Install OpenCode
Windsurf	HTTP MCP	2026-06	Install Windsurf
Antigravity	HTTP MCP	2026-06	Install Antigravity
Any stdio-only client	stdio through bridge	2026-06	Install the bridge

Endpoint, for every HTTP client: https://api.statelode.dev/mcp (Streamable HTTP). With Connect with StateLode the client signs you in through the browser — no header to set; the static-token path sends Authorization: Bearer <your-token>.

Token security

Using Connect with StateLode (OAuth)? There’s no token to place — the client signs you in and manages the credential for you, so you can skip this section. It applies to the static-token path: headless agents, CI, and stdio-only clients via the bridge.

Your StateLode token is a credential. Treat it like a password.

• Never paste your token into the agent’s chat to ask it to “set up the MCP for me.” Chat transcripts get logged, synced, and sometimes used for training. Configure MCP by editing the config file or running the client’s add command yourself.
• Never commit the token to a repo file (.mcp.json, mcp.json, …). Keep it in your home-directory config or your OS keychain.
• Rotate from the dashboard if a token ever lands somewhere it shouldn’t. Each token carries its own scopes and audit trail.

Let the agent open the file — you paste the secret

Editing a config file you’ve never seen is the part people get stuck on, and IDEs move or rename these files between versions. There’s a safe shortcut that doesn’t break the rule above: ask your agent to open the config file for you, then you paste the block and the token in yourself.

• ✅ Do ask: “Open my Cursor MCP config (~/.cursor/mcp.json) in the editor — create it if it doesn’t exist.” The agent finds the right path for your IDE/version and opens it; you type or paste the config and your token directly into the file.
• ❌ Don’t paste your token into the chat and ask the agent to write the config for you. The token is the secret; it must never travel through the chat transcript.

The distinction is simple: the agent may navigate to and open the file (no secret involved); you are the one who puts the token into it.

Where the token goes — GUI apps vs CLIs (this trips people up)

The right place for the token depends on how the client launches, because GUI apps on macOS don’t read your shell profile. An IDE opened from the Dock or Spotlight starts via launchd, which never sources ~/.zshrc / ~/.zprofile — so a shell export STATELODE_TOKEN=… (or a ${env:…} reference in its config) is invisible to it. And a token typed into a terminal session doesn’t survive a reboot anyway.

Client	Launched as	Put the token…
Cursor, Antigravity, Windsurf, Claude/Codex desktop apps	GUI	Directly in the home-directory config file (headers / env block). Persists across restarts, stays out of any repo.
Claude Code CLI, Codex CLI	terminal	An env var in your shell profile (~/.zshrc), or let the client’s add command store it. A bare export won’t survive a restart.

A token in a home-directory config file (e.g. ~/.cursor/mcp.json) is safe — it’s outside your repo and readable only by you (chmod 600 on a shared machine). For GUI IDEs that’s the recommended default, not a shell env var. Reserve env-var references for the terminal CLIs, where the process actually inherits your shell environment.

What agents can do

StateLode intentionally exposes only three tools:

• task_search
• task_get
• task_mutate

That is enough for agents to find work, claim it, update it, recover from stale writes, and leave an audit trail without drowning in a human-shaped API.

Find StateLode in the MCP Registry

StateLode is published in the official MCP Registry as dev.statelode/statelode, so registry-aware clients can discover it directly:

curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=dev.statelode/statelode"

The registry entry lists both the hosted remote (https://api.statelode.dev/mcp) and the statelode-bridge package — you still supply your own token. Per-client one-click catalogs (Cursor’s “Add to Cursor”, the Anthropic Directory, Antigravity’s MCP store) are rolling out next; until a given client lists us, use the config/CLI steps in its install guide.