DB Gateway

Governed database access for AI agents.

MCP DB Gateway sits between MCP clients and your database. It gives agents enough context to work while keeping database access narrow, read-only, limited, and auditable.

The goal is not another universal SQL connector. The goal is a practical governance boundary for tools such as Cursor, Claude Code, and Claude Desktop.

Early-stage software. Do not treat v0.1 as a complete security boundary without reviewing it for your environment.

Why this exists

Giving an AI agent a database connection creates two opposing problems:

• Too little access forces developers to paste schemas and data into prompts.
• Too much access lets an agent explore or expose far more than the task requires.

MCP DB Gateway makes that boundary explicit through allowlists, read-only transactions, query limits, and audit events.

v0.1 scope

• PostgreSQL
• MCP over stdio
• list_tables
• describe_table
• execute_query
• Schema and table allowlists
• Read-only SQL validation and transactions
• Row and statement-timeout limits
• JSON audit events written to stderr

MySQL, SQLite, PII masking, role-based access, and a remote gateway are intentionally deferred.

Quick start

Requirements: Node.js 20+ and PostgreSQL.

git clone https://github.com/altsys/mcp-db-gateway.git
cd mcp-db-gateway
npm install
cp mcp-db-gateway.example.json mcp-db-gateway.json

Edit mcp-db-gateway.json so it contains only the schemas and tables the agent needs. Then build and run:

export DATABASE_URL="postgresql://user:password@localhost:5432/database"
npm run build
MCP_DB_GATEWAY_CONFIG=./mcp-db-gateway.json node dist/index.js

Example MCP client configuration:

{
  "mcpServers": {
    "database": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-db-gateway/dist/index.js"],
      "env": {
        "DATABASE_URL": "postgresql://user:password@localhost:5432/database",
        "MCP_DB_GATEWAY_CONFIG": "/absolute/path/to/mcp-db-gateway/mcp-db-gateway.json"
      }
    }
  }
}

Configuration

{
  "databaseUrlEnv": "DATABASE_URL",
  "governance": {
    "allowedSchemas": ["public"],
    "allowedTables": ["public.customers", "public.orders"],
    "maxRows": 100,
    "statementTimeoutMs": 5000
  }
}

An empty allowedTables array permits every table inside allowedSchemas. For a real deployment, prefer an explicit table allowlist.

Security model

The gateway provides defense in depth, not magic. Use a dedicated PostgreSQL role with SELECT access only. The application also validates SQL, opens a read-only transaction, limits execution time, and caps returned rows.

SQL parsing is deliberately conservative in v0.1. A proper PostgreSQL parser and table-level query enforcement belong on the near-term roadmap.

Roadmap

• Enforce table policy inside arbitrary SQL queries
• Replace conservative string validation with an AST-based PostgreSQL policy engine
• Mask configured PII columns
• Add structured file or HTTP audit sinks
• Add MySQL and SQLite adapters behind a shared provider interface
• Add named context packs for task-specific access
• Add RBAC and remote transport

Contributing

Issues and focused pull requests are welcome. Please keep changes aligned with the central idea: agents should receive the least database access necessary to complete the task.

License

MIT