Provides read-only access to PostgreSQL databases, including tools for listing databases, schemas, and tables, describing tables, running guarded read-only SQL, and performing reranked hybrid search.
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_db_server Show me the tables in the policy database and their schemas."
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.
The read-only MCP database server — a uv workspace holding one engine package and the config-only instances that run it. Carved from the rag monorepo on 2026-08-13 (see the pre-repo-split tag for the joint pre-split history); the pipeline that builds the corpus lives in the sibling ingestion_pipeline repo.
One installable distribution, credential-free and instance-free: it learns schemas, tables, and embedding columns from PostgreSQL at runtime and serves six tools (list_databases, list_schemas, list_tables, describe_tables, run_sql, search) over streamable HTTP with bearer-token auth.
Package | Purpose |
| The server: catalog introspection, guarded read-only SQL, and reranked hybrid (dense + sparse) search, plus the search-equivalence capture tool |
Installing the workspace (uv sync) installs both entry points as console scripts:
mcp-db-server data-val-search-equivalenceRelated MCP server: PostgreSQL MCP Server
An instance is a directory under instances/ that owns everything about one served database: its .env (connection credentials, bearer tokens, bind port, instructions), its validation config, and its logs and data outputs. Instances own no code — they are configuration, so they are not workspace members.
Current instances: instances/policy_db/ (the CMS policy corpus, port 8000) and instances/metadata_db/ (the metadata catalog, port 8002). The server serves databases this repo does not build: it is shared infrastructure, not a pipeline component, and each database's read-only grants live with that database's DDL owner — policy_db's in ingestion_pipeline (instances/policy_db/sql/mcp_ro_policy_grants.sql), metadata_db's in the metadata_db repo (code/apply_ddl/grants/mcp_ro_metadata.sql).
Onboarding a new instance is mkdir instances/<name>, copy an .env.example to instances/<name>/.env, and add the role's grants in the repo that owns that database.
uv sync # Python >= 3.13
uv run pytest # the full suite, from any directory
uv run mcp-db-server --env-file instances/policy_db/.envThe --env-file flag is required — there is no default instance. Allow ~1 minute for model warm-up (measured: 36s), then GET /health returns 200.
MAINTAINING.server.md — maintaining the engine: workspace layout, setup and testing, running an instance, auth operations, tuning knobs, the data interface the server reads, and gotchas.
MAINTAINING.instance.policy_db.md — operating the policy_db instance: the served corpus, credentials and grants, token onboarding, and the search-equivalence baseline workflow.
MAINTAINING.instance.metadata_db.md — operating the metadata_db instance: the served catalog, credentials and grants, and why it runs without models.
docs/activities/ and docs/code_review/ are dated work records produced by the development workflow, not documentation — see the maintaining files for current truth.
This server cannot be deployed
Query PostgreSQL databases in plain English — LLM-generated, safety-validated SQL.
Safe, read-only Postgres and MySQL access for AI agents. Audit log + column-level controls.
Query your Postgres from ChatGPT or Claude without exposing the database or handing over credentials. Run npx boltschema connect next to your database and it dials out over HTTPS — no inbound firewall rule, no open port, works with localhost and VPC-private databases. Read-only is enforced by a SQL guard, a Postgres READ ONLY transaction, and a scoped role generated for you.
Query 40 databases from Claude, ChatGPT, or Cursor — on any device. Read-only, encrypted, audited.
