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)

Native installation (recommended)

No Node.js is required. On macOS or Linux:

curl -fsSL https://dbxio.com/install-mcp | sh

On Windows, run in PowerShell:

irm https://dbxio.com/install-mcp.ps1 | iex

The installer verifies the download, installs dbx-mcp into ~/.dbx/bin, and prints ready-to-paste Claude Code, Cursor, Codex, ZCode, and generic MCP configurations. Use the expanded absolute executable path it prints, not ~ or the bare dbx-mcp command: GUI clients do not necessarily inherit your shell's PATH. Existing environment settings such as DBX_DATA_DIR remain applicable. DBX desktop settings prefer a discovered native binary, with the existing npm launcher as fallback.

Rerun the same install command to upgrade. A matching version reports already up to date. Version probing uses dbx-mcp --version, falling back to ~/.dbx/bin/.dbx-mcp-version for older binaries. Offline installation fails without replacing an existing binary. Download sources are tried in order: npmjs, npmmirror, then GitHub Releases; an integrity mismatch stops installation.

Homebrew is also available on macOS and Linux:

brew install t8y2/tap/dbx-mcp
brew upgrade t8y2/tap/dbx-mcp

For Homebrew client configurations, use the absolute path printed by echo "$(brew --prefix)/bin/dbx-mcp". This installs the MCP server, not the separate dbx CLI.

The npm/npx channel remains supported unchanged. DBX desktop now installs the standalone native server by default and shows existing npm users a recommended native migration action. Migration keeps the npm package as a fallback and does not rewrite external client files automatically: replace their launch command with the generated native absolute path, remove Node/npx arguments, and preserve env. Removing the old global package with npm rm -g @dbx-app/mcp-server remains optional. The desktop can update and uninstall the active standalone or Homebrew native installation; uninstalling a standalone native installation reveals any retained npm installation again.

Quick Start with npm

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

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

Supported AI Agents

DeepSeek Harness

DeepSeek Harness loads MCP servers through Cordis plugin entries instead of an mcpServers JSON object. After installing @dbx-app/mcp-server, merge the following entry into $DSH_HOME/profiles/web/cordis.patch.yml for the web profile: If DSH_HOME is unset, it defaults to ~/.dsh.

- insert:
    - id: mcp-dbx
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: dbx
        transport: stdio
        command: dbx-mcp-server

Keep the top-level - insert: wrapper and do not overwrite other patch entries. For another DSH profile, replace web in the path with that profile name. The dbx-mcp-server command must be available on the DSH process's PATH; use the full executable path when necessary.

Run dsh web --dump-config to verify the composed configuration, then restart DSH or let its hot reload apply the patch. The tools are exposed to the model as mcp__dbx__<tool>. Keep serverName: dbx stable so tool names and permission rules remain stable. Connection access and execution mode continue to be managed in DBX Settings → MCP.

Tools

DBX MCP provides the following tools (availability depends on build features and access settings):

dbx_execute_query row controls:

• max_rows: 1–1000, defaults to 100. Out-of-range values are clamped, not rejected. It applies to SQL connections only — MongoDB shell commands always return at most 100 rows, and multi-statement scripts routed to the batch executor return at most 100 rows per statement.

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

Plugin tools

DBX plugins whose sidecar implements the mcp/tools bridge can be served by the dbx MCP server and merged into tools/list — no per-plugin --mcp process configuration in your client. Exposure is author opt-in: a plugin's tools appear only when its manifest declares an mcp contribution with external_tools: true (SSH, Files, Kafka, LDAP, ... any plugin can do it):

• Tools are exposed as dbx_<prefix>__<tool>, with the prefix derived from the plugin id's last segment: io.dbx.ssh → dbx_ssh__sftp_list_dir, io.dbx.kafka → dbx_kafka__kafka_topics_list.
• Connections stay host-bound: the plugin schema's connectionId / connectionName are removed and replaced by an optional dbx_connection argument that selects among the plugin's saved connections allowed by the DBX MCP settings. With exactly one allowed connection you can omit it. The host generates the lifecycle payload (credentials, runtime endpoint) from the saved connection — credentials never reach the model or client.
• Scoped sessions (DBX_MCP_SCOPE_*), the global tool allowlist, and the connection allowlist constrain plugin tools exactly like the dbx_* tools.
• The tool allowlist matches exact names: after enabling plugin tools, add each dbx_<prefix>__<tool> you want exposed (or clear the allowlist to allow everything).
• The Web / Docker backend does not serve plugin tools.

