How to Run the DBX MCP Server Against a Docker Deployment

Launch the DBX MCP server against a Docker deployment by setting the DBX_WEB_URL environment variable to http://localhost:4224 (or your container's exposed URL) and providing the DBX_WEB_PASSWORD to authenticate with the containerized DBX web API.

The t8y2/dbx repository provides a self-hosted database management platform that includes a dedicated MCP (Model Context Protocol) server for AI coding agents. When you deploy DBX using Docker, the web backend runs inside the container on port 4224, requiring specific environment configuration to bridge the gap between the MCP server process and the containerized API.

Architecture Overview

The integration follows a three-tier flow where the MCP server acts as a bridge between your AI agent and the Dockerized DBX backend:

1. AI Agent reads the .mcp.json configuration and spawns the MCP server process via npx @dbx-app/mcp-server.
2. MCP Server forwards tool calls to the DBX Web API using the DBX_WEB_URL endpoint.
3. DBX Container (t8y2/dbx:latest) receives requests on port 4224 and executes queries against your configured databases.

As implemented in packages/mcp-server/README.md, the MCP server runs as a separate Node.js process outside the container, making environment variable configuration critical for network connectivity.

Deploy DBX in a Docker Container

Start the DBX web backend using either Docker Compose or a standalone docker run command. The container exposes port 4224 and persists data to /app/data.

Using the official image with docker run:

docker run -d --name dbx \
  -p 4224:4224 \
  -v dbx-data:/app/data \
  -e DBX_PASSWORD=changeme \
  t8y2/dbx:latest

Alternatively, use the Docker Compose definition from deploy/docker-compose.yml in the repository:

services:
  dbx:
    build:
      context: ..
      dockerfile: deploy/Dockerfile
    ports:
      - "4224:4224"
    environment:
      - DBX_PASSWORD=changeme
    volumes:
      - dbx-data:/app/data
    restart: unless-stopped

volumes:
  dbx-data:

Launch the container with:

docker compose -f deploy/docker-compose.yml up -d

The DBX_PASSWORD environment variable secures the web interface and API; you will reference this value again when configuring the MCP server.

Configure the MCP Server for Docker

Create a .mcp.json file in your project root or home directory to tell AI agents how to launch the MCP server against your Docker deployment. According to the configuration documented in the top-level README.md, you must specify the DBX_WEB_URL pointing to your exposed container port:

{
  "mcpServers": {
    "dbx": {
      "command": "npx",
      "args": ["-y", "@dbx-app/mcp-server"],
      "env": {
        "DBX_WEB_URL": "http://localhost:4224",
        "DBX_WEB_PASSWORD": "changeme"
      }
    }
  }
}

Key environment variables:

• DBX_WEB_URL: Must match the exposed Docker port (e.g., http://localhost:4224 if mapped to host port 4224).
• DBX_WEB_PASSWORD: Required when DBX_PASSWORD is set on the container; the MCP server uses this to authenticate API requests.

You can verify the server launches correctly by running:

npx @dbx-app/mcp-server

The process starts listening on the default MCP port (4000) and connects to the Dockerized DBX backend at the configured URL.

Validate the Integration

Once configured, AI agents like Claude Code, Cursor, or Windsurf can invoke MCP tools such as list-connections, list-tables, and execute-sql. For example, when an agent sends an execute-sql request:

{
  "type": "execute-sql",
  "payload": {
    "connectionId": "my-postgres",
    "sql": "SELECT COUNT(*) FROM users"
  }
}

The MCP server forwards this to http://localhost:4224/api/v1/query (the exact endpoint defined in the DBX web API), and returns results in the MCP protocol format. All database queries route through the Docker container while the AI agent remains unaware of the containerization layer.

Summary

• Container Deployment: Run t8y2/dbx:latest on port 4224 with a named volume for /app/data and set DBX_PASSWORD for authentication.
• MCP Configuration: Point DBX_WEB_URL to http://localhost:4224 (or your Docker host URL) and match DBX_WEB_PASSWORD to the container's DBX_PASSWORD.
• Architecture: The @dbx-app/mcp-server package runs as a separate Node process, bridging AI agents to the containerized DBX API via environment variables.
• Key Files: Reference deploy/docker-compose.yml for container orchestration and packages/mcp-server/README.md for MCP server specifics.

Frequently Asked Questions

What port does the DBX Docker container expose?

The DBX Docker container exposes port 4224 by default, as defined in deploy/Dockerfile and deploy/docker-compose.yml. When running the MCP server against a Docker deployment, you must set DBX_WEB_URL to http://localhost:4224 (or the appropriate host IP if running Docker on a remote machine).

Do I need to install the MCP server globally?

No. The recommended configuration uses npx -y @dbx-app/mcp-server to run the server on-demand without global installation. The -y flag automatically accepts the installation prompt, allowing AI agents to spawn the process immediately when reading the .mcp.json configuration.

How do I secure the MCP server connection when DBX requires authentication?

Set the DBX_WEB_PASSWORD environment variable in your .mcp.json to match the DBX_PASSWORD value used when starting the Docker container. This allows the MCP server to authenticate with the DBX web API using the same credentials you use to access the web interface.

Can I run the MCP server inside the same Docker container as DBX?

No. The MCP server is designed to run as a separate Node.js process on your host machine or development environment, not inside the DBX container. It communicates with the containerized DBX web API via HTTP through the DBX_WEB_URL endpoint, keeping the concerns of the AI agent interface separate from the database backend.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}