Agent setup

You are the coding agent. The human may not know where MCP config files live, which format your client expects, or which setup command belongs in which directory. Do not hand that work back to them.

Your job is to configure StateLode, verify that the connection works, and then use the claim-first workflow. The human has only two browser-only jobs: sign in to StateLode if they are not already signed in, and approve the OAuth consent screen when your MCP client opens it.

Before you edit anything

1. Identify which client you are running in: Cursor, Claude Code, Codex, OpenCode, Windsurf, or Antigravity.
2. Prefer OAuth. Do not ask the human to paste a statelode_live_... token into chat.
3. Configure StateLode at global or user scope so it is available in every repo on this machine.
4. After MCP connects, run npx statelode-bridge setup once per machine.
5. In this repo, run npx statelode-bridge init <project-slug> once to pin the repo to a StateLode project.

If you do not know the project slug, ask the human for it. Do not guess one. After MCP is connected, you can also read the statelode://workspace resource to discover valid project slugs.

Human-only steps

• Sign in to StateLode in the browser.
• Approve the OAuth request when the MCP client opens the browser.
• Choose the workspace if the OAuth screen asks.
• Paste a static token only if they explicitly chose the headless, CI, or legacy-bridge fallback.

Everything else is agent work.

Agent steps

• Open or edit the correct global/user MCP config for your client.
• Add the StateLode server with OAuth as the default authentication path.
• Restart or reload the MCP client when that client requires it.
• Run npx statelode-bridge setup once per machine.
• Run npx statelode-bridge init <project-slug> once inside the repo.
• Verify with task_search against the pinned project.
• Confirm the dashboard shows the connection or latest activity.

MCP endpoint

Use the hosted Streamable HTTP endpoint:

https://api.statelode.dev/mcp

OAuth config should not include an Authorization header. The client should discover the protected-resource metadata, open the browser, and store the OAuth credential itself.

Client configs

Cursor

Open or create the global config:

~/.cursor/mcp.json

Use this OAuth config:

{
  "mcpServers": {
    "statelode": {
      "url": "https://api.statelode.dev/mcp"
    }
  }
}

Then open Cursor settings for Tools & MCP, choose the StateLode login/connect action, and let the human approve the browser flow.

Claude Code

Prefer the CLI because it writes the user-scoped config correctly:

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

Then ask the human to authenticate from /mcp if Claude reports that StateLode needs auth. Do not add --header unless the human explicitly chooses the static-token fallback.

Codex

For the Codex desktop app, use the custom MCP UI with Streamable HTTP:

https://api.statelode.dev/mcp

For the Codex CLI, MCP config is stdio-only today. Open or create:

~/.codex/config.toml

If the human explicitly chooses the static-token bridge fallback, add:

[mcp_servers.statelode]
command = "npx"
args = ["statelode-bridge", "--token", "paste-token-here"]

Do not ask the human to paste that token into chat. Ask them to paste it directly into the config file or use the desktop app OAuth path instead.

OpenCode

Open the global config:

~/.config/opencode/opencode.json

Use this OAuth config:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "statelode": {
      "type": "remote",
      "url": "https://api.statelode.dev/mcp",
      "enabled": true,
      "oauth": {}
    }
  }
}

Then run:

opencode mcp auth statelode

Windsurf

Open or create:

~/.codeium/windsurf/mcp_config.json

Use serverUrl, not url:

{
  "mcpServers": {
    "statelode": {
      "serverUrl": "https://api.statelode.dev/mcp"
    }
  }
}

Fully quit and reopen Windsurf, then let the human approve the sign-in from the MCP panel.

Antigravity

Open or create:

~/.gemini/config/mcp_config.json

Use serverUrl, not url:

{
  "mcpServers": {
    "statelode": {
      "serverUrl": "https://api.statelode.dev/mcp"
    }
  }
}

Refresh the MCP store and let the human approve the sign-in.

Machine setup

After the MCP server is configured, run this once on the machine:

npx statelode-bridge setup

This installs StateLode’s global agent workflow rules where supported. It does not require a token and it does not pin a repo to a project.

Repo setup

From the repo root, run:

npx statelode-bridge init <project-slug>

This writes the project pin and agent instructions into the repo. It is safe to run yourself after the human confirms the slug. If no slug was provided and the folder name is generic, ask before running it.

Verify

1. Restart or reload the MCP client if required.
2. Call task_search with the pinned projectId.
3. If task_search reports an unknown project, use the known project list in the error or read statelode://workspace; do not invent a slug.
4. Confirm the StateLode dashboard shows the connection or activity.

After connect

Use StateLode as the task source of truth:

• Start with task_search.
• Use task_get before mutation so you have the latest updatedAt.
• Claim work by moving it to in_progress.
• Move implementation to review after checks and commit.
• Move to done only after acceptance criteria pass.
• On STALE_WRITE, use the fresh task in the error payload and retry with its updatedAt.

Do not add tools. StateLode exposes three MCP tools: task_search, task_get, and task_mutate.