How to Configure MCP Server with DBX for AI Agent Integration

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

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

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

{
  "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). You can restrict the server to a specific connection or database using environment variables:

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

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:

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

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