Schemabrain

What Arun-kc/schemabrain MCP server does

Arun-kc/schemabrain MCP server places a controlled semantic layer between an MCP client and a Postgres database. The agent works with curated entities, joins, and metrics rather than submitting arbitrary SQL. The server compiles database queries from those definitions, so there is no exposed write or general-purpose query tool described in the project material.

The design is intended for read-only analytical access. It can reject a request when the requested relationship is not represented in the configured schema instead of inventing a join. It also applies PII and secret-category restrictions at retrieval time. Tags from the physical schema can propagate through joins and metrics, allowing the server to refuse a metric before the database is contacted when it crosses a blocked category.

Each tool call, refusal, and recovery is added to an append-only audit log using SHA-256 hashes. The audit verify command can detect whether an earlier log row was rewritten.

How it works

A live Postgres schema is indexed into SchemaBrain, then a semantic layer describes the entities, metrics, and canonical joins that agents may use. The bundled demo includes a pre-curated YAML layer; for another database, entity curation can be performed with the project’s command-line workflow and an optional Anthropic API key.

At runtime, an MCP host invokes the available tools. For example, the README describes list_entities, get_metric, and resolve_join behaviors. A metric request is checked against the configured definitions and policy tags before the resulting query is run. If the requested relationship is unreachable, the response can identify the problem and suggest recovery through a join-resolution operation.

The audit chain is best-effort. If the disk is full or no audit writer is configured, the server logs a warning and continues rather than failing the database query.

Setup and configuration

Arun-kc/schemabrain MCP server can be started through the schemabrain Python package. The documented zero-install entry point is uvx schemabrain init; persistent installation is also documented with pipx install schemabrain or pip install schemabrain.

The init wizard asks for a Postgres connection URL, or can start a local demo Postgres container with the bundled fixture. It indexes the source, applies available entities, metrics, and joins, and writes an MCP host configuration. Claude Desktop is the default host in the wizard, with options for Claude Code, Cursor, Windsurf, or manual configuration. The host must be restarted after configuration changes.

An Anthropic API key is optional. The demo path can use its bundled semantic definitions without one. On a user database, the README says entity suggestions can be generated later with schemabrain entities suggest --apply after providing a key.

Tools and capabilities

• Exposes twelve read-only MCP tools.
• Compiles queries from controlled semantic definitions.
• Represents entities, metrics, and canonical joins.
• Refuses blocked PII and secret categories before retrieval.
• Detects unreachable relationships instead of fabricating joins.
• Records calls, refusals, and recoveries in a SHA-256 audit chain.
• Provides inspection, audit verification, and operational command-line workflows.

Limitations and notes

The project is marked beta at version 0.6.0 in the supplied material. Postgres is the supported source connector. SQLite is used for the local store, while SQLite, Snowflake, BigQuery, and MySQL source connectors are listed as roadmap items rather than current support.

The system does not expose write operations according to the README, but its safety depends on the definitions and policy categories configured by the operator. Audit recording is not fail-closed: disk or writer problems produce a warning and allow the query to continue. A fresh schema may require semantic curation, and LLM-based indexing can incur a cost; the bundled demo and unchanged-schema re-indexing are described as having no cost.