Claude Code

60-second wiring: install SchemaBrain, run init — the wizard shells out to claude mcp add for you.

SchemaBrain + Claude Code

60 seconds: install SchemaBrain, run schemabrain init, the wizard shells out to claude mcp add for you. Restart Claude Code, ask about your database.

SchemaBrain is the trust and intelligence layer between Claude Code and your Postgres database — twelve read-only MCP tools, validated metrics, tamper-evident audit. Works on macOS, Linux, and Windows wherever the claude CLI is on PATH.

---

Install

uvx schemabrain init --host claude-code
# 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 shells out to claude mcp add to register the server. We use the CLI rather than editing ~/.claude.json directly because Anthropic’s supported registration path validates the entry and is robust against schema changes.

Verify

claude mcp list
# schemabrain  uvx schemabrain==0.6.0 serve --url-env SCHEMABRAIN_DATABASE_URL --store-path ...

Then in a new Claude Code session:

list the entities SchemaBrain knows about

If Claude 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 walks you through exercising each load-bearing mechanism (read-only, PII refusal, audit chain, structured recovery) in ~10 minutes.

---

If the shell-out failed

schemabrain init prints the exact claude mcp add ... command it tried. You can copy-paste and run it yourself:

claude mcp add \
  -e SCHEMABRAIN_DATABASE_URL=postgresql+psycopg://user:pass@host:5432/db \
  schemabrain -- \
  uvx schemabrain==0.6.0 serve --url-env SCHEMABRAIN_DATABASE_URL --store-path ./schemabrain.db

The -- separator is load-bearing — without it, Claude Code’s parser would try to interpret --url-env as one of its own flags. The SCHEMABRAIN_DATABASE_URL env-var name is the wizard’s default — it’s prefixed to avoid colliding with any app-level DATABASE_URL you already have in the host’s environment.

---

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 and errors ship typed contracts Claude can act on programmatically. Details in /mechanism/structured-recovery.

Sample interaction

You: Using SchemaBrain, which plan tier drives the most revenue?

Claude: (calls find_relevant_entities("revenue by plan") → picks subscription_item → resolve_join(subscription_item, subscription) → resolve_join(subscription, plan) → get_metric(name="total_revenue_real", group_by=["plan.title"]))

Enterprise leads with $379,620 in contracted revenue, ahead of Pro ($539) and Free ($54). Path fully resolved via FK constraints (confidence: HIGH).

The trust signal comes from the v1.2 envelope — see /mechanism/trust-signal for how Claude knows whether to qualify its answer.

---

Troubleshooting

• claude: command not found — install Claude Code from https://claude.com/claude-code or use --host manual and paste the snippet into whatever MCP host you’re using.
• postgresql:// fails with ModuleNotFoundError — use postgresql+psycopg://. init auto-rewrites the scheme with a one-line confirmation.
• onnxruntime install fails on Apple Silicon + Python 3.12 — downgrade to Python 3.11 or pass --no-embed.

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