Install OpenCode

Let your agent do the setup

Paste this into OpenCode:

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.

OpenCode should inspect and merge its own config, trigger OAuth, and verify the server. You handle browser consent and restart OpenCode when the current session cannot restart itself. The steps below are the manual fallback and troubleshooting reference.

OpenCode connects to StateLode through the mcp block of its config file — opencode.json (or opencode.jsonc) in your project root, or the global ~/.config/opencode/opencode.json. OpenCode speaks MCP over remote HTTP, so it reaches StateLode’s hosted endpoint directly, no bridge required. The default way in is Connect with StateLode: a browser sign-in with no token to mint, paste, or rotate. A static token and the stdio bridge are below.

Config format verified against OpenCode’s MCP + rules docs as of 2026-06.

Connect with StateLode (recommended)

Add the server as a remote MCP with an empty oauth block. OpenCode handles the OAuth flow (including dynamic client registration): it opens your browser to sign in to StateLode (via WorkOS) and pick a workspace, then stores and refreshes the credential for you. Your role in that workspace sets access — owner, admin, and member get read + write; viewer is read-only.

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

Trigger the sign-in with:

opencode mcp auth statelode

After browser consent succeeds, completely exit and restart OpenCode before verification. Editing the global config does not make an already-running OpenCode process discover the new server reliably. If the agent performing setup is inside that process, its correct handoff is one exact request—restart OpenCode and return with “continue setup”—then it must resume and run:

opencode mcp list

statelode must appear in that resolved list. A successful file edit or OAuth callback alone is not completion. Nothing secret lands in the config and there’s no token to rotate. (This needs an OpenCode version with remote-MCP OAuth support — if oauth isn’t recognized or the sign-in never opens, use the static-token path below.)

Static token (machine & CI)

When there’s no browser for a consent flow — CI, headless runs, shared service accounts — use a static statelode_live_… token. Mint one in the dashboard and keep the config out of git (see Token security). Don’t paste the token into an OpenCode chat to “add the MCP”; put it in the config yourself, or ask OpenCode to open the file so you paste it in (Let the agent open the file).

Send it as an Authorization header on the same remote server. OpenCode substitutes {env:VAR} at load time, so reference an env var and the literal token never lands in the file:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "statelode": {
      "type": "remote",
      "url": "https://api.statelode.dev/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {env:STATELODE_TOKEN}"
      }
    }
  }
}

Export STATELODE_TOKEN in the shell you launch opencode from. Put this in your project opencode.json (highest precedence) or the global ~/.config/opencode/opencode.json to cover every project.

Through the bridge (stdio)

Prefer a local stdio server — or already run statelode-bridge for another tool? Register it as a local MCP instead. This path needs Node.js on your PATH, since the bridge runs through npx — see The statelode-bridge CLI.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "statelode": {
      "type": "local",
      "command": ["npx", "statelode-bridge", "--token", "paste-your-token-here"],
      "enabled": true
    }
  }
}

The remote paths above are simpler for OpenCode; reach for the bridge only when you specifically want stdio.

Pin the project

So OpenCode sends the right projectId and follows the task workflow, pin the project from your repo root:

npx statelode-bridge init <your-project-slug>

init writes a statelode.json marker and adds a ## StateLode block to AGENTS.md — which OpenCode auto-loads as project rules — so the slug and the claim-first task workflow land in OpenCode’s context for free. (init writes CLAUDE.md too; OpenCode reads AGENTS.md first, then falls back to CLAUDE.md.) See the statelode-bridge CLI for what init writes.

Verify

After the required restart, first run opencode mcp list. Once it shows statelode as connected, ask:

Use StateLode to list active tasks for project <your-project-slug>, then get the highest-priority one.

OpenCode should call task_search first and only call task_get after choosing a task summary.

Troubleshooting

• No MCP servers configured / MCP server not found: statelode — the current process has not resolved a mcp.statelode config entry. Run opencode debug paths and opencode debug config, confirm the global entry is under the reported config directory, then completely exit and restart OpenCode. A configured server with enabled: false appears as disabled; “No MCP servers configured” means the entry is absent from the resolved config.
• Config and OAuth succeeded, but every prompt reports an MCP/SSE error — fully restart OpenCode. It initializes enabled MCP servers before prompts, so a stale broken connection can also block prompts that do not call StateLode.
• oauth not recognized / no sign-in opens — your OpenCode version may predate remote-MCP OAuth. Use the static-token header form above.
• 401 / connection failed (token path) — confirm STATELODE_TOKEN is exported in the shell that launched OpenCode and is a current, unrevoked token from the dashboard. {env:…} silently becomes an empty string when the variable is unset.
• Server never connects (bridge path) — confirm Node.js is installed and on your PATH (node --version); the bridge launches through npx.
• Agent doesn’t know the project / ignores task rules — run npx statelode-bridge init <slug> in the repo so AGENTS.md carries the StateLode block, and confirm OpenCode is loading AGENTS.md from the project root.
• Edited the wrong file — a project opencode.json overrides the global ~/.config/opencode/opencode.json. If a repo has its own config, fix the server there too.