Why your AI agent needs a schema graph, not just SQL access

Agents hallucinate joins on 200-table schemas. Not because the underlying model is bad, but because pasting a full DDL into a context window is the wrong primitive. The agent gets the column names but not the business semantics, the FK relationships, or any sense of what breaks downstream when something changes. Raw SQL access is a start — it is not enough.

The problem with raw SQL access — and what a database schema MCP server should actually do

The Model Context Protocol makes it straightforward to expose a database to an AI agent. Wire up list_tables, describe_table, and execute_query, and you have a working MCP postgres server in an afternoon. That pattern covers a lot of ground — ad hoc exploration of a small schema, one-off queries, quick lookups.

It breaks down around 30 tables. At 200, it falls over.

The failure mode is structural: thin MCP wrappers hand the agent a pile of DDL and expect it to reason about relationships on the fly. The agent doesn’t know which foreign keys are semantically meaningful, which join paths are traversed by production queries, or which tables are lookup references versus transactional fact tables. So it guesses. It writes joins that look plausible but miss a bridge table. It treats customer_id as unique when it isn’t. It has no way to answer “what breaks if I rename this column?” because it has no model of the graph — only the text of the schema.

The “put it all in the prompt” approach also doesn’t compose. You can’t ask an agent to reason about cross-schema impact when each schema is its own raw blob. And you hit context limits before you finish describing a production warehouse.

What a schema graph gives you — AI agent database context that compounds

A knowledge graph of your database is not a different interface to the same information. It is a different information structure.

Four things become possible that aren’t possible with raw SQL access:

FK traversal via traverse. Given two tables — say orgs and invoices — the traverse tool returns every FK-backed and inferred join path between them, with the JOIN SQL included. The agent doesn’t need to reason about the path; it reads a precomputed answer. No LLM in that path. Deterministic.

Join-path discovery via schema. The schema tool returns a per-table view that includes not just columns and types but foreign key edges — both explicit (database-declared FKs) and inferred (name-pattern + signature matching). An agent looking at orders sees that it connects to customers, products, and promotions, and in which direction. That context is the difference between a correct join and a hallucinated one.

Impact analysis via impact. Ask which tables are reachable downstream from a given column via FK edges. This is the blast-radius tool — useful for migrations, refactors, and schema reviews. More on this in the concrete example below.

Table classification via table_context. Pretensor classifies each table into a type — fact, dimension, bridge, lookup, log — using deterministic heuristics over column patterns and relationship counts. An agent that knows order_items is a fact table and countries is a lookup behaves differently than one treating all 200 tables as equivalent.

These four tools are part of a 10-tool MCP surface. All 10 are read-only. Schema-only by default — Pretensor reads catalog metadata, not row data.

How Pretensor works — model context protocol database integration in three steps

Just as GitNexus precomputes a graph over a codebase, Pretensor precomputes a graph over a database.

Index. Point Pretensor at a connection string. It introspects your schema — tables, columns, foreign keys, view definitions, check constraints — and writes a local state directory. No rows are read.

Graph. Pretensor builds a Kuzu knowledge graph from the introspected schema. FK-backed edges are declared from the database itself. Inferred edges come from name-pattern matching and optional embedding-augmented relationship discovery (opt-in extra). The graph is stored locally and reused across agent sessions.

MCP tools. Pretensor serves the graph over MCP. Connect Claude, Cursor, Cline, Continue, Zed, or Goose to the running server. The agent calls traverse, impact, schema, table_context, and six other tools. The graph answers. The database is not queried per-tool call.

pip install pretensor
pretensor index postgresql://USER:PASSWORD@HOST:5432/DBNAME
pretensor serve

Three commands. The quickstart in Getting started walks through the full flow, including MCP client configuration.

Pretensor runs on Python 3.11 / 3.12. Python 3.13 is not yet tested.

A concrete example: impact analysis with the impact tool

This is where schema introspection MCP becomes practically useful. Consider renaming orders.customer_id — a column that may be referenced by FK constraints, views, derived tables, or application code that joins through it.

Before: an agent with raw SQL access asks the database for the column definition. It knows the column exists. It doesn’t know what else depends on it.

After: the agent calls impact with table = "orders" and column = "customer_id".

{
  "tool": "impact",
  "arguments": {
    "table": "orders",
    "column": "customer_id"
  }
}

Pretensor traverses the FK graph outward from that column and returns the reachable tables:

{
  "source": "orders.customer_id",
  "reachable": [
    {
      "table": "order_items",
      "path": ["orders → order_items (order_id)"],
      "edge_type": "fk"
    },
    {
      "table": "shipments",
      "path": ["orders → shipments (order_id)"],
      "edge_type": "fk"
    },
    {
      "table": "returns",
      "path": ["orders → returns (order_id)"],
      "edge_type": "fk"
    },
    {
      "table": "customer_summary",
      "path": ["orders → customer_summary (customer_id)"],
      "edge_type": "inferred"
    }
  ],
  "edge_count": 4
}

The agent now knows that renaming orders.customer_id has downstream implications for four tables — three FK-declared, one inferred. It can surface that to the developer before the migration runs. No LLM guessing which tables might be affected; the graph answers from its precomputed edges.

This is what “database knowledge graph for AI” means in practice: the agent reads a structural answer, not a text blob. The difference compounds as schemas grow.

The full MCP tool reference — including all 10 tool signatures and their parameters — is at MCP tools reference.

Getting started

Install Pretensor from PyPI:

pip install pretensor

Index your database and start serving:

pretensor index postgresql://USER:PASSWORD@HOST:5432/DBNAME
pretensor serve

Then point your MCP client (Claude, Cursor, Cline, or any MCP-compatible host) at http://localhost:4300. The architecture docs explain how the Kuzu graph is structured and which edges are FK-declared versus inferred.

Pretensor is open core. The OSS version runs entirely on your laptop — no network egress after install, no accounts, no configuration beyond a connection string.

Read the docs → Star on GitHub →