MCP Integration

What is MCP?

MCP (Model Context Protocol) lets AI clients call external tools. DBX MCP gives your AI assistant access to the database connections configured in DBX.

AI agent → DBX MCP → your database → results
                    ↘ DBX desktop app (open or display results)

Quick Start

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

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

Supported AI Agents

Tools

DBX MCP currently provides 12 tools:

Connection-scoped sessions hide connection-mutating and desktop UI tools.

Stateful Query Sessions

Regular dbx_execute_query calls are independent. When a workflow must preserve database session state, call dbx_open_session first and pass its returned sessionId to later dbx_execute_query calls. Typical uses include:

• USE or database-context changes
• Temporary tables
• Session variables and settings
• Explicit transactions or multi-step diagnostics that require one connection

Sessions support SQL connections only and are bound to one connection and database. Unknown, closed, or expired IDs fail instead of silently falling back to an ordinary query. Call dbx_close_session when finished. Idle sessions are reclaimed after 30 minutes, and the server allows at most 32 concurrent sessions.

Database Access

Local connections

MCP uses the connections saved in DBX. Connections that execute natively do not require the Desktop app to stay open; bridge-backed or installed Agent/driver paths still depend on their runtime.

Common local paths include:

Set DBX_DATA_DIR to the directory containing dbx.db. Do not set it to the file itself.

Native SQL, standalone Redis, and MongoDB paths can execute directly through MCP. SSH, cluster, vendor-specific, external-driver, and Agent/JDBC availability depends on the connection configuration and installed DBX components. Do not assume that every database supported by the DBX product is bundled into the standalone MCP binary.

DuckDB uses the standalone DBX DuckDB driver. Install it from DBX Driver Manager before querying a DuckDB connection through local MCP. The MCP binary includes the sidecar client but does not bundle the DuckDB engine.

Agent/JDBC databases

Oracle, KingbaseES, and XuguDB require their matching native DBX Agent but no JRE. Dameng, DB2, Hive, Trino, Snowflake, SAP HANA, and other JDBC Agent connections require the matching Agent, JDBC driver, and JRE. Install the required component in DBX before using MCP.

DBX Web and Docker mode

Set DBX_WEB_URL to use a deployed DBX Web backend instead of local connections. If the Web login is protected, also set DBX_WEB_PASSWORD to the same login password.

DBX Web requests honor the standard system proxy environment variables: HTTPS_PROXY/https_proxy for https URLs, HTTP_PROXY/http_proxy for http URLs, with ALL_PROXY/all_proxy as the fallback and NO_PROXY/no_proxy (comma-separated hosts, e.g. localhost,127.0.0.1,.internal.example) as the bypass list. An empty or unset proxy value means direct connection (no proxy). HTTP, HTTPS, and SOCKS5 proxies are supported (http://127.0.0.1:7890 or socks5://127.0.0.1:1080); proxies requiring authentication use the standard user:password@host:port URL form, e.g. http://admin:admin123@127.0.0.1:7890. To attach extra headers to every DBX Web request (for example token auth in front of a gateway), set DBX_WEB_HEADERS to a JSON object of header names and string values, e.g. {"Authorization":"Bearer <token>"}. For self-signed HTTPS backends, certificate verification is on by default; set DBX_WEB_INSECURE_SKIP_VERIFY=1 to disable verification, or set DBX_WEB_CA_CERT to a PEM/DER CA file to trust a private CA. The same variables are honored by the DBX CLI in Web mode.

DBX Web and Docker require the same standalone DuckDB driver. Install it from Driver Manager after the first launch. Docker stores installed drivers under /app/data/agents, so they persist when /app/data is mounted as a volume.

Desktop UI tools

dbx_open_table and dbx_execute_and_show require the DBX desktop app and are unavailable in Web mode or when scoped policy hides UI tools. Whether other tools need Desktop depends on whether the connection uses native execution or a bridge/Agent path.

Safety and Environment Variables

DBX stores one authoritative MCP policy under Settings → MCP and reloads it for every request:

An ineffective condition such as WHERE TRUE, WHERE 1 = 1, _id: {$exists: true}, or an opaque MongoDB filter remains high risk. Connection-level read-only protection, production protection, database credentials, and the MCP connection allowlist remain upper bounds in every mode.

Updated servers do not let DBX_MCP_ALLOW_WRITES or DBX_MCP_ALLOW_DANGEROUS_SQL widen the DBX policy. For upgrade compatibility, DBX_MCP_ALLOW_WRITES=0 (or false) still keeps MCP read-only until a central policy is saved for the first time. After that, the central policy is authoritative and the legacy permission variables are ignored. Legacy connection-scope variables can only narrow the DBX allowlist.

Troubleshooting

Requirements

• Node.js 18.18.0 or newer
• DBX installed with at least one connection configured
• Matching DBX Agent, JDBC driver, and JRE for Agent/JDBC connections
• DBX desktop app running when using the two UI tools