Schemabrain

Give them SchemaBrain instead — a read-only trust and intelligence layer where the agent never writes SQL, PII is refused before the query runs, and every call lands in a tamper-evident audit log.

Works with Claude Desktop · Claude Code · Cursor · Windsurf · any MCP host

SchemaBrain compiles every query from definitions you control — no path from a prompt to raw SQL at your database.

Three guarantees that close the trust gap between AI agents and your database:

- Read-only by architecture— twelve MCP tools, none of which can write. Noexecute()tool, noquery()tool, no path from agent prompt to a write at your database.
- PII-aware refusal at retrieval— PII tags propagate from the physical schema through joins and metrics. If a query touches a blocked category, SchemaBrain refuses before the database is queried.
- Cryptographic audit chain— every call, refusal, and recovery is recorded in a SHA256-hashed append-only log (best-effort: a disk-full or no-writer configuration logs a warning and continues rather than failing the query).audit verifyexits non-zero if any past row was rewritten.

→Full session, with the SQL and results

uvx schemabrain init # then: Cmd+Q Claude Desktop, relaunch, and ask: "list the entities SchemaBrain knows about" # prefer a persistent install? pipx install schemabrain (or) pip install schemabrain

Cost:$0to run the bundled demo (pre-curated pack, no API key) · ~$0.03 to LLM-index a fresh 84-column schema ·$0to re-index unchanged schemas. Detail inSample session.

uvx schemabrain init # zero-install: runs the wizard in one shot # or install persistently first: pipx install schemabrain # (or) pip install schemabrain schemabrain --version

Source install (git clone+uvsync --extra dev) is documented indocs/setup.md.

SchemaBrain init — activation wizard [1/7] Source check ✓ source reachable + read-only [2/7] Index schema ✓ 12 tables, 84 columns indexed [3/7] Curate entities ✓ 12 entities applied (bundled demo pack) [4/7] Curate metrics ✓ 5 metrics applied (bundled demo pack) [5/7] Curate joins ✓ 11 canonical joins applied (bundled demo pack) [6/7] Wire host ✓ wrote schemabrain entry to claude_desktop_config.json (default; switch with --host claude-code|cursor|windsurf|manual) [7/7] Next ✓ restart your MCP host, then ask: "list the entities SchemaBrain knows about"

Full wizard reference (stages explained, flags, dbt auto-detection,--print-onlyfor non-Claude-Desktop hosts,--no-entities/--no-metrics/--no-joinsopt-outs, cost-cap pauses):docs/setup.md.
-

If Claude callslist_entitiesand reportsuser,order, etc., you're done. If not, seeTroubleshooting.

After the wizard,schemabrain inspectshows what the agent has andschemabrain tailstreams every tool call live — seedocs/operations.md.

schemabrain init --url-env DATABASE_URL --emit-yaml-dir ./schemabrain # → ./schemabrain/pii_policy.yaml + entities/ + metrics/ + joins/

Edit a file,schemabrain apply ./schemabrain,schemabrain checkto validate, restartserve. There is noschemabrain.yaml— config is CLI flags +SCHEMABRAIN_env vars (auto-loaded from.env) + that YAML tree. Full map:Your project.

schemabrain audit verify # exit 0 = chain clean

{ "status": "error", "kind": "ambiguous_time_dimension", "recovery": { "suggested_tool": "get_metric", "suggested_args": {"time_dimension": "order.placed_at"} } }

pip install "schemabrain[ui]" schemabrain dashboard # → http://127.0.0.1:7878

