> ## Documentation Index
> Fetch the complete documentation index at: https://schemabrain.mintlify.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Windsurf

> 60-second wiring for Windsurf / Cascade. Auto-detected by the activation wizard.

# SchemaBrain + Windsurf

> **60 seconds:** install SchemaBrain, run `schemabrain init`, restart Windsurf, ask Cascade about your database.

SchemaBrain is the trust and intelligence layer between Windsurf's Cascade agent and your Postgres database — twelve read-only MCP tools, validated metrics, tamper-evident audit. Works on macOS, Linux, and Windows.

***

## Install

```bash theme={null}
uvx schemabrain init --host windsurf
# or install first: pipx install schemabrain (or: pip install schemabrain)
```

The wizard prompts you to pick **1. Connect my own Postgres** (paste a `postgresql+psycopg://...` URL) or **2. Try with sample data** (a 12-table SaaS fixture spins up in Docker; \~\$0.03 to index). Press Enter to take the default (`2`).

The wizard then introspects the schema, classifies columns for PII, optionally calls Anthropic to suggest entities/metrics/joins, then writes the MCP entry to `~/.codeium/windsurf/mcp_config.json` (Windsurf's global MCP config — the Codeium namespace persists from before Windsurf split out as a standalone IDE).

## Resulting config entry

```json theme={null}
{
  "mcpServers": {
    "schemabrain": {
      "command": "uvx",
      "args": [
        "schemabrain==0.6.0",
        "serve",
        "--url-env", "SCHEMABRAIN_DATABASE_URL",
        "--store-path", "/Users/you/schemabrain.db",
        "--pii-block", "credential,government_id,payment_card"
      ],
      "env": {
        "SCHEMABRAIN_DATABASE_URL": "postgresql+psycopg://user:pass@host:5432/db"
      }
    }
  }
}
```

The JSON shape matches Claude Desktop's `mcpServers.{name}` map exactly — no extra fields. The `SCHEMABRAIN_DATABASE_URL` env-var key is the wizard's default, prefixed to avoid colliding with any app-level `DATABASE_URL` you already have in Windsurf's env.

## Restart Windsurf

Quit Windsurf fully and relaunch. The MCP config is only read on cold start.

## Ask Cascade

> list the entities SchemaBrain knows about

If Cascade calls `list_entities` and reports the entities curated during init, you're done. Otherwise run `schemabrain doctor --verify` for an end-to-end smoke test that doesn't require an Anthropic key.

**Next:** [First 5 Queries](../first-5-queries.md) walks you through exercising each load-bearing mechanism (read-only, PII refusal, audit chain, structured recovery) in \~10 minutes.

***

## What you get

* **12 MCP tools, none of which can write.** Full list in [`/mechanism/read-only`](/mechanism/read-only).
* **PII-aware refusal at the `get_metric` boundary.** Defaults block `credential`, `payment_card`, `government_id`. `--pii-block` **replaces** the set rather than extending it, so widen by listing the full target set, e.g. `--pii-block credential,payment_card,government_id,contact,health`. Details in [`/mechanism/pii-taxonomy`](/mechanism/pii-taxonomy).
* **Tamper-evident audit chain.** Verify with `schemabrain audit verify`. Details in [`/mechanism/audit-chain`](/mechanism/audit-chain).
* **Structured recovery envelopes.** Refusals ship typed contracts Cascade can act on programmatically. Details in [`/mechanism/structured-recovery`](/mechanism/structured-recovery).

## Sample interaction

> **You:** What's our total invoiced revenue per workspace?
>
> **Cascade:** *(calls `find_relevant_entities("invoiced revenue per workspace")` → `resolve_join` finds the canonical join path → `get_metric` returns the answer)*

When two parallel joins exist between the same pair of entities, the response disambiguates with a structured choice:

```json theme={null}
{
  "status": "error",
  "error": {
    "kind": "ambiguous_join",
    "recovery": {
      "suggested_tool": "resolve_join",
      "suggested_args": {
        "entity_a": "invoice",
        "entity_b": "workspace",
        "name": "invoice_workspace"
      }
    }
  }
}
```

Cascade reads `recovery.suggested_tool` and `suggested_args.name`, calls `resolve_join` with the disambiguating canonical-join name, and continues. No guessing, no hallucinated SQL.

***

## Troubleshooting

* **Windsurf doesn't list `schemabrain` in its MCP UI** — confirm `~/.codeium/windsurf/mcp_config.json` exists and contains the entry. Check the MCP status in Windsurf's settings panel.
* **`uvx` not on PATH** — install with `pip install uv` (or `brew install uv`). Without `uvx`, the wizard falls back to the installed absolute path.
* **`postgresql://` URL fails with `ModuleNotFoundError`** — use `postgresql+psycopg://`. `init` auto-rewrites with a one-line confirmation.
* **`onnxruntime` install fails on Apple Silicon + Python 3.12** — downgrade to Python 3.11 or pass `--no-embed` to skip the embeddings layer.

Full setup reference: [`docs/setup.md`](../setup.md) (wizard) · [`docs/setup/manual.md`](manual.md) (manual flow, logs, troubleshooting).