# How DBX Integrates with AI Assistants Using the MCP Protocol

> Learn how DBX integrates with AI assistants such as Claude Code and Cursor using the MCP protocol. This guide explains how the MCP server package enables SQL execution and connection management via JSON-RPC.

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

---

**DBX integrates with AI assistants through a dedicated MCP server package that exposes database connections via the Model Context Protocol, enabling agents like Claude Code and Cursor to execute SQL and manage connections through JSON-RPC calls.**

DBX, an open-source database management tool from the `t8y2/dbx` repository, extends its capabilities beyond the desktop interface by implementing the Model Context Protocol (MCP). This integration transforms DBX into a context-aware backend for AI coding agents, allowing them to query your local connection store and execute SQL against configured databases while maintaining strict security controls.

## Architecture Overview

The DBX MCP integration follows a four-tier request flow that bridges AI agents with your local database infrastructure:

1. **AI Agent → MCP Server** – The agent communicates via MCP-compliant JSON-RPC calls to the `@dbx-app/mcp-server` package running on localhost.
2. **MCP Server → DBX Core** – The server reads connection metadata from the local `dbx.db` SQLite file. For UI-related actions, it forwards Tauri events through the bridge implemented in [`src-tauri/src/commands/mcp_bridge.rs`](https://github.com/t8y2/dbx/blob/main/src-tauri/src/commands/mcp_bridge.rs).
3. **DBX Desktop → Database** – The Rust core (`dbx-core` crate) handles database authentication and query execution.
4. **Database → AI Agent** – Results return through the chain as structured JSON, allowing the agent to iterate on queries or present data.

This architecture keeps sensitive database credentials within the DBX desktop application while exposing only the necessary RPC interface to external agents.

## Core Components

The integration relies on three primary implementation layers:

**MCP Server Package** ([`packages/mcp-server/src/index.ts`](https://github.com/t8y2/dbx/blob/main/packages/mcp-server/src/index.ts))  
Exposes HTTP endpoints on `localhost:4221` and registers protocol methods including `list_connections`, `describe_table`, `execute_sql`, and `open_table`.

**Tauri Bridge** ([`src-tauri/src/commands/mcp_bridge.rs`](https://github.com/t8y2/dbx/blob/main/src-tauri/src/commands/mcp_bridge.rs))  
Acts as the intermediary that receives commands from the Node.js MCP server and dispatches them to the Rust core or desktop UI. This bridge enables agents to trigger visual actions like opening tables in the DBX interface.

**Safety Layer** ([`crates/dbx-core/src/ai.rs`](https://github.com/t8y2/dbx/blob/main/crates/dbx-core/src/ai.rs))  
Validates SQL statements against environment-based permission flags before execution. By default, all MCP sessions are restricted to read-only operations regardless of the database user's privileges.

**Command Helpers** ([`src-tauri/src/commands/mcp.rs`](https://github.com/t8y2/dbx/blob/main/src-tauri/src/commands/mcp.rs))  
Manages MCP server installation, binary updates, and version compatibility checking between the desktop app and the server package.

## Configuring the MCP Server

To enable AI assistant access, configure your MCP client to launch the DBX server binary.

### Automatic Configuration via .mcp.json

Create an [`.mcp.json`](https://github.com/t8y2/dbx/blob/main/.mcp.json) file in your project root:

```json
{
  "mcpServers": {
    "dbx": {
      "command": "npx",
      "args": ["-y", "@dbx-app/mcp-server"]
    }
  }
}

```

Claude Code, Cursor, and other MCP-compatible agents will automatically launch the server when detecting this configuration.

### Manual Server Startup

For debugging or standalone usage, start the server directly:

```bash
npx @dbx-app/mcp-server

```

The process will bind to `http://127.0.0.1:4221` and log connection status to stdout.

## Query Execution Examples

Once running, the server accepts standard JSON-RPC requests over HTTP.

### Listing Available Connections

Retrieve all configured database connections from the local store:

```bash
curl -X POST http://127.0.0.1:4221/mcp \
  -H "Content-Type: application/json" \
  -d '{
        "jsonrpc": "2.0",
        "id": 1,
        "method": "list_connections",
        "params": {}
      }'

```

The response includes connection IDs, types, and host information required for subsequent queries.

### Executing Read-Only SQL

Run analytical queries against a specific connection:

```bash
curl -X POST http://127.0.0.1:4221/mcp \
  -H "Content-Type: application/json" \
  -d '{
        "jsonrpc": "2.0",
        "id": 2,
        "method": "execute_sql",
        "params": {
          "connection_id": "1",
          "sql": "SELECT count(*) FROM users"
        }
      }'

```

By default, the safety layer in [`crates/dbx-core/src/ai.rs`](https://github.com/t8y2/dbx/blob/main/crates/dbx-core/src/ai.rs) rejects any DML statements (INSERT, UPDATE, DELETE) at the parsing stage.

### Opening Tables in the DBX UI

Trigger the desktop application to open a specific table view:

```bash
curl -X POST http://127.0.0.1:4221/mcp \
  -H "Content-Type: application/json" \
  -d '{
        "jsonrpc": "2.0",
        "id": 3,
        "method": "open_table",
        "params": {
          "connection_id": "1",
          "schema": "public",
          "table": "users"
        }
      }'

```

This method requires the DBX desktop application to be running, as the MCP server emits a Tauri event through [`mcp_bridge.rs`](https://github.com/t8y2/dbx/blob/main/mcp_bridge.rs) to instantiate the UI tab.

## Security Model and Permissions

DBX implements a defense-in-depth strategy for AI agent interactions through environment variable controls:

**Read-Only Default** – All SQL execution begins in read-only mode. The parser in [`crates/dbx-core/src/ai.rs`](https://github.com/t8y2/dbx/blob/main/crates/dbx-core/src/ai.rs) explicitly blocks data modification statements unless explicitly authorized.

**Write Operations** – To enable INSERT, UPDATE, or DELETE statements, launch the server with:

```bash
DBX_MCP_ALLOW_WRITES=1 npx @dbx-app/mcp-server

```

**Dangerous Operations** – Schema-altering commands (DROP, TRUNCATE, ALTER) require an additional escalation flag:

```bash
DBX_MCP_ALLOW_WRITES=1 DBX_MCP_ALLOW_DANGEROUS_SQL=1 npx @dbx-app/mcp-server

```

These flags prevent accidental data loss when agents generate speculative or exploratory queries. The documentation in `docs/content/docs/mcp.mdx` recommends keeping dangerous SQL disabled for production database connections.

## Summary

- **DBX exposes database connections to AI agents via the `@dbx-app/mcp-server` package**, implementing the Model Context Protocol for standardized communication.
- **The integration spans TypeScript and Rust layers**, with the MCP server handling HTTP transport and the Tauri bridge ([`src-tauri/src/commands/mcp_bridge.rs`](https://github.com/t8y2/dbx/blob/main/src-tauri/src/commands/mcp_bridge.rs)) coordinating with the Rust core.
- **Security defaults prioritize safety** through read-only restrictions controlled by environment variables `DBX_MCP_ALLOW_WRITES` and `DBX_MCP_ALLOW_DANGEROUS_SQL`.
- **Agents can execute SQL and trigger UI actions**, allowing both headless data retrieval and visual exploration within the DBX desktop interface.

## Frequently Asked Questions

### Which AI assistants can connect to DBX via MCP?

Any agent supporting the Model Context Protocol can integrate with DBX, including Claude Code, Cursor, Windsurf, and Windsurf-like environments. The server communicates via standard JSON-RPC over HTTP, making it compatible with any MCP-compliant client that can launch the `npx @dbx-app/mcp-server` binary.

### Is it safe to enable write operations for AI agents?

Write operations carry inherent risks when delegated to autonomous agents. DBX mitigates this by requiring explicit opt-in through the `DBX_MCP_ALLOW_WRITES` environment variable. For production databases, maintain the default read-only configuration and enable writes only in development environments or with strict query logging enabled.

### Why does the `open_table` method require the DBX desktop app?

The `open_table` method triggers visual UI changes rather than returning raw data. According to the implementation in [`src-tauri/src/commands/mcp_bridge.rs`](https://github.com/t8y2/dbx/blob/main/src-tauri/src/commands/mcp_bridge.rs), this method emits a Tauri event that the desktop application must receive and render. SQL execution methods like `execute_sql` function independently of the UI, but interface-dependent actions require an active DBX desktop session.

### How does the MCP server locate my database connections?

The server reads connection metadata from a local SQLite file named `dbx.db` stored in the user's configuration directory. It does not connect to remote databases directly; instead, it delegates actual database connections to the Rust core (`crates/dbx-core`), which manages connection pooling, authentication, and driver-specific protocols.