LabscoMCP early access ↗
Arun-kcMCP SERVER

schemabrain

Give an agent your Postgres schema without giving it a connection string — twelve read-only tools, none of which can write or run arbitrary SQL.

by Arun-kc ↗Relational SQL DatabasesCommunity

LABSCO SUMMARY

It refuses rather than inventing the join.

The behaviour worth the setup is what happens when a question cannot be answered: the tool returns a structured refusal naming the reason and suggesting the recovery call, instead of fabricating a relationship that looks plausible. Add the PII refusal happening before the query runs, and a SHA256-hashed append-only audit log that audit verify exits non-zero on if a past row was rewritten, and you get a surface you can point at a production database. The cost is curation — the semantic layer only exists after an operator confirms entities.

What it is

A read-only layer between an agent and a database. Queries are compiled from definitions you control — entities, canonical joins and declared metrics — so there is no path from a prompt to raw SQL at your database.

What you get

  • Physical-schema tools work as soon as you have indexed: find_relevant_tables retrieves by embedding cosine, describe_table dumps one table, describe_column drills in with the bidirectional FK graph
  • suggest_joins returns the shortest FK-graph paths between table pairs; get_example_queries returns real SQL observed against a table from pg_stat_statements
  • The semantic layer opens once an entity is confirmed: find_relevant_entities, list_entities and describe_entity cover curated entities and their identity columns
  • list_metrics and get_metric declare and run pre-defined metrics; list_joins and resolve_join return canonical relationships, paste-ready
  • Every response carries a token_estimate so an agent can budget context, and a status of success, empty, partial, degraded, error or refused with follow_up_hints for the next call
  • PII tags propagate from the physical schema through joins and metrics — a query touching a blocked category is refused before the database is reached

Requirements

The PyPI package schemabrain, version 0.6.0, run as uvx schemabrain serve over stdio, or uvx schemabrain init to walk the whole setup. DATABASE_URL holds the Postgres connection string and stays in the environment, so credentials never appear in argv or logs; --store-path points at the SQLite store built by schemabrain index, defaulting to ./schemabrain.db. Postgres is the supported source today.

Setup effort

One command plus credentials — uvx schemabrain init, then supply credentials

See installation options