Install Windsurf

Windsurf speaks remote Streamable HTTP MCP, so it connects to StateLode’s hosted endpoint directly — no bridge required. The default way in is Connect with StateLode: add the server by URL and sign in through your browser, with no token to mint, paste, or rotate. A static token is still available for headless and CI use further down. Note the field name: Windsurf uses serverUrl (not url) for remote servers.

Config format verified against Windsurf’s Cascade MCP docs as of 2026-06.

Connect with StateLode (recommended)

Add the StateLode server without an Authorization header. When Windsurf connects it detects that the server needs authorization, opens your browser to sign in to StateLode (via WorkOS), and lets you pick a workspace; Windsurf then stores and refreshes the credential for you. Nothing to paste, nothing to rotate, and it survives restarts. Your role in that workspace sets access — owner, admin, and member get read + write; viewer is read-only.

Edit ~/.codeium/windsurf/mcp_config.json (on Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json) and add the server with just its serverUrl — no headers block:

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

Then quit Windsurf completely and reopen it — closing the window isn’t enough; MCP config is read at startup. In the Cascade MCP panel the statelode server will prompt you to sign in; complete the browser consent and it lists three tools (task_search, task_get, task_mutate).

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 Windsurf’s chat to set up MCP — you can ask the agent to open ~/.codeium/windsurf/mcp_config.json so you paste the config and token in yourself (Let the agent open the file).

Add the token in an Authorization header, literally. Windsurf does support ${env:VAR} interpolation, but the desktop app is launched from the Dock/Spotlight and doesn’t inherit your shell environment, so an ${env:STATELODE_TOKEN} reference is usually empty (see Token security). The file lives in your home directory, outside any repo; chmod 600 it on a shared machine.

{
  "mcpServers": {
    "statelode": {
      "serverUrl": "https://api.statelode.dev/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_STATELODE_TOKEN"
      }
    }
  }
}

Fully restart Windsurf after editing, the same as above.

Verify

Ask Windsurf:

Check StateLode for active work in project statelode.

The expected sequence is task_search, then task_get for the selected task, then task_mutate if you ask the agent to claim it.

Troubleshooting

• No tools after editing config — you didn’t fully restart. Quit the app, not just the window.
• statelode is waiting to sign in — that’s the Connect path. Complete the browser consent from the Cascade MCP panel’s sign-in prompt.
• 401 / empty token on the token path — you used ${env:STATELODE_TOKEN} but launched Windsurf from the Dock, so it never saw the variable. Paste the token literally into the config, or use Connect instead (no token needed). Then fully restart.
• Used url instead of serverUrl — Windsurf ignores url for remote servers. The field must be serverUrl.