How to Configure DBX Web with Password Authentication for MCP

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:

• 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 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) 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:

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

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:

export DBX_DISABLE_PASSWORD=1

Manual Authentication for Scripts

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

# 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 and server initialization in 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.

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. This file contains the auth_middleware that validates session tokens on protected routes.

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