# db-mcp-gateway

> db-mcp-gateway is a self-hosted MCP gateway that gives AI agents SSO-gated, audited, read-only database access without ever handing a database URL out to a client. A team deploys it once (single Docker image + one YAML config + one Postgres for state), and every agent talks to it over MCP/HTTPS. The gateway resolves the caller's SSO identity, evaluates the YAML-defined grant for `(user × group × server × database × action)`, opens a per-database read-only pool with statement timeouts and row caps, and writes an append-only audit row synchronously before the response leaves the wire. Writes are opt-in per grant (`query_write`, never schema changes), never the default. Targets today: PostgreSQL and MongoDB. Written in Rust (tokio + axum + sqlx), distributed as a multi-arch OCI image on GHCR, MIT-licensed.

## Three pillars

- **Credentials never leave the gateway.** No DB URL on a laptop, ever. No tool returns one. No log line contains one. Not in responses, not in errors, not in admin endpoints.
- **Identity end-to-end.** Every query traces SSO user → group → grant → audit row. OIDC (Okta, Google Workspace, Entra, Authentik, Keycloak) drives who; YAML drives what; audit records both.
- **Config-as-code.** Permissions live in YAML, reviewed by PR. Optional SSO-gated admin API for dynamic grants, writes audited to `permissions_audit`. No in-band admin UI, by design.

## MCP tool surface

`list_databases`, `describe_schema`, `sample_table`, `run_query`, `explain`, `get_query_history`. Read-only by default; `query_write` grant unlocks INSERT / UPDATE / DELETE (never DDL) when both YAML *and* the target-DB role permit it.

## Docs

- [README](https://github.com/developerz-ai/db-mcp-gateway/blob/main/README.md): overview, three pillars, install, quick links.
- [Overview](https://github.com/developerz-ai/db-mcp-gateway/blob/main/docs/initial-idea/01-overview.md): what this is and what it isn't.
- [Non-goals](https://github.com/developerz-ai/db-mcp-gateway/blob/main/docs/initial-idea/10-non-goals.md): things db-mcp-gateway explicitly won't do.
- [Roadmap](https://github.com/developerz-ai/db-mcp-gateway/blob/main/docs/initial-idea/11-roadmap.md): what's built vs planned.
- [Features](https://github.com/developerz-ai/db-mcp-gateway/blob/main/docs/features.md): full feature reference.
- [Use cases](https://github.com/developerz-ai/db-mcp-gateway/blob/main/docs/use-cases.md): who this is for, what problems it solves.
- [Comparison](https://github.com/developerz-ai/db-mcp-gateway/blob/main/docs/comparison.md): db-mcp-gateway vs alternatives.
- [Benchmarks](https://github.com/developerz-ai/db-mcp-gateway/blob/main/docs/benchmarks.md): performance numbers.

## Deployment

- [Quickstart](https://github.com/developerz-ai/db-mcp-gateway/blob/main/docs/deployment/quickstart.md): stand up the gateway against a target Postgres.
- [Config reference](https://github.com/developerz-ai/db-mcp-gateway/blob/main/docs/deployment/config-reference.md): every YAML field, validated at boot.
- [Admin API](https://github.com/developerz-ai/db-mcp-gateway/blob/main/docs/deployment/admin-api.md): SSO-gated dynamic grants, audited to `permissions_audit`.
- [Logging](https://github.com/developerz-ai/db-mcp-gateway/blob/main/docs/deployment/logging.md): tracing spans, audit sinks (OTLP, syslog, stdout, S3/GCS/Azure archive).
- [Releasing](https://github.com/developerz-ai/db-mcp-gateway/blob/main/docs/deployment/releasing.md): tagging, image build, multi-arch (linux/amd64 + linux/arm64), compatibility policy.

## Usage

- [First query](https://github.com/developerz-ai/db-mcp-gateway/blob/main/docs/usage/first-query.md): 5-minute walkthrough from `claude mcp add` to a returned result.
- [Claude Code reference](https://github.com/developerz-ai/db-mcp-gateway/blob/main/docs/usage/claude-code.md): full client-side reference.
- [Other agents](https://github.com/developerz-ai/db-mcp-gateway/blob/main/docs/usage/other-agents.md): non-Claude MCP clients (Cursor, Windsurf, etc.).
- [Multi-DB](https://github.com/developerz-ai/db-mcp-gateway/blob/main/docs/usage/multi-db.md): querying across PostgreSQL and MongoDB with one grant surface.