postgres-nl-query

RLS/tenant-aware Postgres access for AI agents, as an MCP server. Five tools: list_tables, describe_table, query_sql, query_nl (NL→SQL via OpenRouter), explain_query.

Design doc: ../../docs/06-POSTGRES-NL-QUERY-MCP.md.

Safety model (defense in depth)

1. Connect with a least-privilege role. RLS policies on your DB apply to it automatically — that's the real guard.
2. Read-only by default (PG_WRITE_ALLOWED=false): query_sql rejects anything that isn't a single SELECT/WITH/EXPLAIN (static guard in sql-guard.ts), and runs it inside a BEGIN READ ONLY transaction.
3. Row cap + timeout: every read is wrapped in an outer LIMIT (PG_MAX_ROWS) and a statement_timeout (PG_STATEMENT_TIMEOUT_MS).
4. Tenant guard: set PG_TENANT_COLUMN/PG_TENANT_VALUE and NL→SQL is instructed to filter every tenant-scoped table (RLS still backs it).
5. Human-in-the-loop: PG_NL_REQUIRE_APPROVAL=true makes query_nl return the generated SQL without executing — the agent (or a human) then runs it via query_sql.

Run

cp .env.example .env   # set PG_URL (+ OPENROUTER_API_KEY for query_nl)
npm install
npm run build
node dist/server.js    # stdio MCP server

MCP client config (e.g. Claude Desktop / Code):

{
  "mcpServers": {
    "postgres-nl-query": {
      "command": "node",
      "args": ["/opt/postgres-nl-query/dist/server.js"],
      "env": { "PG_URL": "postgres://agent_readonly:...@host:5432/appdb", "OPENROUTER_API_KEY": "sk-or-..." }
    }
  }
}

Why it's differentiated

Generic Postgres MCP servers exist; this one is multi-tenant aware (per-tenant filtering), read-only-by-default with a real static guard + READ ONLY tx, and supports an approval gate for NL→SQL — the things enterprises need before letting an agent near production data.