Windsurf integration

Windsurf (by Codeium) supports MCP servers natively in Cascade.

Setup

1. Add to your MCP config

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "oka": {
      "command": "npx",
      "args": ["-y", "@oka-core/reason"]
    }
  }
}

2. Authenticate

Open the Cascade panel and use the login tool:

Use the login tool to authenticate with Oka

This opens your browser to id.oka.so where you sign in or create an account. Your credentials are stored locally and refresh automatically.

3. Verify the connection

Click the MCPs icon in the Cascade panel. You should see oka listed with a green status indicator. Click it to see all 19 available tools.

Windsurf-specific notes

Tool limit

Windsurf has a hard limit of 100 tools across all MCP servers combined. If you use many MCP servers, you can toggle individual tools on/off per server in the MCP settings panel. Oka’s 19 tools are well within this limit.

Cascade Rules integration

Add Oka instructions to your project’s Cascade Rules (Windsurf’s equivalent of .cursorrules or CLAUDE.md). Create .windsurfrules in your project root:

## Oka Reason

- Before starting any task, call context() for the relevant area
- Record architectural decisions with the decision tool
- Record deviations from expected behavior with the deviation tool
- Call done() when completing tasks with outcome notes

Tips

Set OKA_WORKSPACE in the env block to scope events to your project.
Windsurf may not always call MCP tools proactively. Be explicit: “Use the Oka context tool to check…”