# How to Integrate AI Agents with DBX Using MCP: A Complete Technical Guide

> Learn to integrate AI agents with DBX using MCP a complete technical guide. Connect coding assistants like Claude Code and Cursor to your databases via Node.js.

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

---

**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 backend and desktop UI.**

The `t8y2/dbx` repository provides a native MCP server implementation that turns database interactions into structured tool calls for large language models. This integration allows AI agents to introspect schemas, execute read-only or write-enabled queries, and even open tables directly in the DBX desktop application without requiring manual configuration files for each connection.

## Architecture Overview

The DBX MCP integration consists of four distinct layers that handle protocol translation, safety enforcement, and UI coordination.

| Component | Role | Source Location |
|-----------|------|-----------------|
| **MCP Server** | Node.js process exposing `dbx_*` tools via STDIO JSON-RPC | [`packages/mcp-server/src/index.ts`](https://github.com/t8y2/dbx/blob/main/packages/mcp-server/src/index.ts) |
| **MCP SDK** | Generic server implementation and transport handling | `@modelcontextprotocol/sdk/server` (external dependency) |
| **Backend Core** | Connection pooling, SQL execution, and safety evaluation | `crates/dbx-core` (Node core bindings) |
| **Desktop Bridge** | TCP bridge forwarding UI requests to the Tauri frontend | [`src-tauri/src/commands/mcp_bridge.rs`](https://github.com/t8y2/dbx/blob/main/src-tauri/src/commands/mcp_bridge.rs) |

The server automatically discovers the DBX SQLite store (`dbx.db`) at platform-specific locations (`~/.local/share/com.dbx.app/` on Linux, `~/Library/Application Support/com.dbx.app/` on macOS, or `%APPDATA%\com.dbx.app\` on Windows), eliminating the need for manual database configuration.

## Configuration and Setup

### Minimal Configuration for 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:

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

```

Claude Code will automatically discover this configuration and expose the DBX toolset. You can then issue natural language commands like "List my database connections" or "Query the average salary from the employees table."

### Portable Windows Builds

If you run the portable Windows edition, specify the data directory explicitly:

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

```

## Core MCP Tools and Capabilities

The server registers five primary tools in [`packages/mcp-server/src/index.ts`](https://github.com/t8y2/dbx/blob/main/packages/mcp-server/src/index.ts) starting at line 31:

- **`dbx_list_connections`** – Returns all configured database profiles from the SQLite store
- **`dbx_get_schema_context`** – Provides table schemas and sample data for prompt enrichment
- **`dbx_execute_query`** – Executes SQL against a specified connection and returns markdown-formatted results
- **`dbx_open_table`** – Requests the DBX desktop UI to open a specific table view
- **`dbx_execute_and_show`** – Executes query and displays results in the desktop application

### Connection Resolution and Scope Isolation

The MCP server supports scoped sessions through environment variables defined in `resolveConnection` and `loadScopedConnections` (lines 97-120 of [`index.ts`](https://github.com/t8y2/dbx/blob/main/index.ts)). When present, these variables restrict all tool calls to a specific connection or database:

```bash
export DBX_MCP_SCOPE_CONNECTION_NAME=local-pg
export DBX_MCP_SCOPE_DATABASE=shop

```

This isolation prevents AI agents from accidentally querying production databases when working on development environments.

## Safety and Security Features

### SQL Safety Evaluation

Before executing any query, the server invokes `evaluateSqlSafety` (lines 90-94, 191-197) to classify the SQL statement risk level. The safety engine reads two environment variables:

- **`DBX_MCP_ALLOW_WRITES`** – Defaults to enabled; set to `0` to block `INSERT`, `UPDATE`, and `DELETE` statements
- **`DBX_MCP_ALLOW_DANGEROUS_SQL`** – Defaults to disabled; must be set to `1` to allow `DROP`, `TRUNCATE`, `ALTER`, and destructive Redis commands like `FLUSHALL` or `KEYS`

```bash

# Read-only session with strict safety

export DBX_MCP_ALLOW_WRITES=0
export DBX_MCP_ALLOW_DANGEROUS_SQL=0
dbx-mcp-server

```

### Environment-Based Access Control

The `sqlSafetyFromEnv` function dynamically constructs safety rules based on these flags, ensuring that AI agents cannot bypass restrictions through prompt engineering alone.

## Desktop UI Integration

### The Rust Bridge Architecture

When running the DBX desktop application, the MCP server communicates with the Tauri frontend through a local TCP bridge implemented in [`src-tauri/src/commands/mcp_bridge.rs`](https://github.com/t8y2/dbx/blob/main/src-tauri/src/commands/mcp_bridge.rs). The bridge writes its listening port to a file named `mcp-bridge-port` in the DBX data directory, which the Node.js server reads at startup.

UI-specific tools like `dbx_open_table` and `dbx_execute_and_show` utilize the `bridgeRequest` helper (lines 86-90) to forward HTTP-style requests to the Rust layer.

### Opening Tables in the DBX UI

When an AI agent requests to open a table, the server sends a payload to the bridge:

```typescript
// From packages/mcp-server/src/index.ts
return bridgeRequest("/open-table", { 
  connection_name, 
  table, 
  database, 
  schema 
}, `Opened ${table} in DBX`);

```

The Rust bridge constructs a `McpOpenTableEvent` and emits it via Tauri's event system:

```rust
// From src-tauri/src/commands/mcp_bridge.rs (lines 526-583)
let event = McpOpenTableEvent {
    connection_id: config.id.clone(),
    database: req.database.unwrap_or_else(|| config.database.clone().unwrap_or_default()),
    schema: req.schema,
    table: req.table,
};
let _ = app.emit("mcp-open-table", &event);

```

The Tauri frontend listens for `mcp-open-table` events and immediately renders the requested table view, providing seamless integration between agent actions and visual confirmation.

## Command Line Usage

### Using the MCP Server Directly

Install the server globally and run it in STDIO mode:

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

```

You can also interact programmatically using the MCP SDK:

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

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);

```

### Alternative CLI Package

For standalone automation without an MCP host, use the dedicated CLI package:

```bash
npm install -g @dbx-app/cli

# List all connections

dbx connections list --json

# Execute query with JSON output

dbx query local-pg "SELECT * FROM users LIMIT 10" --json

# Get schema context for prompt engineering

dbx schema context --connection local-pg --max-tables 5

```

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

## Summary

- **DBX MCP server** exposes database tools via STDIO JSON-RPC, enabling direct AI agent integration with Claude Code, Cursor, and Windsurf.
- **Zero-configuration setup** automatically discovers the SQLite store at platform-specific paths, with optional `DBX_DATA_DIR` override for portable installations.
- **Safety gating** via `evaluateSqlSafety` blocks dangerous operations unless explicitly enabled through `DBX_MCP_ALLOW_DANGEROUS_SQL` or `DBX_MCP_ALLOW_WRITES` environment variables.
- **Scope isolation** restricts agents to specific connections using `DBX_MCP_SCOPE_CONNECTION_NAME` or `DBX_MCP_SCOPE_DATABASE` variables.
- **Desktop bridge** in [`src-tauri/src/commands/mcp_bridge.rs`](https://github.com/t8y2/dbx/blob/main/src-tauri/src/commands/mcp_bridge.rs) enables UI coordination, allowing agents to open tables directly in the DBX application through Tauri events.

## Frequently Asked Questions

### How does the MCP server locate my DBX configuration?

The server automatically resolves the DBX SQLite store path based on the operating system: `~/.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. For portable Windows builds, set the `DBX_DATA_DIR` environment variable to the data directory containing `dbx.db`.

### Can I restrict an AI agent to a single database or connection?

Yes. Set the `DBX_MCP_SCOPE_CONNECTION_NAME`, `DBX_MCP_SCOPE_CONNECTION_ID`, or `DBX_MCP_SCOPE_DATABASE` environment variables before starting the server. The `resolveConnection` function in [`packages/mcp-server/src/index.ts`](https://github.com/t8y2/dbx/blob/main/packages/mcp-server/src/index.ts) filters all tool calls to match these scopes, preventing cross-database queries.

### What SQL operations are blocked by default?

The safety engine in `evaluateSqlSafety` allows standard write operations (`INSERT`, `UPDATE`, `DELETE`) by default but blocks dangerous statements including `DROP`, `TRUNCATE`, and `ALTER`. Destructive Redis commands like `FLUSHALL`, `KEYS`, and `EVAL` are also blocked. Enable them by setting `DBX_MCP_ALLOW_DANGEROUS_SQL=1`.

### How does the desktop integration work when I ask an agent to "open a table"?

When the agent invokes `dbx_open_table`, the Node.js server sends a request to the Rust bridge via TCP. The `handle_open_table` function in [`src-tauri/src/commands/mcp_bridge.rs`](https://github.com/t8y2/dbx/blob/main/src-tauri/src/commands/mcp_bridge.rs) emits a `mcp-open-table` Tauri event containing the connection ID and table metadata. The DBX frontend listens for this event and immediately opens the table view in the application window.