MCPDBWizard

Documentation  ·  Getting started

Quickstart: Postgres

This page gets MCPDBWizard for Postgres running on Docker, builds a server from your own schema and connects an agent to it. It is the Postgres counterpart of Quickstart: Docker; from step 4 on, the console works exactly as it does on Oracle.

Before you start

1. Settle the settings

Three are required, plus the password; the port defaults to 5432. Exporting them first keeps the password off the docker run command line and out of your shell history.

export MCPDBWIZARD_DB_HOST=db.example.com
export MCPDBWIZARD_DB_PORT=5432
export MCPDBWIZARD_DB_NAME=appdb
export MCPDBWIZARD_DB_USER=mcp_agent
export DB_PASS=change-me

MCPDBWIZARD_DB_USER is both the login role and the first schema listed in Design. If your tables live in another schema, add MCPDBWIZARD_DB_OTHER_USER — see Connecting to Postgres.

A database on the Docker host itself is not localhost from inside the container. Use host.docker.internal (Docker Desktop), or add --add-host=host.docker.internal:host-gateway on Linux, and make sure Postgres listens on an address the container can reach.

2. Pull and run

docker pull ghcr.io/srmadscience/mcpdbwizard-postgres:2.0.33

docker run -d --name mcpdbwizard-postgres \
  -p 8080:8080 \
  -v mcpdbwizard-data:/data \
  -e MCPDBWIZARD_DB_HOST \
  -e MCPDBWIZARD_DB_PORT \
  -e MCPDBWIZARD_DB_NAME \
  -e MCPDBWIZARD_DB_USER \
  -e DB_PASS \
  ghcr.io/srmadscience/mcpdbwizard-postgres:2.0.33

-e NAME with no =value copies the variable through from the shell running docker.

Pin the version tag. docker run never pulls an image the machine already has, so a box that pulled :latest once keeps starting that build until someone pulls again. See :latest does not refresh itself.

Only 8080 is published, and that is deliberate. Generated servers listen on loopback inside the container and are reached through the proxy on 8080, the only component that knows who is calling.

Check it connected:

docker logs mcpdbwizard-postgres 2>&1 | grep 'PostgreSQL connection configured'

3. Sign in

Open http://localhost:8080. There is no default password: the first start writes one to initial-admin-password on the volume, and the sign-in page names the path.

docker exec mcpdbwizard-postgres cat /data/initial-admin-password

Sign in as admin and choose your own password. You are made to before the generator will run, and the file is deleted the moment you do. Set ADMIN_INITIAL_PASSWORD on the docker run if you would rather choose the first one yourself.

4. Build a config

On the Design pages, pick what the agent may reach: tables and views, functions and procedures, sequences, and any SQL statements you have written and tested yourself. Each tab lists what the connected role can see in the schemas you configured.

Write the descriptions. A table called ord_ln means nothing to a model; a description of what it holds, and when to use it, is what keeps an agent on track. See Creating configs.

Press Save. The config is a file with no password in it, which you can review and put through a change process like any other.

5. Generate and run

On the Runtime page, choose Generate & run. The generator writes the Java for exactly what you selected, compiles it and starts the server; the log shows each step. A routine with a parameter type that cannot cross MCP is named in the log and left out — see What becomes a tool.

6. Issue a token and grant the config

On the Users page, create a user, issue it an API token — shown exactly once — and tick the config on the Access grid. A token alone is not access: a new account starts with no grants. See Creating application users.

7. Connect an agent

Point the client at the proxy. The URL carries the config’s owner, so a config orders saved by admin is at /mcp/admin/orders; the Runtime page shows each server’s full URL.

claude mcp add orders --transport http http://localhost:8080/mcp/admin/orders \
  --header "Authorization: Bearer <id>.<secret>"

Ask the agent what it can do and it lists the tools back to you. Tool names carry the schema — sales_orders_get_by_pk — so tables of the same name in two schemas stay apart. See Connecting to the MCP server.

Writes are real. Each tool call commits on its own, so an insert or a procedure that changes data changes it for good. Point a first trial at a database you can reset.

Next