# MCP 集成 > 通过 Model Context Protocol 让 AI 编程助手在 DBX 权限策略内读取元数据、查询数据和使用有状态会话。 Source: https://dbxio.com/cn/docs/mcp Language: zh-CN Relative links resolve against https://dbxio.com/cn/docs/mcp. 把 AI 助手连接到 DBX，即可查看数据库结构、查询数据，并在 DBX 中打开结果。 ## 什么是 MCP？ MCP（Model Context Protocol）是让 AI 客户端调用外部工具的开放协议。DBX MCP 可以让 AI 助手使用 DBX 中已经配置好的数据库连接。 ```text AI 助手 → DBX MCP → 你的数据库 → 返回结果 ↘ DBX 桌面端（打开或展示结果） ``` ## 原生安装（推荐） 无需 Node.js。macOS 或 Linux 执行： ```bash curl -fsSL https://dbxio.com/install-mcp | sh ``` Windows 在 PowerShell 中执行： ```powershell irm https://dbxio.com/install-mcp.ps1 | iex ``` 脚本校验下载内容，将 `dbx-mcp` 安装到 `~/.dbx/bin`，并打印 Claude Code、Cursor、Codex、ZCode 和通用 MCP 配置。请使用输出中**展开后的可执行文件绝对路径**，不要填写 `~` 或裸命令 `dbx-mcp`：GUI 客户端不一定继承 shell 的 PATH。已有的 `DBX_DATA_DIR` 等环境配置继续有效。DBX 桌面设置优先使用发现的原生二进制，找不到时保留原有 npm 启动方式。 重跑同一安装命令即可升级；版本相同时提示 `already up to date`。版本优先读取 `dbx-mcp --version`，旧版二进制不支持时回退读取 `~/.dbx/bin/.dbx-mcp-version`。断网时安装失败但不会替换现有二进制。下载源依次为 npmjs、npmmirror、GitHub Releases；内容校验不匹配时立即拒绝安装。 macOS 和 Linux 也可以使用 Homebrew： ```bash brew install t8y2/tap/dbx-mcp brew upgrade t8y2/tap/dbx-mcp ``` Homebrew 安装后，客户端配置使用 `echo "$(brew --prefix)/bin/dbx-mcp"` 输出的绝对路径。此通道只安装 MCP 服务器，不安装独立的 `dbx` CLI。 npm/npx 通道保持兼容。DBX 桌面端现在默认安装独立原生服务，并为已有 npm 用户显示推荐的原生迁移入口。迁移会保留 npm 包作为兜底，也不会自动改写外部客户端文件：请将启动命令替换为页面生成的原生绝对路径，删除 Node/npx 参数并保留 `env`。仍可选择执行 `npm rm -g @dbx-app/mcp-server` 清理旧包。桌面端可以更新和卸载当前的独立原生或 Homebrew 安装；卸载独立原生版本后，保留的 npm 安装会重新成为兜底。 macOS 上，Shell 安装器还会在替换二进制前验证官方 Developer ID 签名及稳定的 `com.dbx.app.mcp` designated requirement。未签名、临时签名、签名身份不符或绑定单次构建哈希的安装包会被拒绝，已安装的程序和版本标记保持不变。此校验针对 Shell 安装器，Homebrew 和 npm 保持各自的安装流程。 ## npm 快速开始 ### 安装 MCP Server ```bash npm install -g @dbx-app/mcp-server ``` npm 会自动安装当前平台需要的依赖。不要使用 `--no-optional`。 ### 配置 AI 助手 在项目目录创建 `.mcp.json`： ```json { "mcpServers": { "dbx": { "command": "npx", "args": ["-y", "@dbx-app/mcp-server"] } } } ``` 如果使用全局安装，可将 `command` 改为 `dbx-mcp-server`。连接 allowlist 和执行权限统一在 **DBX 设置 → MCP** 中管理，常规客户端配置不需要权限环境变量。Windows 便携版请将 `DBX_DATA_DIR` 设置为 `DBX.exe` 同级的 `data` 目录。 ### 开始使用 在 AI 助手中直接使用自然语言： * "列出我的数据库连接" * "查看 local-pg 上有哪些表" * "查看 users 表的结构" * "查询最近 7 天的订单数量" * "打开 orders 表"（需要 DBX 运行中） ## 支持的 AI 助手 | AI 助手 | 配置方式 | | ----------------- | ----------------------------------------------- | | Claude Code | `.mcp.json` | | Cursor | `.cursor/mcp.json` | | Windsurf | MCP 配置 | | VS Code + Copilot | MCP 扩展/配置 | | DeepSeek Harness | `$DSH_HOME/profiles//cordis.patch.yml` | ### DeepSeek Harness DeepSeek Harness 通过 Cordis 插件条目加载 MCP Server，不读取 `mcpServers` JSON。安装 `@dbx-app/mcp-server` 后，为 `web` profile 将以下条目合并到 `$DSH_HOME/profiles/web/cordis.patch.yml`：未设置 `DSH_HOME` 时默认为 `~/.dsh`。 ```yaml - insert: - id: mcp-dbx name: '@deepseek-ai/dsh-mcp-client' config: serverName: dbx transport: stdio command: dbx-mcp-server ``` 保留最外层的 `- insert:`，不要覆盖文件中已有的 patch 条目。使用其他 DSH profile 时，将路径中的 `web` 替换为对应 profile 名称。DSH 进程的 `PATH` 必须能找到 `dbx-mcp-server`；必要时请改用可执行文件的绝对路径。 运行 `dsh web --dump-config` 检查组合后的配置，再重启 DSH 或等待热加载应用该 patch。模型侧工具名为 `mcp__dbx__`。请保持 `serverName: dbx` 稳定，避免工具名和权限规则发生变化。连接访问范围和执行模式仍统一在 **DBX 设置 → MCP** 中管理。 ## 工具列表 DBX MCP 当前提供以下工具（具体可用工具取决于构建功能及权限设置）： | 工具 | 说明 | | ------------------------------ | -------------------------------------------------------------------- | | `dbx_list_connections` | 列出当前 MCP 会话可见的连接 | | `dbx_list_databases` | 列出连接中可通过 MCP 访问的数据库，并遵守该连接的数据库范围 | | `dbx_add_connection` | 添加连接到 DBX 存储 | | `dbx_duplicate_connection` | 复制一个连接及其完整配置 | | `dbx_remove_connection` | 从 DBX 存储删除连接 | | `dbx_list_tables` | 列出表、视图或集合 | | `dbx_describe_table` | 返回列定义和表元数据 | | `dbx_list_routines` | 列出 Schema 中的存储过程和函数，支持可选的 `routine_type` 过滤（PROCEDURE 或 FUNCTION） | | `dbx_get_routine_source` | 按名称返回存储过程或函数的源码，重载场景可用可选的 `signature` 区分 | | `dbx_get_schema_context` | 返回适合 AI 使用的紧凑 Schema 上下文 | | `dbx_execute_query` | 执行 SQL 或支持的 MongoDB shell 命令，默认返回 100 行，可用 `max_rows` 参数提高到最多 1000 行 | | `dbx_execute_batch` | 一次执行包含多条语句的 SQL 脚本，按语句返回结果（多语句脚本搭配 `use_transaction` 时返回单个合并结果） | | `dbx_open_session` | 为 SQL 连接打开固定后端连接的有状态查询会话 | | `dbx_begin_transaction` | 在已启用事务的原生 MySQL 会话上开始事务 | | `dbx_commit_transaction` | 在 MySQL 确认 `COMMIT` 后提交当前会话事务 | | `dbx_rollback_transaction` | 回滚当前会话事务 | | `dbx_close_session` | 关闭会话并释放固定连接资源 | | `dbx_execute_redis_command` | 执行 Redis 命令 | | `dbx_salesforce_current_user` | 显示连接背后的 Salesforce 用户与组织，包括简档是否具有 “Modify All Data” | | `dbx_salesforce_prepare_write` | 准备一条 Salesforce 记录写入，返回摘要和一次性确认令牌 | | `dbx_salesforce_apply_write` | 使用确认令牌应用已准备的 Salesforce 写入 | | `dbx_peek_messages` | 读取 Kafka 消息，不提交消费位点 | | `dbx_send_message` | 向支持的消息队列 Topic 或队列发送消息 | | `dbx_open_table` | 在运行中的 DBX 桌面端打开表 | | `dbx_execute_and_show` | 执行查询并在 DBX 中展示结果 | `dbx_execute_query` 返回行数： * `max_rows`：取值 1–1000，默认 100。越界值会被夹取到范围内，而不是报错。仅对 SQL 连接生效——MongoDB shell 命令始终最多返回 100 行，路由到批量执行器的多语句脚本每条语句最多返回 100 行。 启用连接作用域后，修改连接和桌面 UI 工具会被隐藏。 ## 插件工具 实现了 `mcp/tools` 桥接协议的 DBX 插件 sidecar，其工具可由 `dbx` MCP 服务器合并进 `tools/list`，无需在客户端逐个配置插件的 `--mcp` 进程。该机制按作者声明加入：只有 manifest 中声明了 `mcp` 贡献且 `external_tools: true` 的插件（SSH、Files、Kafka、LDAP 等均可）才会暴露工具： * 工具名为 `dbx_<插件前缀>__<工具名>`，前缀取插件 id 的最后一段：`io.dbx.ssh` → `dbx_ssh__sftp_list_dir`，`io.dbx.kafka` → `dbx_kafka__kafka_topics_list`； * 连接由宿主绑定：工具 schema 中的 `connectionId` / `connectionName` 会被移除，改由可选的 `dbx_connection` 参数选择该插件**已保存且被 MCP 设置放行**的连接；只有一个可用连接时省略该参数即可自动绑定；凭据由宿主从保存的连接生成 lifecycle 注入，永不经过模型或客户端； * 作用域会话（`DBX_MCP_SCOPE_*`）与全局 MCP 设置（工具 allowlist、连接 allowlist）同样约束插件工具； * 工具白名单按精确名称匹配：启用插件工具后，请把要暴露的 `dbx_<前缀>__<工具名>` 逐个加入白名单（或清空白名单以全部放行）； * Web / Docker 后端不提供插件工具。 ### 懒发现（`DBX_MCP_PLUGIN_TOOLS`） 插件较多时，平铺的 `tools/list` 会在参数 schema 上消耗大量上下文。设置 `DBX_MCP_PLUGIN_TOOLS=lazy` 只暴露三个元工具——`dbx_plugin_list`（可过滤的插件目录）、`dbx_plugin_tools`（按**插件 id** 查看某插件的工具与 schema）、`dbx_plugin_call`（按插件 id + 工具名调用）——schema 在需要时才进入上下文。`both` 同时平铺与元工具。默认仍为 `flat`。 ## Resources 支持 MCP Resources 的客户端可以读取连接目录，并通过模板获取数据库元数据： | Resource URI | 说明 | | ------------------------------------------------------------------------ | ---------------------- | | `dbx://connections` | 当前 MCP 范围内可见的连接 | | `dbx://connections/{connection_id}/databases` | 指定连接中可见的数据库 | | `dbx://connections/{connection_id}/tables{?database,schema}` | 可选数据库或 Schema 中的表和视图 | | `dbx://connections/{connection_id}/table-schema{?database,schema,table}` | 指定表的字段定义；`table` 为必填参数 | Resource 的发现和读取会复用对应 Tool 的白名单，以及连接、分组、数据库和运行时范围限制。查询参数值必须进行 URI 编码。SQL 执行和所有可写操作仍只通过 Tool 提供。 ## 读取 Kafka 消息 包含 `mq-admin` 的构建在本地和 Web 模式下均提供 `dbx_peek_messages`。通过 `connection_id` 或 `connection_name` 选择已保存的 Kafka 连接，并指定 `topic`。工具遵守 MCP 连接范围及工具白名单，允许读取只读连接和生产连接，不提交消费位点。 ```json { "connection_name": "Kafka", "topic": "events", "count": 20, "start_position": "offset", "partition": 0, "offset": 120 } ``` * `count`：1–100，默认 20。 * `start_position`：`latest`（默认）、`earliest` 或 `offset`。仅 `offset` 模式必须且允许传入非负 `offset`。 * `partition`：可选的非负分区号。不传时跨分区读取；offset 模式下从各分区的该位点开始读取。 * JSON 结果包含 `messages`，保留 base64 消息体、可无损解码时的 UTF-8 预览、消息 ID 和元数据。`incomplete` 表示读取达到超时或扫描上限；`outputTruncated` 表示为满足 256 KiB 消息输出预算而省略了整条消息。如果首条消息过大，可能返回空列表并标记 `outputTruncated: true`，不会静默截断消息体。 该工具读取有限条消息快照，不提供持续订阅或全 Topic 文本搜索。其他消息队列类型会被拒绝。 ## 批量 SQL 执行 `dbx_execute_batch` 在单次调用内执行包含多条语句的 SQL 脚本。默认（自动提交）模式下按语句返回结果，因此调用方可以清楚看到哪条失败、每条影响多少行、各自返回什么；使用 `use_transaction` 且脚本包含多条语句时，只返回一个合并的事务结果。 * 脚本通过方言感知的解析器拆分成独立语句，字符串、注释、存储过程中出现分号也不会破坏批次。 * 默认遇到第一条失败语句即停止；传入 `continue_on_error` 可让批内在单条语句出错后继续执行（连接级错误仍会终止）。 * 传入 `use_transaction` 可把多条语句放入同一个 `BEGIN … COMMIT`，使整批要么全部成功要么回滚；这要求脚本包含多条语句（单语句脚本会忽略该选项，按普通自动提交执行）。此模式下调用只返回一个合并结果（而非逐语句结果），且 `use_transaction` 不能与 `session_id` 同时使用——事务批处理运行在池连接上，会丢弃会话状态；也不能与 `continue_on_error` 同时使用——事务批处理在第一条失败时即回滚并停止。当当前后端无法提供可回滚事务时，DBX 会拒绝该选项。MySQL 系连接对含 DDL 的脚本会拒绝 `use_transaction`，因为 MySQL 的 DDL 会隐式提交、无法回滚。 * SQL 策略（只读、危险 SQL、生产保护、切换数据库）作为整体在匹配前重新检查，与 `dbx_execute_query` 一致；只要批内含一条写入或 DDL，在只读策略下整次调用都会被拒绝。 * 每个批次在其完整执行期间都会使用独占连接，因此临时表和 `SET` 状态可在批内语句之间保留。若要跨多次 MCP 调用保留这些状态，先用 `dbx_open_session` 打开会话，再传入其 `session_id`。 * Redis 和 MongoDB 连接不支持 `dbx_execute_batch`。 ## 有状态查询会话 普通 `dbx_execute_query` 调用彼此独立。需要保持数据库 Session 状态时，先调用 `dbx_open_session`，再把返回的 `sessionId` 传给后续 `dbx_execute_query` 或 `dbx_execute_batch`： * `USE` 或数据库上下文切换 * 临时表 * Session 变量和设置 * 需要固定连接的显式事务或多步诊断 会话只支持 SQL 连接，并固定到一个连接和数据库。未知、已关闭或过期的 `sessionId` 会失败，不会静默退化为普通查询。完成后应调用 `dbx_close_session`；会话默认空闲 30 分钟后回收，同时最多允许 32 个并发会话。在 MCP 宿主进程设置 `DBX_SESSION_IDLE_TTL_SECS=43200` 可将空闲时间延长为 12 小时，事务专属连接也使用此配置。值必须为正整数秒；未设置、非法值、零、负数或无法表示的时长均保留默认 1800 秒。修改后需重启宿主。使用嵌入式 DBX Web MCP 时，在 Web 服务端设置；使用独立启动器时，在启动器环境中设置。 有状态会话不会放宽 SQL 策略。 `USE` 只有在会话中才有意义，但写入、DDL、生产保护、连接只读和数据库权限仍按每次请求重新检查。 ### 原生 MySQL 显式事务 调用 `dbx_open_session` 时传入 `enable_transactions: true`，DBX 会立即保留一条物理原生 MySQL 连接。随后依次调用 `dbx_begin_transaction`、带该 `session_id` 的一个或多个 `dbx_execute_query`/`dbx_execute_batch`，最后调用 `dbx_commit_transaction` 或 `dbx_rollback_transaction`。事务前后的查询仍使用同一条受管连接。`use_transaction` 仍不能与 `session_id` 同时使用；它是前文所述的独立原子批处理功能。 该 opt-in 模式仅支持本地原生 MySQL 连接。DBX Web/`DBX_WEB_URL`、外部驱动 profile、兼容引擎及其他数据库类型会返回 `TRANSACTION_UNSUPPORTED`，不会静默退化为自动提交。事务会话每次操作只接受一条经过解析的 `SELECT`（含锁定读）、`INSERT`、`UPDATE`、`DELETE` 或 `REPLACE`；原始事务控制、DDL/临时 DDL、`CALL`、`LOAD`、表锁、`SET`、`USE`、XA、文件/输出子句、可执行注释、优化器 hint 及多语句均会被拒绝。完整批次持有同一个操作槽位，并为每条语句返回执行后的事务状态。 响应包含 `transaction_state`（`idle`、`active` 或 `unknown`），并在适用时包含 `transaction_outcome`（`committed`、`rolled_back` 或 `unknown`）。普通 MySQL 语句错误可能仍让事务保持 active；DBX 会在同一连接上重新探测服务器状态后再返回。超时、取消、传输故障或丢失 `COMMIT` 确认会把结果永久标为 `unknown`，禁止该会话继续执行 SQL，并在不重放语句或 `COMMIT` 的前提下销毁连接。显式正值的连接查询超时同样用于事务操作；当连接配置为“无限制”（`0`）时，事务 owner 仍使用默认 300 秒操作上限，确保 busy 操作保持有界。关闭、过期、协议会话删除和服务退出会对状态已知的 active 事务执行有界回滚，然后销毁连接。 回滚保证依赖 InnoDB 等事务型存储。触发器、存储函数、非事务表及外部副作用可能产生 MySQL 无法回滚的效果。DBX 会在排队完成后重新检查当前连接/数据库范围、工具 allowlist、只读与生产保护以及已确认 SQL。即使写权限被撤销，仍允许原会话执行回滚和关闭以完成清理。 ## Salesforce SOQL 与 DML Salesforce 连接使用 SOQL 而非 SQL，DBX 据此调整了 MCP 的行为： * `dbx_list_tables` 列出组织中的对象，`dbx_describe_table` 列出对象字段，`dbx_execute_query` 执行 SOQL（例如 `SELECT Id, Name FROM Account LIMIT 10`）。 * `dbx_list_databases` 会说明一个 Salesforce 组织就是一个作用域，而不会虚构数据库。 * `dbx_execute_batch` 与 `dbx_open_session` 会被拒绝：SOQL 只读，不存在需要批处理的多语句脚本；每次调用都是无状态 REST 请求，没有可固定的会话，也没有可开启的事务。 * 写入记录永远不会走查询通道。`dbx_execute_query` 会以 `SALESFORCE_DML_REQUIRES_CONFIRMATION` 拒绝写入尝试，因此下面的确认流程无法被绕过。 ### 写入确认 写入分为两次调用，且只有当人看到第一步的摘要后第二步才可能执行： 1. 调用 `dbx_salesforce_prepare_write`，传入 `connection_id`（或 `connection_name`）、`op`（`insert`、`update` 或 `delete`）、`object`（API 名称，如 `Account` 或 `Invoice__c`）；`update`/`delete` 需要记录 `id`，`insert`/`update` 需要 `fields`。此时不会向 Salesforce 发送任何请求。 2. 把返回的摘要展示给用户：操作、对象、记录 Id、每个字段值、连接，以及该变更所归属的身份。 3. 调用 `dbx_salesforce_apply_write`，传入第 1 步返回的 `confirm_token`。 令牌只能使用一次，签发 5 分钟后过期，并与那一条语句绑定——写入内容变了就必须重新准备。重放、过期或从未签发的令牌会以 `CONFIRM_TOKEN_INVALID` 失败。DBX 在应用阶段会重新检查连接范围、工具白名单、只读与生产保护以及 DML 开关，因此两次调用之间撤销权限会立即生效。 Salesforce 写入不是事务性的。 `dbx_salesforce_apply_write` 返回后，组织中的记录已经改变，DBX 无法回滚。每次调用只影响一条记录： `upsert` 、批量与 composite 写入会在准备阶段以 `SALESFORCE_DML_INVALID` 拒绝。准备写入需要 **设置 → MCP** 中该连接的 **允许 DML** 开关，它默认关闭，未开启时返回 `SALESFORCE_DML_DISABLED` ；执行模式为只读时该开关一律无效。 ### 写入归属的身份 `dbx_salesforce_current_user` 返回当前连接用户、简档、组织显示名，以及该简档是否具有 **Modify All Data**——这个标志决定字段级安全和记录共享规则是否生效。准备写入前先调用它，也可以用它区分权限失败与记录 Id 错误。`dbx_salesforce_prepare_write` 的摘要中包含同样的身份信息；若查询失败，摘要会写明身份未知并仍然完成准备，把是否应用的决定权留给用户。 ## 数据库访问 ### DBX Desktop 原生 Streamable HTTP Desktop 可以选择直接托管 Streamable HTTP MCP 服务。该服务**默认关闭**；在 **设置 → MCP → HTTP 服务**启用后，默认仅监听 `127.0.0.1:5225/mcp`。监听服务由 Desktop 进程管理，会生成本地 Bearer Token，页面提供可复制的客户端配置；服务异常退出时会由 Desktop 自动重新拉起。 本机 MCP 客户端的接入步骤： 1. 打开 **设置 → MCP → HTTP 服务**，开启 **Streamable HTTP 服务**。除非确实需要让其他设备访问，否则保持默认本机回环地址。 2. 点击 **保存并应用**。该按钮会保存配置，并根据开关状态启动、重启或停止服务；修改地址、端口或路径时会自动重启服务。 3. 将页面展示的服务地址和 Bearer Token 复制到 MCP 客户端。 不同客户端的字段名称可能不同，但核心配置如下： ```json { "type": "http", "url": "http://127.0.0.1:5225/mcp", "headers": { "Authorization": "Bearer " } } ``` 本机客户端建议保留默认回环监听。绑定到局域网地址时，必须开启 **允许远程访问**，并填写精确的允许 `Host`；浏览器客户端还必须填写精确的 `Origin`。客户端通过非默认端口访问时，允许的 Host 应写成 `host:port`。轮换 Token 会立即使旧凭证失效。 ### 本地连接 这是默认模式。MCP 使用 DBX 中保存的连接配置。原生可执行的连接不要求 DBX 桌面端保持运行；需要 Desktop bridge 或已安装 Agent/驱动的连接仍依赖对应运行时。 常见的本地数据库文件路径： | 平台 | 默认路径 | | ------- | -------------------------------------------------- | | macOS | `~/Library/Application Support/com.dbx.app/dbx.db` | | Linux | `~/.local/share/com.dbx.app/dbx.db` | | Windows | `%APPDATA%\com.dbx.app\dbx.db` | `DBX_DATA_DIR` 必须指向包含 `dbx.db` 的目录，而不是数据库文件本身。Windows 便携版通常是 `DBX.exe` 同级的 `data` 目录。 原生 SQL、独立 Redis 和 MongoDB 等路径可以由 MCP 直接执行。SSH、集群、厂商专用、外部驱动以及 Agent/JDBC 连接是否可用，取决于连接配置和本机已安装的 DBX 组件；不要从“DBX 支持该数据库”推断 MCP 原生包已经内置全部运行时。 DuckDB 使用独立的 DBX DuckDB 驱动。通过本地 MCP 查询 DuckDB 前，需要先在 **DBX Driver Manager** 中安装该驱动。MCP 二进制只包含 sidecar 客户端，不会内置 DuckDB 引擎。 ### Agent/JDBC 数据库 Oracle、金仓KingbaseES 和虚谷需要匹配的 DBX 原生 Agent，但不需要 JRE。达梦、DB2、Hive、Trino、Snowflake、SAP HANA 等 JDBC Agent 数据库需要匹配的 Agent、JDBC 驱动和 JRE。请先在 DBX 中安装所需组件，再使用 MCP。 ### DBX Web / Docker 模式 设置 `DBX_WEB_URL` 后，MCP 会使用部署的 DBX Web 后端，而不是读取本机连接。如果 Web 登录启用了密码保护，还要设置 `DBX_WEB_PASSWORD`，值为 Web 登录页使用的密码。 DBX Web 请求遵循标准系统代理环境变量：https 地址读取 `HTTPS_PROXY`/`https_proxy`，http 地址读取 `HTTP_PROXY`/`http_proxy`，`ALL_PROXY`/`all_proxy` 作为兜底，`NO_PROXY`/`no_proxy`（逗号分隔的主机列表，例如 `localhost,127.0.0.1,.internal.example`）作为绕过列表。代理值为空或未设置时直连（不走代理）。支持 HTTP、HTTPS 与 SOCKS5 代理（`http://127.0.0.1:7890` 或 `socks5://127.0.0.1:1080`）；需要认证的代理使用标准 `user:password@host:port` URL 形式，例如 `http://admin:admin123@127.0.0.1:7890`。如需为每次 DBX Web 请求附加自定义请求头（例如网关前的令牌认证），将 `DBX_WEB_HEADERS` 设置为 JSON 对象，键为请求头名称、值为字符串，例如 `{"Authorization":"Bearer "}`。目标为自签名 HTTPS 时，证书验证默认开启：设置 `DBX_WEB_INSECURE_SKIP_VERIFY=1` 可跳过验证，或设置 `DBX_WEB_CA_CERT` 指向 PEM/DER CA 文件以信任私有 CA。同样的变量在 DBX CLI 的 Web 模式下同样生效。 DBX Web 和 Docker 同样需要独立 DuckDB 驱动。首次启动后可通过 Driver Manager 安装；Docker 会把驱动保存到 `/app/data/agents`，挂载 `/app/data` 数据卷后升级容器不会丢失。 ### DBX Web 原生 Streamable HTTP DBX Web 可以直接托管 MCP，复用现有 Web 监听器和 `/mcp` 路径，因此 Docker 和反向代理部署不需要额外暴露第二个端口。单实例、已启用 Web 登录密码的部署可在 **设置 → MCP → HTTP 服务**填写允许的 Host 并启用服务；DBX 自动生成 Bearer Token，使用现有加密 Secret 存储，可在页面复制、轮换或禁用，修改立即对新请求生效。未启用时页面不会把 `/mcp` 显示为可连接地址。无 Web 登录密码时，页面管理的 MCP 不会生效；演示部署禁用 MCP。 部署环境变量仍然优先：配置 `DBX_WEB_MCP_TOKEN` 或 `DBX_WEB_MCP_TOKEN_FILE` 后，页面只读显示状态，不会覆盖部署 Secret。此前启用的页面 Token 仍会保留；移除部署 Token 并重启 Web 后，它会重新生效。将 `DBX_WEB_MCP_ALLOWED_HOSTS` 配置为客户端在 `Host` 请求头中发送的公网访问地址；如有端口映射，必须包含映射后的端口。多实例部署应使用一致的部署 Secret 与白名单，而不是页面管理模式。生产环境请使用 `DBX_WEB_MCP_TOKEN_FILE` 或部署平台的 Secret 管理能力，不要把真实 Token 提交到 Compose 文件中。 例如容器映射为 `4225:4224` 时，MCP 地址为 `http://localhost:4225/mcp`： ```yaml environment: DBX_WEB_MCP_TOKEN: replace-with-a-long-random-secret DBX_WEB_MCP_ALLOWED_HOSTS: localhost:4225 ports: - "4225:4224" ``` 客户端必须携带 `Authorization: Bearer `。浏览器客户端还需要在 `DBX_WEB_MCP_ALLOWED_ORIGINS` 中填写精确 Origin，例如 `https://mcp.example.com`；原生客户端通常不会发送 `Origin` 请求头。若反向代理添加了公网路径前缀，请设置 `DBX_PUBLIC_BASE_PATH=/dbx`，此时原生端点为 `/dbx/mcp`。原生 HTTP 与现有的 `DBX_WEB_URL` stdio 适配方式可以同时使用：两者共享 DBX 连接和 MCP 策略，后者仍适合只支持 stdio 的客户端。 ### 桌面 UI 工具 `dbx_open_table` 和 `dbx_execute_and_show` 要求 DBX 桌面端正在运行，并且在 Web 模式或连接作用域隐藏 UI 工具时不可用。其他工具是否需要 Desktop 取决于该连接是原生执行还是 bridge/Agent 路径。 ## 安全和环境变量 DBX 在 **设置 → MCP** 中保存一份权威策略，并在每次请求时重新读取： | 权限模式 | 允许的操作 | | ---- | --------------------------------------------------------- | | 只读 | 查询和元数据读取 | | 数据读写 | 普通插入、带有效过滤条件的更新/删除、范围明确的 MongoDB 修改和普通 Redis 写入 | | 完全访问 | 额外允许大范围更新/删除、DDL、`TRUNCATE`、MongoDB 破坏性操作和 Redis `FLUSH*` | `WHERE TRUE`、`WHERE 1 = 1`、`_id: {$exists: true}` 或不透明 MongoDB 过滤器仍按高风险处理。连接自身只读、生产库保护、数据库账号权限和 MCP 连接 allowlist 在任何模式下都是权限上限。 对于已暴露给 MCP 的连接，**设置 → MCP** 可以设置连接默认执行权限：继承全局、只读、安全写入或高风险写入。选择指定数据库后，还可为单个数据库设置执行权限。执行权限按范围由小到大回退：**单库设置 → 连接默认 → 全局默认**；例如全局和连接默认均为“数据读写”时，可为单个数据库设置“完全访问”。连接自身只读、生产库保护、数据库范围和数据库账号权限仍是独立的硬性限制，不能被单库设置绕过。 同一页面还可只暴露选定的 MCP 工具。这项限制在服务端的每一次调用中都会强制执行，不只是客户端的展示偏好；即使客户端缓存了旧工具列表，也会在服务端 allowlist 更新后被拒绝。 ### 按顺序配置授权范围 在 **设置 → MCP** 中建议按以下顺序定义最终权限范围： 1. 选择 MCP 可见的是**所有连接**（包括以后新增的连接），还是仅**指定连接**。 2. 为每个已暴露连接选择**全部数据库**、**仅指定数据库**或**不允许访问**。指定数据库名按精确名称匹配；可先调用 `dbx_list_databases` 获取当前允许使用的名称，并为选中的数据库按需设置执行权限。 3. 为每个连接设置默认执行权限。未配置单库覆盖、或选择全部数据库时，该默认值就是连接内数据库的执行权限。 4. 仅选择客户端实际需要的 MCP 工具，再设置全局默认执行权限模式。 执行权限由最具体的设置决定，但已允许的工具仍不能绕过隐藏连接、数据库范围、连接只读、生产库保护或数据库账号本身的权限。请求未被选中数据库时，服务会返回 `DATABASE_OUT_OF_SCOPE`；配置单库执行权限时，跨库 SQL 和 MongoDB 聚合写入会被拒绝，避免绕过数据库级限制。 升级时，未带执行策略版本的已保存连接规则继续使用旧的权限上限语义，不会放大全局权限。只有当前设置页面保存的规则会标记为范围覆盖语义；编辑旧规则时，系统会先固化其实际生效的权限上限，再启用新的覆盖行为。 新版 Server 不允许 `DBX_MCP_ALLOW_WRITES` 或 `DBX_MCP_ALLOW_DANGEROUS_SQL` 放宽 DBX 中央策略。为兼容升级，在中央策略首次保存前，旧配置中的 `DBX_MCP_ALLOW_WRITES=0`（或 `false`）仍会保持 MCP 只读；策略保存后仅以中央策略为准，并忽略旧权限变量。旧连接 scope 变量只能进一步收窄 DBX allowlist。 | 变量 | 用途 | | ------------------------------------------ | ------------------------------------------------------------------------------ | | `DBX_DATA_DIR` | 覆盖本地 DBX 数据目录 | | `DBX_SESSION_IDLE_TTL_SECS` | 有状态会话空闲超时，单位为正整数秒，默认 `1800`。非法值、零、负数或无法表示的时长回退默认值；同样适用于事务专属连接。修改后需重启 MCP 宿主进程。 | | `DBX_WEB_URL` | 使用 DBX Web/Docker 后端 | | `DBX_WEB_PASSWORD` | 登录 DBX Web | | `HTTP_PROXY` / `HTTPS_PROXY` / `ALL_PROXY` | DBX Web 请求的标准系统代理变量；空值表示不走代理。认证格式 `http://user:pass@host:port` | | `NO_PROXY` | 上述代理的标准绕过列表（逗号分隔主机） | | `DBX_WEB_HEADERS` | DBX Web 请求附加的请求头 JSON 对象，例如 `{"Authorization":"Bearer token"}` | | `DBX_WEB_INSECURE_SKIP_VERIFY` | `1`/`true` 时跳过 TLS 证书验证（用于自签名 DBX Web 后端；默认验证） | | `DBX_WEB_CA_CERT` | DBX Web TLS 验证时信任的 PEM/DER CA 文件 | | `DBX_WEB_MCP_TOKEN` | 使用该 Bearer Token 启用原生 Web Streamable HTTP MCP | | `DBX_WEB_MCP_TOKEN_FILE` | 从文件读取原生 Web MCP Token；不能与 `DBX_WEB_MCP_TOKEN` 同时设置 | | `DBX_WEB_MCP_ALLOWED_HOSTS` | 原生 Web MCP 必填：允许的公网 Host authority，逗号分隔 | | `DBX_WEB_MCP_ALLOWED_ORIGINS` | 原生 Web MCP 的浏览器 Origin allowlist，逗号分隔 | | `DBX_MCP_ALLOW_WRITES` | 仅用于升级兼容：`0`/`false` 使尚未配置的策略保持只读 | | `DBX_MCP_SCOPE_CONNECTION_ID` | 兼容旧配置：限制为一个连接 ID | | `DBX_MCP_SCOPE_CONNECTION_IDS` | 兼容旧配置：限制为多个连接 ID | | `DBX_MCP_SCOPE_CONNECTION_NAME` | 限制为一个连接名称 | | `DBX_MCP_SCOPE_DATABASE` | 限制为一个数据库 | | `DBX_MCP_DEBUG_SQL` | 临时诊断时输出 SQL | ## 常见问题 ### 升级后的凭据访问 独立 macOS MCP 在后台运行时不弹出钥匙串对话框。已有加密密钥被锁定或拒绝访问时，启动会保留 `KEYRING_ACCESS_FAILED`（可能包含在 `SECRET_KEY_UNAVAILABLE` 中），而不是反复要求输入密码。先解锁登录钥匙串；对于旧版绑定构建哈希的授权，在终端对 **MCP 客户端实际使用的同一个官方程序**执行一次： ```bash "$HOME/.dbx/bin/dbx-mcp" --authorize-keychain ``` Homebrew 或 npm 安装需要替换为对应的二进制路径。该命令先验证运行程序的官方签名和稳定 designated requirement，再读取已有 DBX 钥匙串条目；不会打开数据库、启动 MCP 传输、创建或替换密钥、导出密钥，也不会自行改写 ACL。macOS 首次迁移时可能要求确认一次，对已验证的 DBX 程序选择 **始终允许**，然后重启 MCP 客户端。已获授权的程序应直接成功。稳定签名使普通正式升级继续沿用授权，但不能绕过签名团队变更或用户撤销权限。 不要将 `--authorize-keychain` 添加到 MCP 客户端的启动参数，它是执行后立即退出的一次性恢复命令。缺失的密钥仍需通过 Desktop 数据安全设置处理，该命令不能恢复丢失的密钥。Windows 和 Linux 不使用此 macOS 命令；应恢复同一系统用户的凭据库访问（或配置的无界面密钥文件），再重启 MCP。凭据库拒绝访问或密钥损坏时，不应自动生成替代加密密钥。 ### npm 没有安装当前平台包 不要使用 `--no-optional` ，重新安装 `@dbx-app/mcp-server` ，并用 `node -p 'process.platform + "-" + process.arch'` 检查平台。Alpine Linux 默认使用 musl，目前不在 Linux 发布包支持范围内。 ### 找不到 dbx.db 将 `DBX_DATA_DIR` 设置为包含 `dbx.db` 的目录。Windows 便携版通常是 `DBX.exe` 旁边的 `data` 目录。 ### 提示 DBX 未运行 只有 `dbx_open_table` 和 `dbx_execute_and_show` 需要桌面端运行；本地查询工具可以在 DBX 关闭时执行。 ### Desktop HTTP 客户端提示 ERR_CONNECTION_REFUSED 进入 **设置 → MCP → HTTP 服务** ，确认服务已开启并点击 **保存并应用** 。客户端应使用页面展示的地址、路径和当前 Bearer Token。默认的 `127.0.0.1` 只接受同一台电脑上的连接。 ### Desktop 提示 HTTP 地址已被占用 已有其他进程监听了所选地址和端口。请在 **设置 → MCP → HTTP 服务** 中改用未被占用的端口，再保存配置以重启服务。不要让两个 DBX Desktop 实例使用相同 HTTP 端点。 ### 请求返回 DATABASE_OUT_OF_SCOPE 该连接虽然已暴露给 MCP，但请求的数据库不在它的 MCP 数据库范围内。请在 **设置 → MCP** 中添加精确的数据库名称，或在合适时将该连接设为全部数据库。指定范围时，应先调用 `dbx_list_databases` ，再使用返回的名称。 ### 之前可见的工具现在被拒绝 该工具已不在 **设置 → MCP** 的选中范围内，或当前权限策略不允许它。修改工具 allowlist 后请刷新 MCP 客户端的工具列表；服务端同样会拒绝缓存的旧工具调用。 ### Docker 或反向代理下 MCP 请求失败 请使用公网访问地址，包括映射后的端口和 `DBX_PUBLIC_BASE_PATH` 前缀。 `DBX_WEB_MCP_ALLOWED_HOSTS` 必须与实际 `Host` authority 精确一致；浏览器客户端还必须在 `DBX_WEB_MCP_ALLOWED_ORIGINS` 中配置精确 Origin。 ### Agent/JDBC 数据库无法启动 在 DBX Driver Manager 中安装或更新匹配的 Agent、JDBC 驱动和 JRE。厂商专有驱动不会随 MCP 原生包发布。 ### DuckDB 连接无法启动 在 DBX Driver Manager 中安装或更新 DuckDB 驱动。本地 MCP、DBX Web 和 Docker 都通过独立驱动运行 DuckDB，不会内置 DuckDB 引擎。 ### 出现 better-sqlite3 或 Node ABI 错误 MCP 不需要 `better-sqlite3` 。请先升级 `@dbx-app/mcp-server` ；如果错误来自 `@dbx-app/cli` ，请按照 CLI 的安装要求处理，因为它们是两个独立的包。 ## 系统要求 * Node.js 18.18.0 或更高版本 * 已安装 DBX，并至少配置一个数据库连接 * Agent/JDBC 数据库需要匹配的 Agent、驱动和 JRE * 使用两个桌面 UI 工具时，需要保持 DBX 桌面端运行