sql-steward MCP server

[!IMPORTANT]

This repository has moved into the Governed Agent Stack monorepo.

Active development is now at packages/sql-steward/.

This repo is archived and read-only. Its full commit history is preserved here;

new work, issues and releases happen in the monorepo.

sql-steward

<!-- mcp-name: io.github.Pawansingh3889/sql-steward -->

Part of the Governed Agent Stack: free, on-prem building blocks for an AI agent you can point at a real database and audit.

A governed SQL gateway for AI agents, exposed over the Model Context Protocol. The agent never gets a connection string and never writes SQL. It calls typed tools; sql-steward compiles every query from a semantic layer you control, refuses blocked PII before the query runs, and returns rows. Same tools across SQL Server, Postgres and SQLite.

Most SQL MCP servers hand the model a run_sql tool and try to catch the bad queries on the way out. sql-steward removes the tool. There is no path from a prompt to raw SQL at your database, because the only thing the agent can do is name an entity or a metric and pick from allow-lists you wrote.

See it defend a database live. The governed vs ungoverned demo runs the same request through a naive run_sql agent, which leaks customer PII and empties a table, and through sql-steward, which refuses it at compile time.

Three guarantees

1. Read-only by construction. There is no run_sql, query, or execute tool. The compiler can only ever build a SELECT, so a write isn't blocked, it's unrepresentable.
2. PII refused before retrieval. Every field can carry a PII tag. If a request touches a category your policy blocks, sql-steward refuses with a structured reason before any SQL is compiled or run.
3. Auditable. Every call, refusal and error can be recorded in a tamper-evident, hash-chained log via agent-blackbox, with audit-verify to prove nothing was rewritten.

See it in 10 seconds

pip install sql-steward      # or: pipx install sql-steward
sql-steward demo            # zero config, no API key, no agent, SQLite

1) get_metric('mrr_total', dimensions=['plan'])  -> safe aggregate
   compiled: SELECT subscriptions.plan, SUM(subscriptions.mrr) AS mrr_total
             FROM subscriptions GROUP BY subscriptions.plan LIMIT 1000
   {'plan': 'pro', 'mrr_total': 297.0}
   {'plan': 'team', 'mrr_total': 598.0}

2) get_metric('mrr_total', dimensions=['customers.country'])  -> auto-join
   compiled: ... INNER JOIN customers ON subscriptions.customer_id = customers.id ...

3) get_records('customers', fields=['id','email'])  -> PII refusal
   refused: {"kind": "pii_blocked", "detail": "Field 'customers.email' is tagged
             EMAIL_ADDRESS, which this policy refuses."}

The semantic layer

This YAML is the entire contract between the agent and your database. Review it like code.

dialect: postgres

Shortened. The full README is on GitHub.