SchemaBrain

Stop giving AI agents raw database connection strings.

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](#1-read-only-by-architecture-not-configuration) — twelve MCP tools, none of which can write. No execute() tool, no query() tool, no path from agent prompt to a write at your database.
• [PII-aware refusal at retrieval](#2-pii-aware-refusal-at-the-get_metric-tool-boundary) — 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](#3-tamper-evident-audit-log) — 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 verify exits non-zero if any past row was rewritten.

See it in action — ask for something the schema can't answer, and it refuses instead of fabricating a join:

You: *compute usage volume by plan tier*

SchemaBrain → agent: { "kind": "unreachable_entity", "recovery": { "suggested_tool": "resolve_join" } } — there's no plan_id on usage events, so it won't invent one.

Claude: I can't fake that join — here's contracted revenue by plan tier instead, which actually resolves. ✓

→ Full session, with the SQL and results

Watch it run — a live Postgres schema becomes a governed knowledge graph, the firewall computes the safe metric and refuses the leaks, and every call lands in a tamper-evident audit log. No agent, no API key:

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: $0 to run the bundled demo (pre-curated pack, no API key) · ~$0.03 to LLM-index a fresh 84-column schema · $0 to re-index unchanged schemas. Detail in Sample session.

Status: 0.6.0 (beta). Postgres supported today (the local store itself is SQLite). SQLite / Snowflake / BigQuery / MySQL source connectors on the roadmap.

Contents

Read next based on what you need:

Quickstart

Just want to see what it does? uvx schemabrain demo — one command, zero prompts. Builds the sample SaaS layer, then lets you open the dashboard or run a terminal firewall showcase. No API key, and no Docker for the dashboard / showcase paths. The steps below are for wiring SchemaBrain into your own agent against your own database.

Three steps from uvx schemabrain init to a working Claude Desktop integration. If you paste your own Postgres URL — no Docker needed, ~30s. Press Enter for the bundled demo and init invokes Docker + downloads a ~67 MB embedding model first time; ~45s once cached.

1. Install

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 + uv sync --extra dev) is documented in docs/setup.md.

2. Run the activation wizard

schemabrain init

init is a seven-stage wizard that takes you from "I have a Postgres database" to "Claude Desktop can answer questions about it" in one command. On first run it prompts for what it needs:

• A Postgres URL — paste your own connection string, or press Enter to spin up a local demo Postgres container with the bundled SaaS fixture (Docker is invoked automatically; idempotent on re-runs).
• An `ANTHROPIC_API_KEY` — optional. Skip and the wizard still wires Claude Desktop. On the demo path, entities + metrics + joins are pre-curated from a bundled YAML pack — the semantic layer works zero-config. On your own database, entity curation can run later via schemabrain entities suggest --apply once you have a key.

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-only for non-Claude-Desktop hosts, --no-entities / --no-metrics / --no-joins opt-outs, cost-cap pauses): docs/setup.md.

3. Restart Claude Desktop and ask

1. Quit Claude Desktop fully — Cmd+Q, not just close the window. The MCP config is only read on cold start.
2. Relaunch.
3. New conversation:

list the entities SchemaBrain knows about

If Claude calls list_entities and reports user, order, etc., you're done. If not, see Troubleshooting.

After the wizard, schemabrain inspect shows what the agent has and schemabrain tail streams every tool call live — see docs/operations.md.

Your project files

init writes just ./schemabrain.db (the local store — gitignore it) plus your host config. To tune the PII policy and semantic layer as editable YAML, re-run with --emit-yaml-dir:

schemabrain init --url-env DATABASE_URL --emit-yaml-dir ./schemabrain

→ ./schemabrain/pii_policy.yaml + entities/ + metrics/ + joins/

Edit a file, schemabrain apply ./schemabrain, schemabrain check to validate, restart serve. There is no schemabrain.yaml — config is CLI flags + SCHEMABRAIN_* env vars (auto-loaded from .env) + that YAML tree. Full map: Your project.

Safety guarantees

Six properties SchemaBrain enforces at the SQL boundary today:

1. Read-only by architecture, not configuration

The MCP surface exposes twelve tools — none of which can write. No execute(), no query(), no path from agent prompt to a write at your database, regardless of session state — the guarantee is structural, not a flag the agent can flip. schemabrain serve also pins default_transaction_read_only=on as belt-and-suspenders. Read-only by architecture →

2. PII-aware refusal at the get_metric tool boundary

Any get_metric touching a blocked PII category returns a refused envelope — the compiled SQL never runs and the refusal lands in mcp_audit. describe_entity enforces the same at the column level (blocked columns ship redacted=True). init blocks the catastrophic-leak set by default (credential,payment_card,government_id); --pii-block replaces the set, so widen by listing the full target. Detection is column-name pattern matching across twelve GDPR / CCPA / HIPAA / PCI categories; content-aware classification is on the roadmap. PII taxonomy & propagation →

3. Tamper-evident audit log

Every tool call writes one row to an append-only mcp_audit table — PII categories, content-addressable fingerprints, sha256 hash chain. audit verify re-walks the chain and exits non-zero if any past row was rewritten.

schemabrain audit verify   # exit 0 = chain clean

Tamper-evident audit chain →

4. Failure is a contract, not a string

Every non-success call — refused, error, or degraded — returns a structured recovery.suggested_args block, not a message to parse. PII blocks (status: "refused") ship the entity to ret