# How to Configure MCP Server with DBX for AI Agent Integration

> Integrate AI agents with your databases using DBX's MCP server. Learn to configure MCP server with DBX for seamless AI coding agent interaction. Explore AI agent capabilities.

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

---

**DBX ships a Model Context Protocol (MCP) server that enables AI coding agents like Claude Code, Cursor, and Windsurf to query your configured databases through a Node.js process that bridges to the DBX desktop app via STDIO and local TCP sockets.**

The t8y2/dbx repository provides a complete **Model Context Protocol (MCP)** implementation that allows AI agents to interact with your existing database connections. By configuring the MCP server, you enable agents to list connections, introspect schemas, and execute queries against PostgreSQL, MySQL, Redis, and other supported databases without manual connection management.

## Understanding the DBX MCP Server Architecture

Understanding the DBX MCP server architecture helps you configure it correctly for your environment. The system consists of a **Node.js MCP server** that communicates with AI agents via STDIO, a **Rust-based backend** that manages connections and safety, and an optional **TCP bridge** for desktop UI integration.

### Core Components

The implementation spans several key files in the t8y2/dbx repository:

- **MCP Server** ([`packages/mcp-server/src/index.ts`](https://github.com/t8y2/dbx/blob/main/packages/mcp-server/src/index.ts)): Starts the `McpServer` from the MCP SDK and registers tools like `dbx_list_connections`, `dbx_get_schema_context`, and `dbx_execute_query` starting at line 31.
- **Backend Layer** (`@dbx-app/node-core`): Provides `createBackend`, `buildSchemaContext`, and `evaluateSqlSafety` functions that read from the DBX SQLite store and manage connection pools.
- **Tauri Bridge** ([`src-tauri/src/commands/mcp_bridge.rs`](https://github.com/t8y2/dbx/blob/main/src-tauri/src/commands/mcp_bridge.rs)): Implements a local TCP bridge that forwards UI-specific requests (like `dbx_open_table`) from the Node server to the running DBX desktop application.
- **SQLite Store**: Persists connection profiles at platform-specific locations (`~/.local/share/com.dbx.app/dbx.db`, `~/Library/Application Support/com.dbx.app/dbx.db`, or `%APPDATA%\com.dbx.app\dbx.db`).

## Installation and Basic Configuration

Installing the MCP server requires Node.js and the `@dbx-app/mcp-server` package. The server operates in **zero-config mode** by default, automatically discovering the DBX SQLite database file on startup.

### Installing the MCP Server

Install the package globally using npm:

```bash
npm install -g @dbx-app/mcp-server

```

Once installed, the `dbx-mcp-server` command starts an STDIO-based server that AI agents can communicate with using the Model Context Protocol.

### Configuring Claude Code

Create a [`.mcp.json`](https://github.com/t8y2/dbx/blob/main/.mcp.json) file in your project root to register the DBX server with Claude Code:

```json
{
  "mcpServers": {
    "dbx": {
      "command": "dbx-mcp-server"
    }
  }
}

```

This configuration allows Claude Code to discover available tools automatically. You can then ask the agent to "List my database connections" or "Query the average salary from employees."

### Portable Windows Configuration

If you use a portable Windows build of DBX, specify the data directory using the `DBX_DATA_DIR` environment variable:

```json
{
  "mcpServers": {
    "dbx": {
      "command": "dbx-mcp-server",
      "env": {
        "DBX_DATA_DIR": "D:\\DBX_x64-portable\\data"
      }
    }
  }
}

```

## Database Interaction and Safety Controls

The MCP server exposes database functionality through registered tools that handle connection resolution, SQL safety evaluation, and result formatting.

### Connection Resolution and Scope Isolation

The server resolves connections using `resolveConnection` and `loadScopedConnections` functions (lines 97-120 in [`packages/mcp-server/src/index.ts`](https://github.com/t8y2/dbx/blob/main/packages/mcp-server/src/index.ts)). You can restrict the server to a specific connection or database using environment variables:

```bash
export DBX_MCP_SCOPE_CONNECTION_NAME=local-pg
export DBX_MCP_SCOPE_DATABASE=shop
export DBX_MCP_ALLOW_WRITES=0
dbx-mcp-server

```

When these variables are set, all tool calls automatically target the specified connection and database, and write operations are rejected.

### Safety Gating and Write Permissions

Before executing any SQL, the server calls `evaluateSqlSafety` (lines 90-94, 191-197) to enforce security policies:

- **Write statements** (`INSERT`, `UPDATE`, `DELETE`) are allowed by default but can be blocked by setting `DBX_MCP_ALLOW_WRITES=0`.
- **Dangerous statements** (`DROP`, `TRUNCATE`, `ALTER`) and risky Redis commands (`KEYS`, `FLUSHALL`, `EVAL`) are blocked unless `DBX_MCP_ALLOW_DANGEROUS_SQL` is set to `1`.

The safety logic reads these flags via `sqlSafetyFromEnv` and applies them to every query execution.

## Desktop UI Integration

When running the DBX desktop application, the MCP server can trigger UI actions through a local TCP bridge, enabling agents to open tables or display results visually.

### The Rust Bridge Implementation

The bridge ([`src-tauri/src/commands/mcp_bridge.rs`](https://github.com/t8y2/dbx/blob/main/src-tauri/src/commands/mcp_bridge.rs)) creates a TCP server that writes its port to a file named `mcp-bridge-port` in the DBX data directory. The Node.js server reads this file to establish communication.

When an agent calls `dbx_open_table` or `dbx_execute_and_show`, the server uses the `bridgeRequest` helper (lines 86-90) to forward requests to the bridge, which emits Tauri events:

- `mcp-open-table`: Triggered by `handle_open_table` (lines 526-583) to open a specific table view
- `mcp-execute-query`: Triggered by `handle_execute_query` to run queries and display results

The bridge constructs events like `McpOpenTableEvent` containing the connection ID, database, schema, and table name, then emits them to the Tauri frontend.

## Programmatic Usage and CLI

Beyond AI agent integration, you can interact with the MCP server programmatically or through the dedicated CLI package.

### Using the MCP Server from Node.js

Import the MCP client SDK to call tools directly from JavaScript:

```javascript
import { McpClient } from "@modelcontextprotocol/sdk/client/stdio";

(async () => {
  const client = new McpClient({ name: "my-tool", version: "1.0" });
  const result = await client.callTool("dbx_execute_query", {
    connection_name: "local-pg",
    sql: "SELECT count(*) FROM orders"
  });
  console.log(result);
})();

```

The response returns as a markdown-formatted table with row counts.

### Command-Line Interface with @dbx-app/cli

The `@dbx-app/cli` package provides standalone commands that mirror MCP tools:

```bash
npm install -g @dbx-app/cli
dbx connections list --json
dbx query local-pg "SELECT * FROM users LIMIT 10" --json
dbx schema context --connection local-pg --max-tables 5

```

These commands communicate with the same backend as the MCP server, ensuring consistent behavior across interfaces.

## Summary

- **Zero-configuration setup**: The MCP server automatically discovers the DBX SQLite store at standard platform locations (`~/.local/share/com.dbx.app/dbx.db`, `~/Library/Application Support/com.dbx.app/dbx.db`, or `%APPDATA%\com.dbx.app\dbx.db`).
- **Scope isolation**: Use `DBX_MCP_SCOPE_CONNECTION_NAME` and `DBX_MCP_SCOPE_DATABASE` to restrict AI agents to specific databases.
- **Safety controls**: Configure `DBX_MCP_ALLOW_WRITES` and `DBX_MCP_ALLOW_DANGEROUS_SQL` to prevent destructive operations.
- **Desktop integration**: The Rust bridge ([`src-tauri/src/commands/mcp_bridge.rs`](https://github.com/t8y2/dbx/blob/main/src-tauri/src/commands/mcp_bridge.rs)) enables agents to open tables directly in the DBX UI via TCP socket communication.
- **Multiple interfaces**: Access database functionality through Claude Code, direct Node.js clients, or the `@dbx-app/cli` package.

## Frequently Asked Questions

### Where does the MCP server store connection data?

The server reads connection profiles from the DBX SQLite database file located at platform-specific paths: `~/.local/share/com.dbx.app/dbx.db` on Linux, `~/Library/Application Support/com.dbx.app/dbx.db` on macOS, and `%APPDATA%\com.dbx.app\dbx.db` on Windows. Passwords are stored securely in the OS keyring and accessed through the backend layer.

### How do I restrict the MCP server to a single database?

Set the environment variables `DBX_MCP_SCOPE_CONNECTION_ID`, `DBX_MCP_SCOPE_CONNECTION_NAME`, or `DBX_MCP_SCOPE_DATABASE` before starting the server. These variables filter all tool calls to the specified connection, preventing the AI agent from accessing other configured databases. This is particularly useful for project-specific assistants.

### Can the MCP server execute write operations?

Yes, by default the server allows `INSERT`, `UPDATE`, and `DELETE` statements. However, dangerous operations like `DROP`, `TRUNCATE`, and `ALTER` are blocked unless you set `DBX_MCP_ALLOW_DANGEROUS_SQL=1`. You can disable all writes by setting `DBX_MCP_ALLOW_WRITES=0`. The `evaluateSqlSafety` function in the backend enforces these rules before query execution.

### How does the desktop bridge work for opening tables?

When you call `dbx_open_table` or `dbx_execute_and_show`, the MCP server sends an HTTP-style request to the Rust bridge running inside the DBX desktop app. The bridge ([`src-tauri/src/commands/mcp_bridge.rs`](https://github.com/t8y2/dbx/blob/main/src-tauri/src/commands/mcp_bridge.rs)) emits Tauri events (`mcp-open-table` or `mcp-execute-query`) that the frontend captures to open the requested table view or display query results. The bridge port is discovered via a file named `mcp-bridge-port` in the DBX data directory.