Lazy discovery (DBX_MCP_PLUGIN_TOOLS)

With many plugins, one flat tools/list spends a lot of context on argument schemas. Set DBX_MCP_PLUGIN_TOOLS=lazy to expose only three meta tools — dbx_plugin_list (filterable plugin catalog), dbx_plugin_tools (one plugin's tools and schemas), and dbx_plugin_call (call by plugin id + tool) — so schemas enter the context on demand. both advertises the flat tools and the meta tools at once. The default stays flat.

Resources

Clients that support MCP Resources can read the connection catalog and expand templates for database metadata:

Resource discovery and reads reuse the corresponding Tool allowlist plus connection, group, database, and runtime scopes. Query parameter values must be URI encoded. SQL execution and all write-capable operations remain Tools.

Read Kafka Messages

dbx_peek_messages is available in builds with mq-admin, in both local and Web modes. Select a saved Kafka connection by connection_id or connection_name and provide topic. It respects MCP connection scopes and tool allowlists and works with read-only and production connections without committing consumer offsets.

{
  "connection_name": "Kafka",
  "topic": "events",
  "count": 20,
  "start_position": "offset",
  "partition": 0,
  "offset": 120
}

• count: 1–100, defaults to 20.
• start_position: latest (default), earliest, or offset. Supply a non-negative offset only with offset mode.
• partition: optional non-negative partition number. If omitted, reads across topic partitions; in offset mode, the offset applies to every partition.
• The JSON response contains messages with base64 payloads, lossless UTF-8 previews when available, message IDs and metadata. incomplete means the broker read reached a deadline or scan limit. outputTruncated means whole messages were omitted to fit the 256 KiB message output budget. A single oversized message may therefore yield no messages with outputTruncated: true; payloads are never silently clipped.

This is a bounded snapshot, not a continuous consumer or a topic-wide text search. Other message queue types are rejected.

Batch SQL Execution

dbx_execute_batch runs a SQL script containing multiple statements in a single call. In auto-commit mode (the default) it returns one result per statement, so callers see exactly which statement failed, how many rows each affected, and what each returned. With use_transaction and a script containing multiple statements it returns a single merged transaction outcome instead.

• The script text is split with a database-dialect-aware parser, so semicolons inside string literals, comments, and stored procedures do not break the batch.
• By default the batch stops at the first failing statement. Pass continue_on_error to keep going after a per-statement error (connection-level failures always stop the batch).
• Pass use_transaction to run all statements inside one BEGIN … COMMIT so the whole batch either succeeds or rolls back; this requires a script with more than one statement (a single-statement script ignores the option and runs as normal auto-commit). In transaction mode the call returns a single merged result (not one result per statement), and use_transaction cannot be combined with session_id (a transactional batch runs on a pooled connection and would discard the session's state) or with continue_on_error (a transactional batch stops and rolls back at the first failure). DBX rejects the option when the active backend cannot provide a rollbackable transaction. MySQL-family connections reject use_transaction for DDL scripts because MySQL DDL implicitly commits and cannot be rolled back.
• SQL policy (read-only, dangerous-SQL, production protection, database switching) is rechecked against the whole script as a unit before anything runs, exactly as dbx_execute_query does. A single write or DDL statement in the batch fails the whole call under a read-only policy.
• Each batch gets a dedicated connection for its full lifetime, so temporary tables and SET state are preserved between its statements. To preserve that state across multiple MCP calls, open a session with dbx_open_session and pass its session_id.
• dbx_execute_batch is not available for Redis or MongoDB connections.

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 or dbx_execute_batch 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 by default, and the server allows at most 32 concurrent sessions. Set DBX_SESSION_IDLE_TTL_SECS=43200 in the process hosting MCP to allow 12 hours of inactivity, including transaction-owned connections. The value must be positive whole seconds; unset, invalid, zero, negative or unrepresentable values keep the 1800-second default. Restart the host after changing it. For embedded DBX Web MCP, set it on the Web server; for the standalone launcher, set it in the launcher environment.

Explicit native MySQL transactions

Set enable_transactions: true when calling dbx_open_session to reserve one physical native MySQL connection eagerly. Then use dbx_begin_transaction, one or more dbx_execute_query or dbx_execute_batch calls with the returned session_id, and finally dbx_commit_transaction or dbx_rollback_transaction. Queries before and after a transaction still use the same owned connection. use_transaction remains incompatible with session_id; it is the separate atomic-batch feature described above.

This opt-in mode is available only for local native MySQL connections. DBX Web/DBX_WEB_URL, external driver profiles, compatibility engines, and other database types return TRANSACTION_UNSUPPORTED instead of falling back to auto-commit. Transaction-session SQL accepts one parsed SELECT (including locking reads), INSERT, UPDATE, DELETE, or REPLACE statement per operation. It rejects raw transaction control, DDL and temporary DDL, CALL, LOAD, table locks, SET, USE, XA, file/output clauses, executable comments, optimizer hints, and multi-statements. Complete batches hold one operation slot and report the resulting transaction state for every statement.

Responses include transaction_state (idle, active, or unknown) and, when known, transaction_outcome (committed, rolled_back, or unknown). A normal MySQL statement error can leave the transaction active; DBX probes fresh state on the same connection before reporting it. A timeout, cancellation, transport failure, or lost COMMIT acknowledgement makes the outcome unknown, permanently blocks more SQL on that session, and disposes the connection without replaying the statement or COMMIT. A positive connection query timeout applies to transaction operations; when the connection is configured as unlimited (0), transaction owners still apply their default 300-second operation cap so busy work remains bounded. Closing, expiry, protocol-session deletion, and server shutdown attempt bounded rollback for a known active transaction and then dispose the connection.

Salesforce SOQL and DML

Salesforce connections speak SOQL, not SQL, and DBX shapes the MCP surface around that:

• dbx_list_tables lists the org's objects, dbx_describe_table lists an object's fields, and dbx_execute_query runs SOQL (SELECT Id, Name FROM Account LIMIT 10).
• dbx_list_databases explains that one Salesforce org is one scope instead of inventing databases.
• dbx_execute_batch and dbx_open_session are refused: SOQL is read-only so there is no multi-statement script to batch, and every call is a stateless REST request — there is no session to pin and no transaction to open.
• A record write is never a query. dbx_execute_query rejects write attempts with SALESFORCE_DML_REQUIRES_CONFIRMATION so the confirmation below cannot be bypassed.

Confirming a write

Writing goes through two calls, and the second one only works if a human saw the first one's summary:

1. dbx_salesforce_prepare_write with connection_id (or connection_name), op (insert, update, or delete), object (an API name such as Account or Invoice__c), the record id for update/delete, and fields for insert/update. Nothing is sent to Salesforce.
2. Show the returned summary to the user: the operation, object, record Id, every field value, the connection, and the identity the change will be attributed to.
3. dbx_salesforce_apply_write with the confirm_token from step 1.

The token is single-use, expires 5 minutes after it was issued, and is bound to that exact statement — a changed write needs a new prepare. A replayed, expired, or never-issued token fails with CONFIRM_TOKEN_INVALID. DBX re-checks the connection scope, tool allowlist, read-only and production protections, and the DML opt-in at apply time, so revoking permission between the two calls takes effect immediately.

Who the write is attributed to

dbx_salesforce_current_user returns the connected user, their profile, the org display name, and whether that profile holds Modify All Data — the flag that decides whether field-level security and record sharing apply at all. Call it before preparing a write, and use it to tell a permission failure apart from a bad record Id. dbx_salesforce_prepare_write includes the same identity in its summary; if the lookup fails the summary says the identity is unknown and still prepares the write, leaving the decision with the user.

Database Access

Native Streamable HTTP for DBX Desktop

Desktop can optionally host its own Streamable HTTP MCP endpoint. It is off by default and, when enabled in Settings → MCP → HTTP Service, listens only on 127.0.0.1:5225/mcp by default. The Desktop process manages the listener, creates a local bearer token, shows a copyable client configuration, and restarts the managed HTTP service if it exits unexpectedly.

To connect a local MCP client:

1. Open Settings → MCP → HTTP Service, turn on Streamable HTTP Service, and keep the default loopback address unless another device genuinely needs access.
2. Click Save and apply. The button saves the configuration and starts, restarts, or stops the service according to the toggle; changing the address, port, or path restarts the service automatically.
3. Copy the displayed service address and bearer token into the MCP client.

Use the generated values in an HTTP-capable MCP client. The transport-specific field names differ between clients, but the essential configuration is:

{
  "type": "http",
  "url": "http://127.0.0.1:5225/mcp",
  "headers": {
    "Authorization": "Bearer <token shown by DBX Desktop>"
  }
}

Keep the default loopback binding for local clients. Binding to a LAN address requires turning on Allow remote access and setting the exact allowed Host authorities; browser clients also need their exact Origin values. Use host:port in an allowed Host when the client sends a non-default port. Rotating the token immediately invalidates the previous credential.

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.

Native Streamable HTTP for DBX Web

DBX Web can also host MCP itself on its existing listener at /mcp, so Docker and reverse-proxy deployments do not need a second exposed port. A single-instance deployment with a Web login password can enable it in Settings → MCP → HTTP Service after entering the allowed Hosts. DBX generates a bearer token in its encrypted secret store; the page can copy, rotate, or disable it, with changes applying to new requests immediately. The page does not show /mcp as a usable endpoint while it is disabled. Page-managed MCP is inactive without a Web login password; demo deployments disable MCP entirely.

Deployment configuration takes precedence: when DBX_WEB_MCP_TOKEN or DBX_WEB_MCP_TOKEN_FILE is set, the page shows read-only status and cannot replace the deployment secret. A previously enabled page-managed token remains stored and becomes active again if the deployment token is removed and Web is restarted. Configure DBX_WEB_MCP_ALLOWED_HOSTS with the public authorities clients send in the Host header, including mapped ports. Multi-instance deployments should use a shared deployment secret and allowlist, not the page-managed mode. Use DBX_WEB_MCP_TOKEN_FILE or your deployment secret manager instead of committing a real token to a Compose file.

For example, a container published as 4225:4224 uses http://localhost:4225/mcp:

environment:
  DBX_WEB_MCP_TOKEN: replace-with-a-long-random-secret
  DBX_WEB_MCP_ALLOWED_HOSTS: localhost:4225
ports:
  - "4225:4224"

Clients must supply Authorization: Bearer <DBX_WEB_MCP_TOKEN>. Browser-based clients additionally require DBX_WEB_MCP_ALLOWED_ORIGINS with their exact origin, such as https://mcp.example.com; native clients normally do not send an Origin header. When a reverse proxy adds a public path prefix, set DBX_PUBLIC_BASE_PATH=/dbx; the native endpoint then becomes /dbx/mcp. Native HTTP and the existing DBX_WEB_URL stdio adapter can coexist: they share DBX connections and MCP policy, while the adapter remains useful for clients that support only stdio.

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.

For connections exposed to MCP, Settings → MCP can set a default execution permission: inherit the global mode, read only, safe write, or high-risk write. When selected databases are used, individual databases can receive their own execution permission. Execution permissions fall back from the most specific scope: database setting → connection default → global default. For example, a database can use full access while both the global and connection defaults use data read/write. Connection-level read-only protection, production protection, database scope, and database credentials remain independent hard limits that no database setting can bypass.

The same page can also expose only selected MCP tools. This is enforced at every call, rather than being only a client-side display preference; a client that retained an old tool list is denied once the server-side allowlist changes.

Configure access in order

Use Settings → MCP to define the effective scope in this order:

1. Choose whether MCP can see all connections (including future connections) or only specified connections.
2. For every exposed connection, choose all databases, specified databases, or no access. Specified database names are exact matches; use dbx_list_databases to discover the names that are currently allowed, then optionally set execution permissions for those databases.
3. Set each connection's default execution permission. It applies to every database when all databases are exposed, and to selected databases that do not have an override.
4. Select only the MCP tools that the client needs, then choose the global default execution permission.

The most specific execution setting wins, but an allowed tool still cannot bypass a hidden connection, database scope, connection read-only status, production protection, or the database account's own privileges. Requests for a database outside the selected scope are rejected with DATABASE_OUT_OF_SCOPE. When database-specific execution permissions exist, cross-database SQL and MongoDB aggregation writes are rejected to prevent bypassing those limits.

During upgrade, saved connection rules without an execution policy version keep the previous ceiling semantics and cannot widen the global permission. Only a rule saved by the current Settings UI is marked for scoped override semantics; editing an existing legacy rule first carries its effective ceiling forward before enabling the new behavior.

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