MCPDBWizard

Documentation  ·  Getting started

Quickstart: MariaDB

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

Before you start

No schema of your own to hand? The MariaDB hotel demo is a small booking database with procedures, cursors and two ready-made configs, one of them pinned to a single customer by the connection URL. Load it with three mariadb commands (its README has them, and it needs MariaDB 12.3 or later), set MCPDBWIZARD_DB_NAME=mcpdemo and MCPDBWIZARD_DB_USER=mcpdemo below, and upload its config/mcpdemo_customer.json at step 4 rather than building a config.

1. Settle the settings

Three are required, plus the password; the port defaults to 3306. 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=3306
export MCPDBWIZARD_DB_NAME=shop
export MCPDBWIZARD_DB_USER=mcp_agent
export DB_PASS=change-me

MCPDBWIZARD_DB_NAME is the database whose objects Design lists as your own; the login can be called anything. To list more databases, add MCPDBWIZARD_DB_OTHER_USER — see Connecting to MariaDB.

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, make sure MariaDB listens on an address the container can reach (bind-address), and that the login’s host part allows the container ('mcp_agent'@'%').

2. Pull and run

docker pull ghcr.io/srmadscience/mcpdbwizard-mariadb:2.0.36

docker run -d --name mcpdbwizard-mariadb \
  -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-mariadb:2.0.36

-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-mariadb 2>&1 | grep 'MariaDB 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-mariadb 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, procedures and functions (package members among them), sequences, and any SQL statements you have written and tested yourself. Each tab lists what the connected login can see in the databases 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.

A SQL statement’s parameters need a type hint, because MariaDB does not report one: where id = ? /* pId int */. Without one, a parameter is text.

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 that cannot be described — most often for want of the SHOW CREATE ROUTINE grant — is named in the log with the reason 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. 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