db-mcp-gateway

Cho phép AI agents truy cập cơ sở dữ liệu mà không bao giờ phải cung cấp URL cơ sở dữ liệu

Tài liệu

db-mcp-gateway

db-mcp-gateway

Your AI agent needs to read the production database. The connection string is the one thing you cannot hand it.

Maintained by developerz.ai CI Release Image Rust GitHub stars License: MIT

Give an agent a database URL and that credential now lives on a laptop, in a config file, in shell history, and in whatever the agent decides to echo back. Rotating it means finding every copy. And every query it runs is attributed to nobody.

db-mcp-gateway holds the credential instead. It is a self-hosted MCP server your team deploys once. Developers point their agent at one URL. The gateway authenticates them through the SSO you already run, checks each query against permissions reviewed by pull request, and commits an append-only audit row before any result goes back.

The denial is the product

Live gateway: service:demo-bot in the query_read group reads customers, then the same account's INSERT is rejected as forbidden_sql — both calls commit as audit_calls rows before the response returns.

Install

v2.3.0 — stable, in production use. Upgrading from 1.x: website/docs/deployment/upgrading-to-2.md. One image, one YAML file, and one Postgres for the gateway's own state:

docker pull ghcr.io/developerz-ai/db-mcp-gateway:2.3.0

Public on GHCR, no auth needed to pull. Multi-arch (linux/amd64, linux/arm64), built reproducibly from a v* git tag. :latest tracks the newest release; pin the version in production. Compatibility policy in website/docs/deployment/releasing.md, deployment in website/docs/deployment/quickstart.md.

Client side, that is the whole setup:

claude mcp add --transport http db-gateway --scope project https://db.internal.acme.com

The first call triggers SSO in a real browser — no embedded webview, no token pasting. Walk through it end to end in website/docs/usage/first-query.md, or use another MCP client via website/docs/usage/other-agents.md.


Three pillars

PillarWhat it means
Credentials never leave the gatewayNo DB URL on a laptop, ever. No tool returns one. No log line contains one.
Identity end-to-endEvery query traces SSO user → group → grant → audit row.
Config-as-codePermissions live in YAML, reviewed by PR. No in-band admin UI, by design.

Supported databases

"MySQL" means two unrelated things here, so both are stated once, in one table. Query targets are what an agent can read through the gateway. The permissions store is where the gateway keeps its own grant metadata — an agent never touches it.

PostgreSQLYugabyteDB (YSQL)MongoDBRedis / Dragonfly / ValkeyMySQLMSSQL
Query target — agents can query ityesyes, as kind: postgres — CI-testedyes, read-onlyyes, read-only (kind: redis; Redis + Dragonfly CI-tested)no — rejected at bootno — rejected at boot
Permissions store — gateway's own stateyesnot testedno, by designno, by designresolver path only, no admin APIno

A server.kind of mysql or mssql refuses to start rather than booting clean and failing every query, so a wrong config is caught at deploy time and not by a user. MySQL and MSSQL query adapters are on the roadmap. Writes (query_write) exist on Postgres-protocol targets only; Mongo and Redis stay read-only whatever the grant, and Redis key scoping is the ACL user's job (multi-db).

Performance: measured numbers are published in website/docs/benchmarks.md, with the raw run evidence committed under benchmarks/results/ — and the harness to measure it yourself on your own hardware.


What it does

  • MCP tool surface — list_servers, list_databases, describe_schema, sample_table, run_query, explain, get_query_history, table_stats, db_activity, cancel_query. run_query takes SQL on PostgreSQL and YugabyteDB, a JSON command document on MongoDB, and a JSON argv array (["HGETALL","user:1"]) on Redis and Dragonfly.
  • OIDC SSO — Any OIDC-compliant identity provider (e.g. Okta, Google Workspace, Entra, Authentik, Keycloak). Browser-flow login from the agent.
  • Read-only by default, writes opt-in per grant — per-database least-privilege roles; a query_write grant permits data writes (INSERT/UPDATE/DELETE), never schema changes. Statement timeouts and row caps enforced at the DB and gateway layer.
  • Permissions in YAML — group × server × database × action, with per-grant constraints (require_reason, row_limit, statement_timeout_ms). Table and schema scoping is the target-DB role's job, not a grant's. Reviewed by PR, with the full change history git already gives you.
  • Synchronous audit log — user, SQL, reason, row count, duration, outcome. The write commits before the response is sent; if it fails, the request fails. Retained in the gateway's Postgres with a configurable TTL and an hourly pruner, with optional stdout/syslog stream sinks for feeding an existing log pipeline or SIEM. Archive to object storage and OTLP streaming are roadmap Phase 4, not shipped.
  • Boring deployment — docker pull, one YAML file, and one Postgres for the gateway's own state. The databases your agents query are your existing ones; the local quickstart stands up a throwaway target too, so you can try it end to end without pointing at anything real. No agent runtime, no query builder, no credential vault to operate.

