Guarded Postgres MCP Server

An MCP server that lets Claude query and safely write to a Postgres database — built so it structurally cannot run DROP TABLE, leak PII, or silently return wrong data. Every guardrail is driven by one policy.yaml file, so the same server works for any client's database by editing config, not code.

Files

Related MCP server: Argos-MCP

Run it

docker compose up -d                 # start the demo Postgres (seeds itself)
python -m venv .venv && source .venv/Scripts/activate   # (Windows Git Bash)
pip install -r requirements.txt && pip install -e .
python scripts/smoke_test.py         # prove every tool works (normal + rejected)

Reproduce the metrics

python scripts/run_adversarial.py    # writes results.json
pytest tests/adversarial/ -v         # the same attacks as a formal test suite

Current run — 19 adversarial attacks, 0 succeeded, database intact (row count unchanged, target table still present). Categories: DDL, DML-via-read-tool, injection (stacked statements / comment smuggling / CTE writes), exfiltration, write authorization, and integrity. Every number regenerates from the command above.

Connect to Claude Desktop

See claude_desktop_config.example.json. The server speaks stdio (not HTTP), so Claude Desktop launches it as a subprocess — there's no URL or port. Point DATABASE_URL/WRITE_DATABASE_URL at your own Postgres and edit policy.yaml to match your schema.

Glossary

Terms introduced while building this, in plain language:

• MCP (Model Context Protocol) — the standard that lets Claude call your Python functions as "tools". You tag a function with @mcp.tool() and Claude can invoke it.

• stdio transport — Claude Desktop talks to this server over stdin/stdout (like two programs connected by a pipe), not over the network. Hence no URL/port.

• async/await — lets Python wait on slow I/O (a database round-trip) without freezing the whole program.

• Connection pool — a set of ready-to-use DB connections borrowed and returned, instead of opening a fresh (expensive) connection per request.

• Allow-list vs deny-list — allow-list = "only what's on the list is permitted" (the safe default: forget to list something and it's denied). Deny-list = "everything except the list". This server is allow-list throughout.

• SQL parser / AST — sqlglot turns SQL text into a tree a program can inspect, so we can detect a hidden DROP inside a complex query — not just string-match "DROP".

• CTE (Common Table Expression) — a WITH x AS (...) SELECT ... query. Postgres allows writes inside a CTE, so the guard checks there too.

• Parameterized query — passing values separately from the SQL text ($1, $2) so user data can never be parsed as SQL. The write tools use this throughout.

• Least-privilege role — a database user granted only the permissions it needs (SELECT for reads; INSERT/UPDATE on specific tables for writes) — never a superuser.

• Defense in depth — independent layers (app-level SQL guard and DB-level role grants) that must all fail for an attack to succeed.

• Structured error — a consistent {error_code, message, hint} shape returned on every failure, instead of a raw stack trace or a silent empty result.

• Dry-run / confirm — a write reports what it would do and changes nothing until called again with confirm=true.

• Transaction + rollback — a group of DB operations that either all succeed or all undo, so a half-written row can't be left behind.

• Append-only log — a log you only ever add to (never edit/delete), so the audit trail can be trusted.

• Token bucket — a rate-limit metaphor: a bucket of tokens refilled over time; each call spends one; empty bucket = request politely refused.

• PII (Personally Identifiable Information) — data identifying a person (email, phone). Masked in results based on policy.yaml.

• Adversarial test — a test that actively tries to break the system (attack it), proving the guards hold — stronger evidence than testing only the happy path.

Honesty note

This is a reference/demo build, not a paid client engagement. Metrics come from the self-built 19-attack adversarial suite and are fully reproducible. No client names, logos, or data are implied.