- Knowledge Graph(/graph) —how does my schema actually connect?Entities as nodes, canonical joins as edges (solid for declared FKs, dashed for log-mined), PII-bearing entities flagged, and refusal hotspots highlighted, with declared-FK cardinality shown on the highlighted join path — the schema as a graph, not a table list.
- Overview(/overview) — the home surface: entity / metric / join / catastrophic-PII counts at a glance.
- Entities(/entities) — a sortable index; drill into any entity's columns, PII, metrics, and canonical joins.
- Data Dictionary(/dict) — every table, column, type, PII class, join, and metric, with one-click Markdown export (the same artifactschemabrain docswrites).
- PII matrix(/pii) —which columns carry sensitive data?A heatmap with one row per classified column and one cell per PII category, each column tagged block / redact / allow by its advisory band. Columns in a catastrophic-leak category (credential,payment_card,government_id) are hard-blocked regardless of policy and pinned to the top — so you catch apayment_cardcolumn hiding insideusersbefore you point an agent at a new schema, and see at a glance what trips the default--pii-blockpolicy. Select any row to drill into its entity's columns, metrics, and joins.
- Refusals(/refusals) —what did SchemaBrain block, and what did the agent see?A chronological feed of held calls; expand any row to reveal the full envelope inline — the reason that fired (pii_blocked,allowlist_violation,fragment_unsafe,cost_cap_exceeded,ambiguous_resolution,schema_drift), the exact category set that intersected the policy, and the structurederror.recovery(suggested tool + args) the agent got back to recover. Use it to triage "the agent says it can't access that" and to review whether those hints actually helped.
- Audit Viewer(/audit) —is the audit chain still intact?The visual face of the tamper-evident log: every tool call writes exactly one row — whatever the outcome — anchored bychain_hash = sha256(prev_hash || canonical(row)). An integrity strip readsnot verified this sessionuntil you run a pass, thenverified · n/N intact(or flagsN rows edited after write); theVerifybutton re-walks the chain server-sideandrecomputes each visible row's RFC-6962 Merkle inclusion proof in your browser. Selecting a row opens the full body (tool, status, cost class, PII categories, fingerprint,chain_hash, and the proof ladder up to the root). Reload to pick up new calls.
- Policy(/policy) — the block / redact / allow grid the firewall enforces, with the always-on catastrophic-leak floor disclosed (it can't be removed). Changes are made via copy-the-CLI actions — the dashboard never writes.
- Drift(/drift) — config and enrichment drift the store can detect, each with a copy-the-CLI fix.

Knowledge Graph — your schema as the entity-relationship projection the semantic layer compiles joins against; catastrophic-PII entities flagged, the canonical join path traced.

Overview — the whole boundary on one screen: what's bound, what's protected, what's drifted.

PII matrix — which columns carry sensitive data, and what the default policy blocks.

Refusals — every blocked call, the reason that fired, and the recovery hint the agent received.

Audit Viewer — the tamper-evident chain, verified server-side down to each row's hash linkage.

Entities — every business entity bound out of the raw schema, with PII exposure and join counts.

Data Dictionary — every table, column, type, and join, exportable to Markdown for your repo or wiki.

Policy — the block / redact / allow grid the firewall enforces, with the always-on floor disclosed.

Drift — config and enrichment drift the store can detect, each with a copy-the-CLI fix.

Claude:(callsget_metric(name="usage_volume", group_by=["plan.title"]). The metric anchors onusage_event; reachingplanwould need a join that isn't in the schema, so it refuses:)

{ "status": "error", "error": { "kind": "unreachable_entity", "message": "entity 'plan' is not reachable from metric anchor 'usage_event'; no canonical join exists. Run schemabrain joins suggest to surface candidate joins.", "recovery": { "suggested_tool": "resolve_join", "suggested_args": { "entity_a": "usage_event", "entity_b": "plan" } } } }

(Claude confirms at the join layer —resolve_join("usage_event", "plan")returnskind: no_canonical_join.usage_eventscarries onlyworkspace_id, never aplan_id, and no table bridges the two.)

SELECT p.title AS plan_tier, SUM(si.unit_price_cents  si.seats) / 100.0 AS revenue -- prices stored in integer cents FROM public.subscription_items si JOIN public.subscriptions s ON si.subscription_id = s.id JOIN public.plans p ON s.plan_id = p.id GROUP BY p.title ORDER BY revenue DESC;

- Contracted, not collected.This is subscription line-item revenue (seats × unit_price_cents), not paid invoices. For billed totals, thetotal_revenuemetric anchors oninvoicesinstead.
- Integer cents.unit_price_centsis stored as an integer; the/ 100.0converts to currency.

The differentiator is whatdidn'thappen: most LLM-over-database tools, asked for usage-by-plan, would confidently emitJOIN plans p ON usage_events.plan_id = p.idagainst aplan_idcolumn that doesn't exist. SchemaBrain refused —get_metricreturnedkind: unreachable_entitywithrecovery.suggested_tool: resolve_join, not prose. The agentacted on the structured recovery contract programmaticallyinstead of fabricating a join. Refusal-not-fabrication is the safety mechanism, demonstrated live.

Cost.~$0.0004/column with Claude Haiku 4.5 (cryptic-name columns can opt into Sonnet 4.6 via--enable-sonnet). The bundled 12-table fixture (84 columns, 12 entities + 5 metrics + 11 joins) ships pre-curated, so the demo path applies it for$0— no API key. Indexing those 84 columns with LLM column descriptions comes to about$0.03. The Pagila DVD-rental sample (87 columns after partition deduplication) is the directly measured reference —$0.0299 in 105s. Re-indexing an unchanged schema is$0— content-addressable fingerprinting skips the LLM call entirely.