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 | shOn Windows, run in PowerShell:
irm https://dbxio.com/install-mcp.ps1 | iexThe 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.
On macOS, the shell installer also verifies the official Developer ID signature and stable com.dbx.app.mcp designated requirement before replacing the binary. Unsigned, ad-hoc, unexpected-signer or hash-bound artifacts are rejected, leaving the installed binary and version marker unchanged. This check applies to the shell installer; Homebrew and npm retain their own installation flows.
Homebrew is also available on macOS and Linux:
brew install t8y2/tap/dbx-mcp
brew upgrade t8y2/tap/dbx-mcpFor 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
Install the MCP Server
npm install -g @dbx-app/mcp-servernpm automatically installs the package for your current platform. Do not use --no-optional.
Configure Your AI Agent
Create .mcp.json in your project directory:
{
"mcpServers": {
"dbx": {
"command": "npx",
"args": ["-y", "@dbx-app/mcp-server"]
}
}
}If you installed the package globally, you can use "command": "dbx-mcp-server". Manage the connection allowlist and execution mode centrally in DBX Settings → MCP; normal client configs do not need permission variables. For Windows portable DBX, set DBX_DATA_DIR to the data directory next to DBX.exe.
Start Using
Ask your AI assistant in natural language:
- "List my database connections"
- "Show the tables on local-pg"
- "Describe the users table"
- "Count the orders from the last 7 days"
- "Open the orders table" (requires DBX to be running)
Supported AI Agents
| Agent | Configuration |
|---|---|
| Claude Code | .mcp.json |
| Cursor | .cursor/mcp.json |
| Windsurf | MCP configuration |
| VS Code + Copilot | MCP extension/configuration |
| DeepSeek Harness | $DSH_HOME/profiles/<profile>/cordis.patch.yml |
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-serverKeep 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):
| Tool | Description |
|---|---|
dbx_list_connections | List connections visible to the MCP session, including saved notes |
dbx_list_databases | List databases available through a connection, respecting its MCP database scope |
dbx_add_connection | Add a connection to DBX storage |
dbx_duplicate_connection | Duplicate a DBX connection with its complete settings |
dbx_remove_connection | Remove a connection from DBX storage |
dbx_list_tables | List tables, views, or collections |
dbx_describe_table | Return columns and table metadata |
dbx_list_routines | List stored procedures and functions in a schema, with an optional routine_type filter (PROCEDURE or FUNCTION) |
dbx_get_routine_source | Return the source of a stored procedure or function by name, with an optional signature for overloaded names |
dbx_get_schema_context | Return compact schema context for an AI model |
dbx_execute_query | Execute SQL or a supported MongoDB shell command, returning 100 rows by default (up to 1000 with the max_rows parameter) |
dbx_execute_batch | Execute a SQL script containing multiple statements in one call, returning a result per statement (or a single merged result with use_transaction on a multi-statement script) |
dbx_open_session | Open a stateful SQL query session pinned to one backend connection |
dbx_begin_transaction | Begin a transaction on a transaction-enabled native MySQL session |
dbx_commit_transaction | Commit the active session transaction after MySQL acknowledges COMMIT |
dbx_rollback_transaction | Roll back the active session transaction |
dbx_close_session | Close a session and release its pinned connection resources |
dbx_execute_redis_command | Execute a Redis command |
dbx_salesforce_current_user | Show the Salesforce user and org behind a connection, including whether the profile holds "Modify All Data" |
dbx_salesforce_prepare_write | Prepare one Salesforce record write and return a summary plus a single-use confirm token |
dbx_salesforce_apply_write | Apply a prepared Salesforce write using its confirm token |
dbx_peek_messages | Read Kafka messages without committing consumer offsets |
dbx_send_message | Send a message to a supported message queue topic or queue |
dbx_open_table | Open a table in the running DBX desktop app |
dbx_execute_and_show | Execute a query and display the result in DBX |
Nacos and Consul tool levels
Nacos and Consul expose product-specific toolsets. The client tool list is filtered by connection-type coverage, enabled tools, and permissions. Each call still rechecks visibility and effective permissions for the target connection and sub-scope; a listed tool is not authorized for every target.
| Tool | Level | Description |
|---|---|---|
dbx_nacos_list_namespaces | Read | List the Nacos namespaces visible for the connection |
dbx_nacos_list_configs | Read | List configurations in a namespace, with dataId, group, text, and paging filters |
dbx_nacos_get_config | Read | Read configuration content and metadata |
dbx_nacos_config_history | Read | Read the publish history of a configuration |
dbx_nacos_publish_config | Write | Create or overwrite one configuration, with an optional CAS MD5 |
dbx_nacos_delete_config | Full | Delete one configuration |
dbx_nacos_list_services | Read | List services in a namespace |
dbx_nacos_list_instances | Read | Read instance health, weight, and enabled state |
dbx_nacos_update_instance | Write | Change an instance's online state or weight |
dbx_nacos_search_configs | Read | Search configuration content in one or all allowed namespaces |
dbx_nacos_rollback_config | Write | Restore one configuration from its publish history |
dbx_nacos_get_service | Read | Read service details |
dbx_nacos_register_instance | Write | Register one service instance |
dbx_nacos_deregister_instance | Full | Deregister one service instance |
dbx_consul_kv_list | Read | List Consul KV keys by prefix, one page at a time |
dbx_consul_kv_get | Read | Read one KV and its ModifyIndex |
dbx_consul_kv_put | Write | Write one KV, with optional CAS protection |
dbx_consul_kv_delete | Full | Delete one KV |
dbx_consul_list_services | Read | List services and tags in the Consul catalog |
dbx_consul_list_nodes | Read | List catalog nodes |
dbx_consul_service_health | Read | Read service instances and health checks |
dbx_consul_set_maintenance | Write | Put a Consul Agent service into or out of maintenance mode |
Nacos uses namespace as its sub-scope. In the access-control tree under Permission management, expand a Nacos connection and choose all namespaces, selected namespaces, or no namespaces. dbx_nacos_list_namespaces also returns only namespaces that are visible to MCP. A Consul connection is already bound to one datacenter, so the tree does not split datacenters and currently has no KV-prefix sub-scope.
The public Nacos namespace uses public in permission rules; an omitted or empty namespace resolves to the same public scope when the connection default is empty.
Nacos user, role, and namespace administration, and Consul ACL and Intentions administration, are not exposed by default. Snapshot restore, Raft or cluster-member changes, License writes, and other cluster operations whose risk cannot be reliably classified are not provided as MCP tools.
dbx_list_connections and dbx://connections include saved connection notes regardless of the sidebar display setting. Notes are visible to MCP clients that can access the connection; do not store passwords or other secrets in notes.
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/connectionNameare removed and replaced by an optionaldbx_connectionargument 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 thedbx_*tools. - The tool allowlist supports exact names and plugin wildcards:
dbx_<prefix>__<tool>allows one tool,dbx_<prefix>__*one plugin, anddbx_*__*every plugin. - 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. Without the environment variable, new configurations list tools directly and saved modes remain unchanged. Automatic (compatibility) preserves the existing threshold: list directly with up to 40 plugin tools in total, otherwise use on-demand discovery.
Resources
Clients that support MCP Resources can read the connection catalog and expand templates for database metadata:
| Resource URI | Description |
|---|---|
dbx://connections | Connections visible to the current MCP scope |
dbx://connections/{connection_id}/databases | Databases visible through one connection |
dbx://connections/{connection_id}/tables{?database,schema} | Tables and views in an optional database/schema |
dbx://connections/{connection_id}/table-schema{?database,schema,table} | Column definitions for a table; table is required |
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, oroffset. Supply a non-negativeoffsetonly withoffsetmode.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
messageswith base64 payloads, lossless UTF-8 previews when available, message IDs and metadata.incompletemeans the broker read reached a deadline or scan limit.outputTruncatedmeans whole messages were omitted to fit the 256 KiB message output budget. A single oversized message may therefore yield no messages withoutputTruncated: 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_errorto keep going after a per-statement error (connection-level failures always stop the batch). - Pass
use_transactionto run all statements inside oneBEGIN … COMMITso 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), anduse_transactioncannot be combined withsession_id(a transactional batch runs on a pooled connection and would discard the session's state) or withcontinue_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 rejectuse_transactionfor 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_querydoes. 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
SETstate are preserved between its statements. To preserve that state across multiple MCP calls, open a session withdbx_open_sessionand pass itssession_id. dbx_execute_batchis 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:
USEor 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.
USE is meaningful only inside a session, while writes, DDL, production protection, connection read-only state, and database privileges are rechecked for every request.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, and server shutdown attempt bounded rollback for a known active transaction and then dispose the connection. Sessions are reclaimed by dbx_close_session, by the idle timeout, or by MCP server shutdown. The HTTP transport keeps no session of its own, so there is no transport session for DELETE to end or for an idle client to lose; the session_id handle is the only thing that carries state.
Salesforce SOQL and DML
Salesforce connections speak SOQL, not SQL, and DBX shapes the MCP surface around that:
dbx_list_tableslists the org's objects,dbx_describe_tablelists an object's fields, anddbx_execute_queryruns SOQL (SELECT Id, Name FROM Account LIMIT 10).dbx_list_databasesexplains that one Salesforce org is one scope instead of inventing databases.dbx_execute_batchanddbx_open_sessionare 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_queryrejects write attempts withSALESFORCE_DML_REQUIRES_CONFIRMATIONso 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:
dbx_salesforce_prepare_writewithconnection_id(orconnection_name),op(insert,update, ordelete),object(an API name such asAccountorInvoice__c), the recordidforupdate/delete, andfieldsforinsert/update. Nothing is sent to Salesforce.- 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.
dbx_salesforce_apply_writewith theconfirm_tokenfrom 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.
dbx_salesforce_apply_write returns, the record has changed in the org and DBX cannot roll it back. Each call touches exactly one record: upsert, bulk, and composite writes are rejected at prepare time with SALESFORCE_DML_INVALID. Preparing a write needs the per-connection Allow DML switch in Settings → MCP, which is off by default and returns SALESFORCE_DML_DISABLED until a person turns it on; a read-only execution mode ignores the switch entirely.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:
- Open Settings → MCP → HTTP Service, turn on Streamable HTTP Service, and keep the default loopback address unless another device genuinely needs access.
- 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.
- 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.
DBX answers both MCP protocol generations on the same endpoint, so any agent can connect without a version-specific setup:
| Agent | Handshake | Transport state |
|---|---|---|
| Older clients | initialize (protocol 2025-11-25 and earlier) | Stateless: the response carries no Mcp-Session-Id, and every request is served on its own |
| Modern clients | server/discover (protocol 2026-07-28) | Stateless: every request carries its own protocol version and capabilities in _meta |
Both generations are served statelessly, so the endpoint accepts POST only: GET and DELETE return 405 Method Not Allowed. Nothing in DBX depends on an HTTP-level session, which is why a client that reconnects after any idle period simply works instead of running into a session the server already dropped.
Stateful DBX sessions still work in both cases, because they are explicit handles: dbx_open_session returns a session_id that the agent passes back as an ordinary tool argument on later calls. That handle is independent of the transport, has its own idle TTL, and is what keeps a pinned connection, USE/SET state, temporary tables, or an open transaction alive across requests.
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:
| Platform | Default database file |
|---|---|
| macOS | ~/Library/Application Support/com.dbx.app/dbx.db |
| Linux | ~/.local/share/com.dbx.app/dbx.db |
| Windows | %APPDATA%\com.dbx.app\dbx.db |
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:
| Permission mode | Allowed operations |
|---|---|
| Read only | Queries and metadata reads |
| Data read/write | Regular inserts, effectively filtered updates/deletes, scoped MongoDB mutations, and ordinary Redis writes |
| Full access | Also permits broad updates/deletes, DDL, TRUNCATE, MongoDB destructive operations, and Redis FLUSH* |
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.
MCP settings tabs
The MCP settings page uses the three labels shown in the UI: Access methods, Capabilities, and Permission management. They share one policy, so changes apply to every MCP client.
Access methods
Access methods handles MCP Server installation, upgrades and removal, generates stdio/HTTP client configurations, and exposes runtime settings. Query timeout remains here; External plugin tool delivery is under Capabilities → Advanced settings. Generated client configurations contain only the runtime information needed to start MCP Server; they do not contain permission or connection-scope variables.
Capabilities
The Capabilities tab defaults to Category management: choose Database, Nacos, Consul, Message queues, Salesforce, or DBX General on the left and configure its toolsets on the right. Global overview displays all categories together. Plugins have separate entries marked with their source. Search covers categories, toolsets, tool names/IDs and plugins; Only show enabled filters by configuration without changing the selected category. Category batch actions include tools hidden by filters and take effect after Apply. Shared connection discovery belongs to DBX General, so disabling Database does not disable discovery for other products.
Each toolset shows enabled counts, Read / Write / High risk badges and connection coverage by type. Badges describe tool risk and do not grant access. Toolsets without matching connections remain configurable. Built-in changes use Apply / Cancel; plugin grants save immediately. Custom tool allowlists are under Advanced configuration.
Open a card to inspect its tools. Tool details include the tool ID, model-facing description, access level, supported database types, and every parameter's name, type, required flag, description, and default. Classified tools say that each call is classified as read, write, or high risk from its statement. A switch in the detail view can disable one built-in tool. Apply this toolset saves only the switches in the current toolset and keeps the dialog open. Unsaved changes to other toolsets, permissions, and runtime settings remain drafts. Closing the detail also keeps its draft for Apply or Discard in Settings; discarding other drafts does not undo a toolset already applied from its details. Save failures appear inside the dialog and can be retried.
Plugin cards show the plugin name, version, plugin ID, level badges, and the MCP tools mark. They show whether the author opened external MCP, the external MCP switch, an authorization ceiling (read only / read & write / full), and the exposed count. The first time you enable a plugin, an authorization dialog appears; only tools and levels declared in the manifest are accepted. New read-only tools can become available automatically. New write or full tools, and existing tools whose declared level rises, require confirmation even when they are within the existing ceiling. Tools above the ceiling remain hidden; raising the ceiling does not replace confirmation of new tools. Plugin details group tools by toolset, show parameters and declared levels, and allow a single tool to be switched off. A tool with no manifest access declaration is never exposed, even when the sidecar marks it read-only.
Plugin tool entries add another layer to the global MCP tool allowlist: dbx_<prefix>__<tool> allows one exact tool, dbx_<prefix>__* allows every tool from one plugin, and dbx_*__* allows every plugin tool. When an explicit allowlist is active, plugin tools without a matching entry stay hidden. Selecting all tools requires no individual entries. The plugin switch, ceiling, and per-tool switch always apply.
Expand External plugin tool delivery under Capabilities → Advanced settings to choose how DBX provides authorized plugin tools to MCP clients. Click Apply at the bottom to save. New configurations default to List directly (flat), which lists each authorized tool in tools/list. Lazy discovery (lazy) provides the shared dbx_plugin_list, dbx_plugin_tools, and dbx_plugin_call entry points; enable Plugin discovery and invocation under DBX general. Both paths enforce the same plugin grants and resource permissions. Saved modes remain unchanged, and legacy saved policies without this field retain their previous automatic behavior. Automatic (compatibility) lists directly with up to 40 plugin tools in total and uses on-demand discovery above that. The DBX_MCP_PLUGIN_TOOLS environment variable takes priority over the page setting and accepts flat, lazy, or both; both advertises both the flat tools and the discovery tools.
Permission management
Permission management provides Global default permission, Access control, and independent Call safety. There are no quick presets or Custom mode. Permission changes do not change tool switches in Capabilities.
Global default permission applies to resources without a more specific permission. Choose read only, data read/write, or full access. Changing the default updates the effective preview for resources that inherit it; groups, connections, and databases with their own permissions keep those settings. The comparison table is collapsed under Permission details. It describes permission levels; tools must also be enabled in Capabilities.
Call safety is independent of permission inheritance and tool switches. Changing the global default does not alter the confirmation policy. Granting full access to a default, group, connection or database still asks for confirmation of that settings change; cancelling retains the previous value. This is separate from confirming a tool invocation.
The global default and group, connection, and database permissions are staged until you click Apply. Switching tabs keeps the draft; closing and discarding changes restores the saved configuration.
The access-control tree puts groups, connections, and sub-scopes in one table. Choose All connections (including future connections) or Selected only, then set group and connection visibility. Each connection shows a database scope summary. Configure database access opens a transfer dialog with All databases, Selected, and No databases modes. Move databases to the right and set each to inherit, read only, data read/write, or full access. Removing a database also removes its override.
When individual connections or child groups are authorized, their ancestor group shows a mixed checkbox and the number of visible connections across the full group, regardless of collapsing or filtering. Even if all current connections are visible, the checkbox stays mixed until the whole group is authorized; future connections are not implicitly included. Clicking the mixed checkbox authorizes the entire group. Group permission defaults apply to child items without their own permission setting and do not change visibility.
Check multiple databases on the right and use Set access for checked to update their permissions together. Unchecked databases are unchanged, and full access requires one confirmation for the batch. Select current search results includes matching databases beyond the currently rendered rows; changing the search clears the checkmarks. Batch changes are saved only when you click Apply database access. Each row's help icon explains the permission source and whether the database was found during discovery.
Discovery loads every database visible to the database account. Both lists support search; refresh and manual entry of exact names are available. Lists over 100 entries render in batches, while search and Select current search results cover the entire list. Selected databases missing from discovery are retained. All databases includes future databases; selecting every currently discovered database does not. Unselected databases and cross-database requests are rejected.
Apply database access saves only this connection’s database scope and individual permissions. Drafts for other connections, parent permissions, tools and runtime settings remain unchanged. Success keeps the dialog open; failures can be retried. Closing retains drafts, and discarding other drafts does not undo database permissions already applied. Pending parent changes are distinguished from currently saved inherited permissions.
Permissions inherit from the most specific scope: database → connection → nearest group → parent group → global default. The Permission column is the row's setting; Effective shows the final level and its source. Search covers groups, connections, and databases, and Only show individual settings hides rows that only inherit their default. Rows saved by an older version are marked legacy and can only narrow the connection's inherited permission; choose a permission again to make the row a regular setting. Salesforce connections also have an Allow DML switch; it is off by default and unavailable at read-only level, while connection and production protections remain hard limits.
Plugin connections can expose a plugin-declared sub-scope (for example, a namespace or directory) in the same tree. Load the values from the plugin and choose all, selected, or none. Nacos connections use the same editor for namespaces; Consul's datacenter is fixed by the connection. Sub-scope changes save immediately, as noted in their editor, and are unaffected by Apply or Cancel at the bottom. A failed save displays an error and keeps the previous configuration.
Call safety
Enable Request human confirmation before high-risk tool calls to check permissions first and reject insufficient access. Authorized high-risk calls also require confirmation at full access. This covers high-risk SQL, dangerous or unbounded MongoDB mutations, dangerous Redis commands, plugin tools declared full, Nacos/Consul deletion and connection removal. Ordinary reads and bounded ordinary writes do not prompt. Enabled tools, plugin grants, resource visibility, read-only connections and production protections remain mandatory.
DBX Desktop shows the tool, target and operation. Each approval is for the current call only, without elevating permissions or granting a timed exemption. Denial, timeout or unavailable desktop confirmation prevents execution. Permissions are rechecked after approval; revocation wins. The policy applies to both stdio and HTTP; Web backends cannot provide desktop confirmation.
Compatibility: Existing promptHighRiskSql=true or v2 confirm="full" remains Legacy temporary authorization: data-write access can confirm supported high-risk calls, while full access does not prompt. SQL's once/hour/day choices remain exclusive to that legacy mode. The UI explains the difference. Only explicitly choosing the new policy or disabling legacy authorization, then clicking Apply, changes the behavior. The new policy uses callConfirmation="high_risk" / v2 confirm="high_risk", never a reinterpretation of the old boolean. Fresh configurations start without additional confirmation and can opt in. Older standalone MCP programs do not understand the new policy; use matching desktop and standalone MCP versions.
MCP call history
The View MCP call history button is on the right of the transport selector row in Access methods, displayed as a history icon in narrow layouts. It closes Settings and opens the history panel on its MCP view. If there are unsaved changes, you must first confirm discarding them; choosing to keep editing leaves the history panel closed. Entries include the time, transport (stdio or HTTP), MCP client name and version, tool, target connection/database or other resource, classified level, whether confirmation was used, duration, request/response summaries, and the success or failure reason. The client name is recorded only for auditing and does not affect authorization. MCP history has its own retention and cleanup settings.
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. DBX_MCP_ALLOW_WRITES=0 (or false) enforces read-only access for the current run, even after the central policy is saved and even when a group, connection, or database grants full access. This restriction applies to both local and Web backends without modifying saved settings. A value of 1, true, or an unset variable still requires authorization from the central policy. Legacy connection-scope variables can only narrow the DBX allowlist.
| Variable | Purpose |
|---|---|
DBX_DATA_DIR | Override the local DBX data directory |
DBX_SESSION_IDLE_TTL_SECS | Stateful session idle timeout in positive whole seconds (default: 1800). Invalid, zero, negative or unrepresentable values use the default. Applies to transaction-owned connections too; restart the MCP host after changing it. |
DBX_MCP_PLUGIN_TOOLS | Override External plugin tool delivery in Advanced settings with flat, lazy, or both; the environment variable takes priority. |
DBX_WEB_URL | Use a DBX Web/Docker backend |
DBX_WEB_PASSWORD | Authenticate to DBX Web |
HTTP_PROXY / HTTPS_PROXY / ALL_PROXY | Standard system proxy variables for DBX Web requests; empty value means no proxy. Auth via http://user:pass@host:port |
NO_PROXY | Standard bypass list for the proxy above (comma-separated hosts) |
DBX_WEB_HEADERS | JSON object of extra HTTP headers for DBX Web requests, e.g. {"Authorization":"Bearer token"} |
DBX_WEB_INSECURE_SKIP_VERIFY | 1/true disables TLS certificate verification for self-signed DBX Web backends (default: verify) |
DBX_WEB_CA_CERT | PEM/DER CA file to trust for DBX Web TLS verification |
DBX_WEB_MCP_TOKEN | Enable native Web Streamable HTTP MCP with this bearer token |
DBX_WEB_MCP_TOKEN_FILE | Read the native Web MCP token from a file; cannot be combined with DBX_WEB_MCP_TOKEN |
DBX_WEB_MCP_ALLOWED_HOSTS | Required comma-separated public Host authorities for native Web MCP |
DBX_WEB_MCP_ALLOWED_ORIGINS | Comma-separated browser Origins allowed for native Web MCP |
DBX_MCP_ALLOW_WRITES | 0/false forces the current run to be read-only, including saved group, connection, and database overrides; 1/true never widens the central policy. Applies to local and Web backends. |
DBX_MCP_SCOPE_CONNECTION_ID | Compatibility scope for one connection ID |
DBX_MCP_SCOPE_CONNECTION_IDS | Compatibility scope for multiple connection IDs |
DBX_MCP_SCOPE_CONNECTION_NAME | Restrict the session to one connection name |
DBX_MCP_SCOPE_DATABASE | Restrict the session to one database |
DBX_MCP_DEBUG_SQL | Include SQL in temporary diagnostics |
Troubleshooting
Credential access after an upgrade
Standalone macOS MCP runs without Keychain dialogs. If the existing encryption key is locked or denied, startup fails with KEYRING_ACCESS_FAILED (possibly inside SECRET_KEY_UNAVAILABLE) instead of repeatedly asking for a password. Unlock your login keychain first. For an older hash-bound authorization, run the same official executable used by your MCP client once in a terminal:
"$HOME/.dbx/bin/dbx-mcp" --authorize-keychainReplace that path for a Homebrew or npm installation. The command verifies the running program's official signature and stable designated requirement before reading the existing DBX Keychain item. It does not open the database, start an MCP transport, create or replace a key, export key material, or rewrite an ACL itself. macOS may ask for confirmation once; choose Always Allow (not Allow) for the verified DBX executable. The command then re-reads the key from a fresh non-interactive process and fails with KEYRING_ACCESS_FAILED if the authorization was not retained, so a success message means background launches will work. Restart your MCP client afterwards. An already-authorized executable should not prompt. Stable signing keeps that authorization valid across normal signed upgrades, not across a changed signing team or a revoked permission.
Do not put --authorize-keychain in your MCP client's arguments: it is a one-time recovery command and exits immediately. Missing keys still require the Desktop data-security setup; this command cannot recreate a lost key. Windows and Linux do not use this macOS command. On those platforms, restore access to the credential store for the same OS user (or the configured headless key file) and restart MCP; denied or corrupt providers must not cause a replacement encryption key to be generated.
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