Sanitized DB MCP Server

An MCP server that rewrites SQL queries at the AST level to prevent PII/PHI exposure.

Why This Exists

AI agents write SQL. They also hallucinate column names, ignore access controls, and cheerfully SELECT * from tables full of personal data. This server sits between the agent and your PostgreSQL database, rewriting every query so hidden columns return type-preserving placeholders instead of real values. The agent gets useful results; your users keep their privacy.

Quick Start

1. Create an allowlist

Generate a scaffold from your database schema:

# Install the CLI (skip if using uvx or Docker below)
pip install sanitized-db-mcp

sanitized-db-mcp generate-allowlist --database-url postgresql://user:pass@host:5432/mydb > allowlist.yaml

Edit the YAML to expose only the columns agents should see (see Generating an Allowlist below).

2. Run the server

Pick one of the four methods below and add the config to your .mcp.json.

Method 1: uvx (recommended — zero install)

uvx runs the package in an isolated environment with no permanent installation and no dependency conflicts. Unlike pip, there is nothing to install or manage. Unlike Docker, there are no volume mounts or path mappings to configure.

{
  "sanitized-db": {
    "type": "stdio",
    "command": "uvx",
    "args": ["sanitized-db-mcp"],
    "env": {
      "ALLOWLIST_PATH": "./allowlist.yaml",
      "DATABASE_URL": "postgresql://user:pass@host:5432/mydb"
    }
  }
}

No install needed. uvx downloads and runs the package in an isolated environment.

Method 2: pip install

pip install sanitized-db-mcp

{
  "sanitized-db": {
    "type": "stdio",
    "command": "python3",
    "args": ["-m", "sanitized_db_mcp.server"],
    "env": {
      "ALLOWLIST_PATH": "./allowlist.yaml",
      "DATABASE_URL": "postgresql://user:pass@host:5432/mydb"
    }
  }
}

Method 3: Docker (pre-built image)

{
  "sanitized-db": {
    "type": "stdio",
    "command": "docker",
    "args": [
      "run", "-i", "--rm",
      "-e", "ALLOWLIST_PATH=/app/allowlist.yaml",
      "-e", "DATABASE_URL",
      "-v", "./allowlist.yaml:/app/allowlist.yaml:ro",
      "ghcr.io/ruminaider/sanitized-db-mcp:latest"
    ],
    "env": {
      "DATABASE_URL": "postgresql://user:pass@host:5432/mydb"
    }
  }
}

Method 4: Docker (build from source)

docker build -t sanitized-db-mcp:local .

{
  "sanitized-db": {
    "type": "stdio",
    "command": "docker",
    "args": [
      "run", "-i", "--rm",
      "-e", "ALLOWLIST_PATH=/app/allowlist.yaml",
      "-e", "DATABASE_URL",
      "-v", "./allowlist.yaml:/app/allowlist.yaml:ro",
      "sanitized-db-mcp:local"
    ],
    "env": {
      "DATABASE_URL": "postgresql://user:pass@host:5432/mydb"
    }
  }
}

3. Query through the agent

The server exposes a single MCP tool (query) that accepts raw SQL and returns sanitized results.

Generating an Allowlist

The CLI tool connects to your database, reads the schema, and produces a YAML file where nothing is visible by default. You opt columns in by uncommenting them.

sanitized-db-mcp generate-allowlist --database-url postgresql://user:pass@host:5432/mydb > allowlist.yaml

Add --deny-pii to flag columns that look like PII (email, name, phone, address, etc.):

sanitized-db-mcp generate-allowlist --database-url postgresql://... --deny-pii > allowlist.yaml

Example output:

# Generated by: sanitized-db-mcp generate-allowlist --deny-pii
#
# HOW TO USE:
# - Columns under "columns:" are VISIBLE to agents (currently empty)
# - Commented lines show available columns — uncomment to make visible
# - Lines marked "# PII" were flagged as likely PII/PHI — review carefully
# - After editing, restart the MCP server to apply changes

tables:
  users:
    columns: {}
    # Available columns (uncomment to make visible):
    #   id: {type: integer, placeholder: 0}
    #   is_active: {type: boolean, placeholder: false}
    #   email: {type: varchar, placeholder: '[REDACTED]'}  # PII
    #   password: {type: varchar, placeholder: '[REDACTED]'}  # PII

Uncomment the columns you want agents to see. Leave everything else hidden.

Allowlist YAML Format

tables:
  <table_name>:
    columns:
      <column_name>: {type: <pg_type>, placeholder: <sql_literal>}
allowed_functions:
  - FUNCTION_NAME

• Listed columns are VISIBLE. Unlisted columns are hidden and replaced with type-preserving placeholders.
• type: base PostgreSQL type (integer, varchar, boolean, timestamp, uuid, jsonb, etc.).
• placeholder: SQL literal that replaces hidden column values. Must be type-compatible.
• allowed_functions: SQL functions agents can call. All others are rejected.

Configuration

The server prefers Render API credentials when both are set. For local development, DATABASE_URL is sufficient.

Framework Integration

