mcp-sql-gateway
Enables querying a SQLite database through governed natural-language requests: read-only single SELECT statements validated against per-user table profiles, sensitive column masking, enforced row limits, daily quotas, and a full audit log of every accepted, rejected, or failed query.
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., "@mcp-sql-gateway Which product category sold the most in Q3 2025?"
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.
mcp-sql-gateway
An MCP (Model Context Protocol) server that lets Claude or any MCP client query a SQL database in natural language, without handing the LLM the keys to the warehouse.
Every request goes through a governance layer:
🔐 Per-user data profiles: which tables each user may read
🕶️ Column masking: sensitive columns (email, phone…) come back as stable hashes
🛡️ SQL guard: one read-only
SELECTonly; tables are checked against the profile, even inside subqueries; a rowLIMITis always enforced📊 Daily quotas per user
🧾 Audit log of every attempt: accepted, rejected, failed or over quota, with the original and the executed SQL
🔒 Read-only connection as defense in depth
This is a clean-room demo with a synthetic dataset. It shows the same architecture I use in production with Azure Synapse and Microsoft Entra ID sign-in.
Architecture
flowchart LR
U[User in Claude / MCP client] -->|tool call| S[MCP server<br/>MCP Python SDK v2, stdio]
S --> I{Identity<br/>GATEWAY_USER<br/><i>prod: Entra ID token</i>}
I --> P[Profile registry<br/>profiles.yaml]
P --> Q[Quota check]
Q --> G[SQL guard<br/>sqlglot AST]
G -->|rewritten SQL + LIMIT| DB[(Data DB<br/>read-only)]
DB --> M[Column masking]
M -->|JSON rows| S
Q -. every attempt .-> A[(Audit log)]
G -. rejected .-> A
M -. ok .-> ATool | What it does |
| Tables and views the caller may query |
| Columns and types, flagging masked ones |
| Validates, rewrites and runs one |
| The caller's own audit trail |
Related MCP server: mcp-data-server
Quick start
git clone https://github.com/MateoCuenca09/mcp-sql-gateway.git
cd mcp-sql-gateway
python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
python scripts/seed_demo_db.py # creates data/demo.db (synthetic)Connect it to Claude Desktop
Add this to claude_desktop_config.json, using absolute paths:
{
"mcpServers": {
"sql-gateway": {
"command": "/path/to/mcp-sql-gateway/.venv/bin/mcp-sql-gateway",
"env": { "GATEWAY_USER": "ana.analyst@example.com" }
}
}
}Then ask: "Which product category sold the most in Q3 2025?" or "Show me the emails of
customers in Córdoba". As ana.analyst the emails come back masked; switch to
fede.finance@example.com and they don't.
You can also try it with the MCP Inspector: npx @modelcontextprotocol/inspector mcp-sql-gateway.
Configuration
config/profiles.yaml maps users to profiles:
profiles:
analyst:
tables: [orders, products, customers]
masked_columns: [email, phone]
max_rows: 200
daily_quota: 100
users:
ana.analyst@example.com: analystEnv var | Default |
| required, the caller's identity |
|
|
|
|
|
|
Tests
pytest -vThe tests cover write and multi-statement rejection, forbidden tables in subqueries, CTEs, limit capping, masking per profile, quota exhaustion, audit entries for every outcome and the read-only connection. CI runs ruff and pytest on Python 3.11–3.13.
Taking it to production
Identity: run over Streamable HTTP behind OAuth (e.g. Microsoft Entra ID) and take the user from the validated token instead of an env var.
Database: swap SQLite for Azure SQL / Synapse (
pyodbc) and setdialect="tsql"in the guard. Use a database login that only hasSELECTon the exposed schemas.Audit: send the log to a durable store (Azure Table Storage, Log Analytics).
Secrets: Key Vault + Managed Identity, no connection strings in config.
License
MIT
Available Tools
4 toolsdescribe_tableB
Show the columns of a table. Masked columns return hashed values.
Inputs: table (required). Returns: result
list_tablesA
List the tables and views you are allowed to query.
Inputs: no named parameters. Returns: result
my_recent_queriesB
Show your own most recent entries in the audit log.
Inputs: limit. Returns: result
run_queryA
Run a single read-only SELECT (SQLite dialect). A row limit is always applied.
Inputs: sql (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool maps to a distinct step in the query workflow: list_tables (discover), describe_table (inspect schema), run_query (execute), my_recent_queries (audit review). There is no overlap in purpose or return shape, so an agent can select correctly on the first try.
All names are lowercase snake_case and three of four follow a verb_noun pattern (describe_table, run_query, list_tables). my_recent_queries is a noun phrase rather than verb-led, a minor deviation but still immediately readable and thematically consistent.
Four tools is well-scoped for a deliberately read-only SQL gateway; each tool covers a necessary phase of the workflow and none feels redundant. Nothing is padded or missing from a minimal viable surface.
The read-only lifecycle is fully covered: discovery, schema inspection, execution, and audit traceability, with no dead ends for the stated purpose. Minor gaps exist (no way to inspect indexes/keys or paginate the audit log beyond the default limit), but agents can work around these.
Related MCP Connectors
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
Query your warehouse or a CSV with Claude/ChatGPT over MCP, governed by table-level ACL + audit.
Query 40 databases from Claude, ChatGPT, or Cursor — on any device. Read-only, encrypted, audited.
Query, explore, and manage your databases through natural conversation.
Related MCP Servers
- FlicenseAqualityDmaintenanceEnables read-only exploration and querying of PostgreSQL or MySQL databases via MCP, with schema discovery, safe SQL validation, natural language to SQL conversion, and CSV export.112-
- AlicenseNot gradedqualityBmaintenanceProvides read-only, guarded access to business databases via MCP. Enables natural language querying with built-in security barriers like table allowlists, PII masking, and audit logging.MIT
- FlicenseNot gradedqualityDmaintenanceEnables natural-language querying of Postgres and MongoDB databases in read-only mode, with PII masking and row/timeout guardrails, from any MCP client.-
- AlicenseNot gradedqualityCmaintenanceEnables MCP clients such as Claude, ChatGPT and Cursor to answer business questions about sales, customers, orders and spreadsheets in natural language by reading live Postgres/SQLite databases and Google Sheets without exporting files or gaining write access. Guardrails include AST-based read-only SQL validation, read-only database roles, row/byte caps with pagination, PII masking, bearer-token auth for remote HTTP use, and a full JSONL audit log of every tool call.MIT