Provides a security-hardened gateway for querying PostgreSQL databases, enforcing read-only access, PII masking, rate limits, and human-approved write operations via expiring tokens.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Safe DB Gateway Show me the top 5 customers by total spend"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A security-hardened MCP (Model Context Protocol) gateway that lets AI agents query a PostgreSQL database without the ability to destroy it, leak it, or be tricked into either. Read-only by default, PII-masked at the view layer, rate-limited, quarantined on abuse — and writes only through human-approved, expiring, single-use tokens.
The problem it solves: giving an LLM a raw database connection is a loaded gun — hallucinated tables, leaked PII, prompt-injected DROPs. This gateway puts a policy-enforcing membrane between the agent and Postgres, with evidence (audit trail) for everything that happens.
Layer | What it does |
AST guardrail ( | Blocks multi-statements, writable CTEs, dangerous functions ( |
PII barrier |
|
Least-privilege roles | Per-keycard Postgres roles ( |
Read-only sessions | Read path runs |
Rate + compute limits | 30 queries/min, 15s compute budget per 10 min ( |
Circuit breaker | 3 violations → 15-min write quarantine, persisted in Postgres so restarts can't bypass it |
HITL mutations | Propose → human operator key → expiring (5-min) HMAC-signed single-use token → execute |
Audit + alerting | Append-only JSON-lines |
Related MCP server: PostgreSQL MCP Server
One default_role line in roles.yaml sets the whole deployment's access until restart. Forks edit YAML, never code.
Role | Reads | Propose | Approve | Manage |
| ✅ allowlisted tables, PII masked | ❌ | ❌ | ❌ |
| ✅ | ✅ on listed tables | ❌ (proposer ≠ approver) | ❌ |
| ✅ all business tables | ✅ | ✅ | ✅ (quarantine reset, audit) |
Rules that never bend, for any role: restricted tables stay blocked unless explicitly granted, and schema destruction (DROP/ALTER/…) is rejected by the AST layer. A missing or broken roles.yaml fails closed to reader.
Prerequisites: Python 3.10+, Docker.
python setup.py init --demo # writes .env with fresh secrets
python setup.py up # starts Postgres, provisions everythingThen paste the printed block from mcp-servers.json into your Claude Desktop config. That's it — safe_query("SELECT * FROM track LIMIT 5") should return masked Chinook rows.
Against your own database: python setup.py init (wizard) or set DB_HOST/DB_PORT/DB_NAME/DB_SEED=empty — table-specific steps degrade gracefully with SKIP messages.
Tool | Role | Description |
| all | Validated read-only query, PII-masked, capped at 100 rows / 2s |
| all | Allowlisted tables (prevents hallucinated names) |
| all | Columns, types, primary keys |
| editor, admin | Dry-run plan + expiring proposal token, executes nothing |
| admin | Executes a proposal with the operator approval key |
| all | Health, circuit-breaker state, quotas |
| all | Last N audit events (never quarantined) |
| admin | Clear quarantine without restarting |
.env — connection strings, generated secrets, GATEWAY_ROLE, thresholds. Never committed (see .gitignore). Server-side only.
roles.yaml — role definitions and table grants. Your access policy lives here; the gateway only enforces it.
docker-compose.yml — Postgres 16 (scram-sha-256, Chinook seed on first init).
Threats closed and tested: scalar-function file access, PII extraction via SQL functions, superuser runtime connections — see safe-db-gateway_security_report.md and the 22-test suite.
Current boundary is the machine: over stdio there is no per-user auth — whoever holds .env and the MCP config holds the keycard in GATEWAY_ROLE. The trust-auth warning in provisioning (setup_roles.py step 5) must be resolved before any shared deployment.
Roadmap: per-caller auth (API keys → OIDC), HTTP/SSE transport with TLS, per-request tenant RLS, forensic audit queries — see docs/transport_migration_checklist.md.
$env:PYTHONPATH='C:\DB_MCP' # or export PYTHONPATH=/path/to/repo
python test_chinook_gateway.py # 22 end-to-end tests against live Postgres
python -m unittest discover -s testsCovers: injection/CTE/restricted-table rejections, PII masking incl. bypass attempts, HITL lifecycle, token expiry/forgery, durable quarantine + restart survival, read-survives-quarantine rescoping, role enforcement at tool and DB layers, fail-closed config, RLS passthrough, pool ceilings.
src/db_mcp/ gateway package (server, database pools, audit, config)
src/db_mcp/guardrails/ ast_guard, executor, circuit_breaker
scripts/setup_roles.py provisioning (views, roles, RLS, state table, keycards)
setup.py init wizard + up orchestrator
roles.yaml access-level definitions (the policy file you own)
docker-compose.yml local Postgres stack
docs/ transport migration checklist
tests/ legacy SQLite unit suite
test_chinook_gateway.py primary end-to-end suite (22 tests)pip install -r requirements.txt — sqlglot, pydantic, mcp, psycopg2-binary, python-dotenv, pyyaml.
This server cannot be deployed
Safe, read-only Postgres and MySQL access for AI agents. Audit log + column-level controls.
Query PostgreSQL databases in plain English — LLM-generated, safety-validated SQL.
Deterministic safety, correctness & cost gate that vets Postgres SQL before your AI agent runs it.
Query 40 databases from Claude, ChatGPT, or Cursor — on any device. Read-only, encrypted, audited.