• Django: Use a visible() field decorator to mark safe fields, then generate the allowlist from model metadata.
• Rails / Other: Use the CLI tool to scaffold, then curate manually. Or build your own generator that outputs the same YAML format.
• Custom generators: The YAML format is the contract. Any tool that produces conformant YAML works.

SSE Transport (Remote Deployment)

For shared deployments (e.g., Render.com), the server supports SSE transport over HTTP.

Installation

pip install 'sanitized-db-mcp[sse]'

Configuration

Running

export MCP_TRANSPORT=sse
export MCP_API_KEY=your-secret-key
export ALLOWLIST_PATH=./allowlist.yaml
export DATABASE_URL=postgresql://...
python -m sanitized_db_mcp.server

Docker

docker run -e MCP_TRANSPORT=sse -e MCP_API_KEY=secret -e ALLOWLIST_PATH=/app/allowlist.yaml \
  -e DATABASE_URL=postgresql://... -p 8000:8000 sanitized-db-mcp

Claude Code Client Configuration

In your MCP client config, point to the SSE endpoint:

{
  "mcpServers": {
    "sanitized-db": {
      "type": "sse",
      "url": "https://your-service.onrender.com/sse",
      "headers": {
        "Authorization": "Bearer your-secret-key"
      }
    }
  }
}

Endpoints

• GET /sse — SSE connection (MCP session)
• POST /messages/ — Client-to-server messages
• GET /health — Health check (no auth required)

Deployment Guidance

Connection limits: Set MCP_MAX_CONNECTIONS to prevent resource exhaustion under attack or misconfiguration. A reasonable value is 2-5x your expected concurrent clients (e.g., 100 when expecting 10-20 clients). New connections beyond the limit receive HTTP 503. Note: each SSE session AND each /messages/ POST from that session count as separate concurrent connections, so do not set this too low.

Session timeout: Set MCP_SESSION_TIMEOUT (seconds) to close abandoned SSE sessions. 28800 (8 hours) is a reasonable starting point. Clients reconnect automatically after timeout. Without this, abandoned sessions consume resources indefinitely since uvicorn's timeout_keep_alive does not apply to active SSE streams.

CORS: CORS headers are intentionally omitted. The server's clients (Claude Code, MCP CLI tools) are non-browser applications that ignore CORS. The native browser EventSource API cannot send Authorization headers, so browsers cannot authenticate even if they attempt cross-origin connections. If browser-based MCP clients become a supported consumer, add Starlette's CORSMiddleware.

Audit logging: Every query is logged as structured JSON with client IP, request ID, session ID, and user agent for HIPAA compliance. Behind a reverse proxy (Render, nginx), client IP is extracted from X-Forwarded-For. Configure your log aggregator for 6-year retention per HIPAA requirements.

How the Sanitizer Works

The server exposes a single MCP tool (query) that accepts raw SQL and returns sanitized results. Every query passes through an 11-step pipeline:

Agent sends SQL
      |
      v
1.  Parse (pglast) ───── syntax error? → QuerySyntaxError
      |
      v
2.  Statement type ───── not SELECT? → StatementTypeError
      |                   SELECT INTO? → StatementTypeError
      |                   FOR UPDATE/SHARE? → StatementTypeError
      v
3.  Table validation ─── system catalog? → SystemCatalogError
      |                   not in allowlist? → RestrictedColumnError
      |                   TABLESAMPLE? → unwrap, validate inner table
      v
4.  Function check ───── always-blocked? → DisallowedFunctionError
      |                   not in allowlist? → DisallowedFunctionError
      |                   FILTER (WHERE ...)? → walk with WHERE rules
      |                   inline OVER clause? → walk with WHERE rules
      v
5.  WHERE/JOIN check ─── hidden column? → RestrictedColumnError
      v
6.  Clause check ──────── ORDER BY / GROUP BY / DISTINCT ON / WINDOW
      |                    hidden column? → RestrictedColumnError
      v
7.  Subquery check ───── hidden column in subquery/CTE SELECT? → RestrictedColumnError
      v
8.  Rewrite SELECT ───── hidden columns → type-preserving placeholders
      |                   SELECT * → visible columns + redaction marker
      v
9.  Serialize AST ────── rewritten SQL string
      v
10. Execute ───────────── read-only, 5s timeout, SSL
      v
11. Audit log ─────────── structured JSON (original, rewritten, outcome)

Security Model

All 200 tests pass with 0 xfails. The pen test suite covers 21 attack categories:

Running Tests

cd sanitized-db-mcp

# Full test suite (200 tests across 3 suites)
python -m pytest sanitized_db_mcp/tests/ -v

# Individual suites
python -m pytest sanitized_db_mcp/tests/test_sanitizer.py -v    # Core rewriting (37 tests)
python -m pytest sanitized_db_mcp/tests/test_bypass.py -v       # Bypass resistance (64 tests)
python -m pytest sanitized_db_mcp/tests/test_pentest.py -v      # Pen test (99 tests)
python -m pytest sanitized_db_mcp/tests/test_allowlist.py -v    # Allowlist loader

Key Files