# Connect Windsurf to Axiom

**Transport:** stdio (Windsurf also supports HTTP/SSE)
**Auth:** local-stdio (Phase 0)
**Status:** Untested — recipe inferred from upstream docs

Windsurf (Codeium's agentic IDE; now part of Cognition) ships its own
MCP client. Config lives at `~/.codeium/windsurf/mcp_config.json`.

## Install prerequisites

- Windsurf 1.4 or later (MCP UI under Cascade -> MCP).
- Same Axiom prerequisites as the other recipes.

## Configure the connection

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

```json
{
  "mcpServers": {
    "axiom-root": {
      "command": "/absolute/path/to/.venv/bin/axi",
      "args": ["mcp", "serve"]
    }
  }
}
```

Worktree variant:

```json
{
  "mcpServers": {
    "axiom-root": {
      "command": "/absolute/path/to/.venv/bin/python3",
      "args": ["-m", "axiom.extensions.builtins.mcp.server"],
      "env": {
        "PYTHONPATH": "/absolute/path/to/axiom-checkout/src"
      }
    }
  }
}
```

Then in Windsurf: Cascade panel -> MCP icon -> "Refresh".

## Verify

The MCP panel should show `axiom-root` with its tool count. Run from
Cascade chat:

```
Call axiom_node__hooks_list with no arguments and report the JSON.
```

Expected:

```json
{
  "node": "/Users/<you>/.axiom",
  "hooks_total": 0,
  "events_observed": [],
  "by_event": {}
}
```

## Notes

- Windsurf's MCP integration is similar to Cursor's — tool-call approval
  is per-server, with optional auto-approve per tool.
- Windsurf supports HTTP/SSE via a `url` field in the same JSON; needs
  Axiom Phase 5 auth.
- The Cascade "personality" can choose to ignore tool calls if it
  thinks they're unnecessary; explicit "use tool X" prompts are most
  reliable for verification.

## Troubleshooting

| Symptom | Likely cause | Fix |
|---|---|---|
| "Failed to start MCP server" | path issue | Absolute path, verify with `which axi` |
| Tools listed but never invoked | Cascade picking other strategy | Phrase the prompt as "use the axiom_node__hooks_list tool" |
| Surface stale | needs refresh | MCP icon -> Refresh, or restart Windsurf |

## References

- ADR-038 §D7
- Windsurf MCP docs: https://docs.windsurf.com/windsurf/cascade/mcp

_Copyright (c) 2026 B-Tree Ventures, LLC. Apache-2.0 licensed._
