MCP tool reference

Twelve Pydantic-typed MCP tools split across two layers — physical schema and semantic layer. Every response carries a token_estimate and a Charter-conformant envelope.

SchemaBrain exposes twelve Pydantic-typed MCP tools split across two layers:

• Physical-schema tools (5) — read directly from the indexed schema. Always available after schemabrain index.
• Semantic-layer tools (7) — read curated entities, canonical joins, and metrics. Available once the operator has confirmed at least one entity (schemabrain entities suggest --apply or schemabrain init).

Every response includes a token_estimate so agents can budget context. Every envelope follows the Charter status taxonomy (success, empty, partial, degraded, error, refused) with follow_up_hints to chain the next call.

Typical call order for an agent answering a business question against a curated schema: find_relevant_entities → describe_entity → list_metrics → get_metric. Fall back to the physical-schema tools (find_relevant_tables → describe_table) when the semantic layer is empty or the question is purely structural. The MCP server’s initialize.instructions field steers compliant hosts (Claude Desktop, Claude Code, Cursor, Windsurf) toward this order automatically — see the _SERVER_INSTRUCTIONS block for the canonical text.

Physical-schema tools

find_relevant_tables

Embedding-cosine retrieval over indexed columns.

describe_table

Full structural + semantic dump of one table.

describe_column

Drill into one column with bidirectional FK graph.

suggest_joins

Shortest FK-graph join paths between table pairs.

get_example_queries

Real SQL observed against a table from pg_stat_statements.

Semantic-layer tools

find_relevant_entities

Embedding-cosine search restricted to entities.

list_entities

Every confirmed entity with bound table + identity.

describe_entity

Bound table, identity column, and full column list.

list_metrics

Every declared metric with anchor entity + measure.

get_metric

Compiles + runs a pre-declared metric.

list_joins

Every confirmed canonical relationship.

resolve_join

Canonical join between two entities — paste-ready.

Building your own agent against this surface

If you’re wiring SchemaBrain into a custom MCP host (not Claude Desktop / Cursor / Windsurf / Claude Code), the fastest path is the bundled Anthropic SDK demo:

examples/anthropic_demo.py

~250 LOC that spawns schemabrain serve over stdio, drives Claude Haiku through the standard tool-use loop, and prints the transcript. Drop-in template for any MCP-stdio client.

MCP Inspector workflow

Hit every tool against your indexed schema before wiring an LLM — fastest way to audit shapes during integration.

Related

MCP Charter v1.2

The contract every tool implements — status taxonomy, envelope shape, recovery hints.

Read-only by architecture

Why no tool accepts arbitrary SQL.

Structured recovery

What an agent gets back when a tool refuses.

Architecture

Where these tools fit in the pipeline.