> ## 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.

# 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

```bash theme={null}
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

```bash theme={null}
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](../first-5-queries.md) 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:

```bash theme={null}
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`](/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 and errors ship typed contracts Claude can act on programmatically. Details in [`/mechanism/structured-recovery`](/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`](/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](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`](../setup.md) (wizard) · [`docs/setup/manual.md`](manual.md) (manual flow, logs, troubleshooting).