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

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

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 file in your project root to register the DBX server:

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

{
  "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 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). When present, these variables restrict all tool calls to a specific connection or database:

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

# 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. 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:

// 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:

// 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:

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

You can also interact programmatically using the MCP SDK:

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:

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 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 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 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.

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