# DBX MCP Server Integration with Claude Code and Cursor: A Complete Guide

> Integrate DBX MCP server with Claude Code and Cursor to securely query databases. Expose DBX connections as Model Context Protocol tools for AI agents via STDIO.

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

---

**DBX MCP server integration enables Claude Code and Cursor to query your databases securely by exposing DBX connections as Model Context Protocol tools that AI agents can invoke via STDIO.**

The DBX MCP server (`@dbx-app/mcp-server`) bridges the gap between AI coding assistants and your database infrastructure. By implementing the Model Context Protocol (MCP), this integration allows Claude Code and Cursor to discover, explore, and query databases configured in DBX without leaving your editor. The server acts as a secure gateway, enforcing the same safety policies used by the DBX UI while translating natural language requests into structured database operations.

## How the DBX MCP Server Works

At its core, the DBX MCP server is instantiated in [`packages/mcp-server/src/index.ts`](https://github.com/t8y2/dbx/blob/main/packages/mcp-server/src/index.ts) where a `McpServer` instance is created and configured with a comprehensive toolset. The server reads DBX's SQLite configuration file (`dbx.db`) to discover available connections and exposes them to AI agents through a standardized JSON-RPC interface over STDIO.

### Tool Registration

The server registers six primary tools that map directly to database operations. In [`packages/mcp-server/src/index.ts`](https://github.com/t8y2/dbx/blob/main/packages/mcp-server/src/index.ts) (lines 79‑250), the following tools are exposed:

- **`dbx_list_connections`** – Discovers all configured database connections
- **`dbx_list_tables`** – Enumerates tables within a specific connection
- **`dbx_describe_table`** – Retrieves schema metadata for table exploration
- **`dbx_execute_query`** – Executes read-only SQL queries against SQL databases
- **`dbx_execute_redis_command`** – Runs commands against Redis instances
- **`dbx_open_table`** – Triggers the DBX desktop UI to open a specific table (Tauri bridge)

Each tool validates input parameters, resolves the requested connection by name or ID, and forwards the request to the DBX backend with proper context scoping.

### Connection Resolution

The server supports sophisticated connection discovery through environment variable scoping. As implemented in [`packages/mcp-server/src/index.ts`](https://github.com/t8y2/dbx/blob/main/packages/mcp-server/src/index.ts) (lines 95‑124), the server checks for `DBX_MCP_SCOPE_*` environment variables to filter connections, allowing you to scope AI agent access to specific subsets of your database infrastructure. This is particularly useful for separating production and development environments within the same DBX configuration.

### Safety Enforcement

Before executing any SQL or Redis command, the server invokes safety functions from `@dbx-app/node-core`. The `evaluateSqlSafety` and `evaluateRedisCommandSafety` functions (referenced in lines 44‑52 of [`packages/mcp-server/src/index.ts`](https://github.com/t8y2/dbx/blob/main/packages/mcp-server/src/index.ts)) enforce read-only mode, block dangerous SQL patterns, and apply the same security policies used by the DBX graphical interface. This ensures that AI agents cannot execute destructive operations like `DROP TABLE` or `DELETE` without explicit configuration changes.

## Configuring Claude Code and Cursor

Integration requires minimal configuration. Both Claude Code and Cursor recognize MCP servers through a [`.mcp.json`](https://github.com/t8y2/dbx/blob/main/.mcp.json) configuration file placed in your project root.

### Installation

First, install the MCP server globally:

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

```

### Configuration File

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

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

```

Alternatively, you can use `npx` to run the server without global installation:

```json
{
  "mcpServers": {
    "dbx": {
      "command": "npx @dbx-app/mcp-server"
    }
  }
}

```

Once configured, both Claude Code and Cursor automatically discover the server on startup and populate their tool palettes with the available DBX operations.

## Communication Flow and Examples

When you ask Claude Code or Cursor a database-related question, the AI agent constructs a JSON-RPC request and sends it to the MCP server over STDIO. The server processes the request, executes the appropriate tool, and returns a markdown-formatted response.

### Listing Connections

When the AI needs to discover available databases, it sends:

```json
{
  "method": "dbx_list_connections",
  "params": {}
}

```

The server returns a formatted table of connections including names, types, and connection status.

### Executing Queries

For SQL execution, the request structure includes connection targeting:

```json
{
  "method": "dbx_execute_query",
  "params": {
    "connection_name": "local-pg",
    "sql": "SELECT COUNT(*) AS total FROM orders"
  }
}

```

The server validates the query against safety policies, executes it against the resolved connection, and returns results in a markdown table format:

```

| Column | Type | Nullable | Default | Comment |
|--------|------|----------|---------|---------|
| total  | int  | NO       |         |         |

```

### Desktop Integration

For operations requiring the DBX UI, such as opening a table for visual inspection:

```json
{
  "method": "dbx_open_table",
  "params": {
    "connection_name": "local-pg",
    "table": "orders"
  }
}

```

This invokes the Tauri bridge to launch the DBX desktop application focused on the specified table.

## Summary

- **DBX MCP server** ([`packages/mcp-server/src/index.ts`](https://github.com/t8y2/dbx/blob/main/packages/mcp-server/src/index.ts)) exposes database operations as standardized tools that Claude Code and Cursor can invoke
- **Safety first**: All queries pass through `evaluateSqlSafety` and `evaluateRedisCommandSafety` from `@dbx-app/node-core` to prevent destructive operations
- **Configuration**: Add a [`.mcp.json`](https://github.com/t8y2/dbx/blob/main/.mcp.json) file with the `dbx-mcp-server` command to enable automatic discovery by AI agents
- **Scoped access**: Use `DBX_MCP_SCOPE_*` environment variables to limit which connections AI agents can access
- **STDIO transport**: The server communicates via JSON-RPC over STDIO, making it compatible with any MCP-compliant client

## Frequently Asked Questions

### What is the Model Context Protocol in DBX?

The Model Context Protocol (MCP) is a standardized interface that allows AI assistants to interact with external tools and data sources. In DBX, the MCP server (`@dbx-app/mcp-server`) implements this protocol to expose your configured database connections as tools that Claude Code and Cursor can discover and invoke. The server translates AI agent requests into secure database operations while maintaining the context of your DBX configuration stored in `dbx.db`.

### How do I restrict which databases Claude Code can access through DBX?

You can scope AI agent access using environment variables. The DBX MCP server checks for `DBX_MCP_SCOPE_*` variables (as implemented in [`packages/mcp-server/src/index.ts`](https://github.com/t8y2/dbx/blob/main/packages/mcp-server/src/index.ts), lines 95‑124) to filter available connections. By setting these variables before starting your AI assistant, you can limit the exposed connections to specific subsets of your infrastructure, effectively creating isolated environments for different projects or sensitivity levels.

### Is it safe to let AI agents execute SQL queries through the DBX MCP server?

Yes, the integration includes multiple safety layers. Before executing any SQL, the server calls `evaluateSqlSafety` from `@dbx-app/node-core` to enforce read-only policies and block dangerous commands. By default, the MCP server prevents destructive operations like `DROP`, `DELETE`, or `UPDATE` statements, mirroring the safety restrictions of the DBX UI. You can verify these protections in [`packages/mcp-server/src/index.ts`](https://github.com/t8y2/dbx/blob/main/packages/mcp-server/src/index.ts) (lines 44‑52) where safety checks are mandatory prerequisites for query execution.

### Can I use the DBX MCP server with editors other than Claude Code and Cursor?

While this guide focuses on Claude Code and Cursor, any AI assistant or editor that supports the Model Context Protocol can integrate with the DBX MCP server. The server communicates via STDIO using JSON-RPC, making it compatible with any MCP client. As long as the client can read the [`.mcp.json`](https://github.com/t8y2/dbx/blob/main/.mcp.json) configuration and spawn the `dbx-mcp-server` process, it can access the full suite of database tools including listing connections, describing schemas, and executing safety-checked queries.