How to connect Claude or Cursor to your database with schema context

If you use Claude Code, Claude Desktop, or Cursor and want your AI agent to actually understand your database schema — not just blindly run queries — this is the setup guide.

Pretensor is a Python package that introspects your database (Postgres, Snowflake, or BigQuery), builds a schema knowledge graph on disk, and exposes it to your AI editor through the Model Context Protocol. Your agent gets tools like context, traverse, impact, and detect_changes without you ever pasting DDL into chat.

Here’s how to go from zero to agent-aware schema in about five minutes.

Step 1: Install Pretensor

pip install pretensor

One dependency. Pretensor uses Kuzu as its embedded graph database — no separate graph server, no Docker, no cloud account. Everything runs locally.

For Snowflake or BigQuery, install the extras:

pip install 'pretensor[snowflake]'    # Snowflake
pip install 'pretensor[bigquery]'     # BigQuery

Step 2: Index your database

pretensor index postgresql://user:password@host:5432/dbname

This connects to your database, reads information_schema, classifies tables (fact, dimension, bridge), discovers relationships (both explicit FKs and inferred joins), clusters related tables, and writes the result to a Kuzu graph at .pretensor/ in your current directory.

What’s happening under the hood:

• Table classification runs deterministically (no LLM) — column names, types, and patterns determine whether a table is a fact table, dimension, bridge, or reference table.
• Foreign keys are read directly from the database catalog.
• Inferred joins are discovered by matching column names and types across tables (e.g., any column named customer_id of type integer in two tables is flagged as a potential relationship).
• Community detection (Louvain) groups related tables into clusters — your sales tables, your billing tables, your user tables.

The whole process takes seconds for a typical schema (hundreds of tables). Your schema data never leaves your machine.

For Snowflake:

pretensor index snowflake://user:password@account/warehouse/database

For BigQuery:

pretensor index bigquery://my-project-id/dataset-name

You can index multiple databases into the same graph — they coexist and traverse finds cross-database join paths when column names and types match.

Step 3: Wire it to your editor

pretensor serve --config-only

This prints the mcpServers JSON block you need. Merge it into your editor’s MCP config file:

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "pretensor": {
      "command": "pretensor",
      "args": ["serve"],
      "cwd": "/path/to/your/project"
    }
  }
}

Cursor (.cursor/mcp.json in your project root):

{
  "mcpServers": {
    "pretensor": {
      "command": "pretensor",
      "args": ["serve"],
      "cwd": "."
    }
  }
}

Claude Code (.mcp.json in your project root or ~/.claude/.mcp.json):

{
  "mcpServers": {
    "pretensor": {
      "command": "pretensor",
      "args": ["serve"],
      "cwd": "/path/to/your/project"
    }
  }
}

The --cwd should point to the directory where .pretensor/ lives — the same directory where you ran pretensor index.

Restart your editor. The tools appear automatically.

Step 4: What you can now ask your agent

Once the MCP server is running, your agent has access to 12 tools. Here’s what changes:

Before Pretensor:

You: “How many orders were placed last month?” Agent: (runs SQL, guessing column names, maybe joins wrong)

After Pretensor:

You: “How many orders were placed last month?” Agent: (calls context(table="orders") → sees columns, relationships, cluster → writes correct query on first try)

Some questions that work now but didn’t before:

• “Show me all tables related to users” → Agent calls context(table="users"), sees FK edges and cluster membership.
• “How do I join the billing tables to the user tables?” → Agent calls traverse(from="invoices", to="users"), gets the join path.
• “What changed in the schema since last time?” → Agent calls detect_changes, sees the diff.
• “If I rename orders.customer_id, what breaks?” → Agent calls impact(source="orders", column="customer_id"), gets the downstream dependency chain.
• “Which tables are stale?” → Agent checks the indexed timestamps vs. current schema.

The agent handles schema reasoning. You review the SQL.

Step 5: Stay in sync (the reindex loop)

Databases change. Columns get added, renamed, dropped. The agent needs to know.

After a schema migration:

pretensor detect_changes   # see what changed — diff against last index
pretensor reindex          # refresh the graph from the live database
pretensor serve            # restart (or your editor auto-restarts)

The detect_changes step is optional — reindex alone is enough to refresh. But running detect_changes first lets the agent tell you what moved, which is useful when reviewing migrations.

Multiple databases

Already indexed Postgres for the app and Snowflake for analytics?

pretensor index postgresql://user:pass@host:5432/appdb
pretensor index snowflake://user:pass@account/warehouse/analytics
pretensor serve --config-only

Both land in the same graph. The list_databases tool shows both. traverse finds cross-DB join paths. One MCP server, one agent, one graph.

Quick troubleshooting

“The tools don’t appear in my editor” — Check that cwd in your MCP config matches the directory with .pretensor/. Run pretensor serve directly (without --config-only) to see if it starts without errors.

“I get ‘no graph found’” — Run pretensor index first. serve expects a graph at .pretensor/ in the working directory (or the path you pass via --graph-dir).

“The agent keeps using old column names” — Run pretensor reindex after schema changes. The graph is a snapshot; it doesn’t auto-refresh.

“I indexed but the agent still asks me for DDL” — Some agents need prompting to use new tools. Try: “Use the Pretensor MCP tools to explore my database schema.”

Next: read the full quickstart for advanced options, or the MCP tools reference for a complete tool list.