Complete feature documentation →


Who it's for

If you are…What you get
Platform / SREAgent database access without credential exposure, and one place to revoke it
A backend developerProduction queries for debugging with no password on your laptop, every one attributed to you
Data / analytics engineersAgent-assisted access to supported targets through one interface, with resource limits already enforced
Security / compliancePer-query SSO attribution, enforced reason logging, and an audit trail you did not have to build

Detailed use cases →


How it works

┌─────────┐    MCP/HTTPS    ┌──────────────┐ pg/mongo/redis┌──────────┐
│ agent   │ ──────────────▶ │   gateway    │ ────────────▶ │ target   │
│ (Claude │   bearer: jwt   │              │  ro role per  │  DBs     │
│  Code)  │ ◀────────────── │  authz+audit │ ◀──────────── │          │
└─────────┘   tool result   └──────┬───────┘   result rows └──────────┘
                                   │
                                   ▼
                            ┌──────────────┐
                            │ state DB     │
                            │ (sessions +  │
                            │  audit log)  │
                            └──────────────┘

Docs

If you're…Read
Trying to understand what this iswebsite/docs/initial-idea/01-overview.md
A developer whose org already runs itwebsite/docs/usage/first-query.md (5-min walkthrough) → website/docs/usage/claude-code.md (reference)
A platform/SRE deploying itwebsite/docs/deployment/quickstart.md
Adding it to a non-Claude MCP clientwebsite/docs/usage/other-agents.md
Cutting a releasewebsite/docs/deployment/releasing.md
Wondering what it won't dowebsite/docs/initial-idea/10-non-goals.md
Tracking what's built vs plannedwebsite/docs/initial-idea/11-roadmap.md
Asking about performancewebsite/docs/benchmarks.md
Comparing against alternativeswebsite/docs/comparison.md

Built with

ConcernChoice
LanguageRust (stable)
Async runtimetokio
HTTPaxum
DB driverssqlx (Postgres, YugabyteDB YSQL), mongodb, redis (tokio-rustls-comp)
Configserde + YAML, validated at boot
State storePostgres (co-deployed)
DistributionOCI image — ghcr.io/developerz-ai/db-mcp-gateway

AI-maintained

db-mcp-gateway is maintained by AI: by developerz.ai, the way a human maintainer looks after an open-source project. The agent works publicly as developerz-ai[bot] and marks every comment it posts as bot-made. Its policy is committed in .dz/maintainer/maintainer.yml, and CLAUDE.md binds it: no policy line relaxes a non-negotiable.

What arrivesWhat happens
an issuetriaged; asked for a reproduction when one is missing; a real bug is fixed and released
a pull requestreviewed (CodeRabbit and the developerz.ai reviewer), driven to green on fmt, clippy, test and audit, merged
a pull request on a security-review path (auth, authz, audit, exec, tools, state, secrets)labelled security review required, merged only once the mandatory security pass has nothing open
Dependabotdriven to green and merged; every bump waits 14 days after upstream publishes it (security updates excepted)
an outside change to CI, release or publish automationdeclined: members maintain the pipeline that publishes the image
a change that weakens a non-negotiabledeclined with the rule quoted
a breaking change (tool surface, error codes, config schema, audit shape) or a new featurea human decides: the team still designs and builds features, humans and AI together

Scheduled checkups, briefs in .dz/briefs/: weekly release-due judges whether a release is needed, daily security-release ships a confirmed security fix off-cycle, weekly health catches the failures nothing announces, and monthly improve lands at most three small, evidenced improvements.

Star history

Star history of developerz-ai/db-mcp-gateway

License

MIT. See LICENSE.