Install OpenCode

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

Nothing lands in a file 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

Restart OpenCode (or reload its MCP servers), then 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

• 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.