# How to Run the DBX MCP Server Against a Docker Deployment

> Learn to run the DBX MCP server against a Docker deployment. Set DBX_WEB_URL and DBX_WEB_PASSWORD to connect the containerized DBX web API.

- Repository: [skyler/dbx](https://github.com/t8y2/dbx)
- Tags: how-to-guide
- Published: 2026-07-10

---

**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`](https://github.com/t8y2/dbx/blob/main/.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`](https://github.com/t8y2/dbx/blob/main/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`:

```bash
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`](https://github.com/t8y2/dbx/blob/main/deploy/docker-compose.yml) in the repository:

```yaml
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:

```bash
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`](https://github.com/t8y2/dbx/blob/main/.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`](https://github.com/t8y2/dbx/blob/main/README.md), you must specify the `DBX_WEB_URL` pointing to your exposed container port:

```json
{
  "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:

```bash
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:

```json
{
  "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`](https://github.com/t8y2/dbx/blob/main/deploy/docker-compose.yml) for container orchestration and [`packages/mcp-server/README.md`](https://github.com/t8y2/dbx/blob/main/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`](https://github.com/t8y2/dbx/blob/main/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`](https://github.com/t8y2/dbx/blob/main/.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`](https://github.com/t8y2/dbx/blob/main/.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.