# How to Configure DBX Web with Password Authentication for MCP

> Configure DBX Web password authentication for MCP by setting DBX_WEB_PASSWORD. Enable secure, automatic authenticated access to the HTTP API with this guide.

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

---

**Set the `DBX_WEB_PASSWORD` environment variable when starting DBX Web and pass the same password to the MCP client via its environment to enable automatic authenticated access to the HTTP API.**

Configuring DBX Web with password authentication for MCP secures your HTTP API while allowing AI agents to connect automatically. The **t8y2/dbx** repository implements a simple session-based authentication system that protects all routes under `/auth/*` and the API endpoints. This guide covers the environment variables, authentication flow, and MCP client configuration required to implement password protection.

## How DBX Web Password Authentication Works

DBX Web protects its HTTP API using a simple password mechanism controlled by environment variables. When `DBX_WEB_PASSWORD` is set, the server presents a login screen at `/auth/login` and requires a valid session token for all API calls.

### Environment Variable Configuration

The authentication system reads two key environment variables defined in [`crates/dbx-web/src/main.rs`](https://github.com/t8y2/dbx/blob/main/crates/dbx-web/src/main.rs):

- **`DBX_WEB_PASSWORD`**: Sets the password required to access the web interface and API.
- **`DBX_DISABLE_PASSWORD`**: Set to `1` to disable authentication entirely (useful for internal networks or testing).

### Authentication Flow

The authentication flow implemented in [`crates/dbx-web/src/auth.rs`](https://github.com/t8y2/dbx/blob/main/crates/dbx-web/src/auth.rs) follows these steps:

1. **Server Startup**: DBX Web checks for `DBX_WEB_PASSWORD` and initializes a session store.
2. **Client Login**: Clients POST `{"password":"your-password"}` to `/auth/login` to receive a signed session cookie.
3. **Request Validation**: The `auth_middleware` validates the session token on subsequent requests.
4. **MCP Integration**: The MCP server automatically authenticates using the same password and reuses the session token for all calls.

## Configuring the MCP Client

To let an MCP client access a password-protected instance, provide the same credentials through the MCP server's environment.

### MCP Server Environment Variables

The MCP server (documented in [`packages/mcp-server/README.md`](https://github.com/t8y2/dbx/blob/main/packages/mcp-server/README.md)) requires two environment variables:

- **`DBX_WEB_URL`**: The URL of the DBX Web instance (e.g., `http://localhost:4224`).
- **`DBX_WEB_PASSWORD`**: The password matching the `DBX_WEB_PASSWORD` set on the server.

Example MCP configuration:

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

```

## Running DBX Web with Password Protection

### Docker Deployment

Deploy DBX Web with password authentication using Docker:

```bash
docker run -d \
  -e DBX_WEB_PASSWORD=mySecretPass \
  -p 4224:4224 t8y2/dbx-web:latest

```

### Disabling Authentication (Optional)

For internal networks or development environments, disable password protection:

```bash
export DBX_DISABLE_PASSWORD=1

```

## Manual Authentication for Scripts

For scripts or curl-based workflows, manually authenticate and store the session:

```bash

# Login and store session cookie

curl -c cookie.jar -X POST http://localhost:4224/auth/login \
  -H "Content-Type: application/json" \
  -d '{"password":"mySecretPass"}'

# Use cookie for subsequent API calls

curl -b cookie.jar http://localhost:4224/api/connections/list

```

## Summary

- Set **`DBX_WEB_PASSWORD`** when starting DBX Web to enable password authentication.
- Configure the MCP client with matching **`DBX_WEB_PASSWORD`** and **`DBX_WEB_URL`** environment variables.
- Authentication logic resides in [`crates/dbx-web/src/auth.rs`](https://github.com/t8y2/dbx/blob/main/crates/dbx-web/src/auth.rs) and server initialization in [`crates/dbx-web/src/main.rs`](https://github.com/t8y2/dbx/blob/main/crates/dbx-web/src/main.rs).
- Use **`DBX_DISABLE_PASSWORD=1`** to bypass authentication for testing.
- Manual login via `/auth/login` returns a session cookie for non-MCP clients.

## Frequently Asked Questions

### What environment variables does DBX Web use for authentication?

DBX Web uses `DBX_WEB_PASSWORD` to set the access password and `DBX_DISABLE_PASSWORD` to optionally disable authentication. These are read during server startup in [`crates/dbx-web/src/main.rs`](https://github.com/t8y2/dbx/blob/main/crates/dbx-web/src/main.rs).

### How does the MCP server authenticate with DBX Web?

The MCP server reads `DBX_WEB_PASSWORD` from its environment and automatically logs in to DBX Web on startup. It stores the session token and reuses it for all subsequent MCP calls, as implemented in the connection logic.

### Can I use DBX Web without password authentication?

Yes. Set `DBX_DISABLE_PASSWORD=1` when starting the server. This disables the login screen and opens all routes, which is suitable for internal networks or development environments but should not be used in production.

### Where is the authentication middleware implemented?

The authentication middleware, login endpoints (`/auth/login`), and session handling are implemented in [`crates/dbx-web/src/auth.rs`](https://github.com/t8y2/dbx/blob/main/crates/dbx-web/src/auth.rs). This file contains the `auth_middleware` that validates session tokens on protected routes.