SchemaBrain + Cursor

60 seconds: install SchemaBrain, run schemabrain init, restart Cursor, ask the agent about your database.

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

---

Install

uvx schemabrain init --host cursor
# 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 ~/.cursor/mcp.json (Cursor's global config).

Resulting config entry

init writes an entry shaped exactly like Cursor's documented schema:

{
  "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"
      },
      "type": "stdio"
    }
  }
}

The explicit "type": "stdio" is written per Cursor's documented schema. Cursor accepts entries without it (stdio is the default), but explicit is safer when their schema evolves. 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 Cursor's env.

Restart Cursor

Quit Cursor fully (Cmd+Q on macOS) and relaunch. Cursor only reads mcp.json on startup.

Ask the agent

list the entities SchemaBrain knows about

If Cursor's agent 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.

Next: First 5 Queries walks you through exercising each load-bearing mechanism (read-only, PII refusal, audit chain, structured recovery) in ~10 minutes.

---

Project-local vs global

schemabrain init --host cursor targets ~/.cursor/mcp.json — install once, use across every project. If you want a per-project MCP entry, copy the same entry into .cursor/mcp.json at your project root; the wizard doesn't write project-local configs.

---

What you get

• 12 MCP tools, none of which can write. Full list in /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.
• Tamper-evident audit chain. Verify with schemabrain audit verify. Details in /mechanism/audit-chain.
• Structured recovery envelopes. Refusals ship typed contracts Cursor's agent can act on programmatically. Details in /mechanism/structured-recovery.

Sample refusal

When the agent attempts a metric that touches a blocked PII category:

{
  "status": "refused",
  "error": {
    "kind": "pii_blocked",
    "recovery": {
      "suggested_tool": "describe_entity",
      "suggested_args": {"name": "user"}
    },
    "pii_categories": ["credential"]
  }
}

The agent reads recovery.suggested_tool, pivots to describe_entity to find non-PII columns, retries. No human round-trip.

---

Troubleshooting

• Cursor doesn't list schemabrain in MCP — confirm the path Cursor reads (~/.cursor/mcp.json) and the entry shape. Cursor's MCP indicator is in the bottom status bar.
• 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.

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