MCP 集成

什么是 MCP？

MCP（Model Context Protocol）是让 AI 客户端调用外部工具的开放协议。DBX MCP 可以让 AI 助手使用 DBX 中已经配置好的数据库连接。

AI 助手 → DBX MCP → 你的数据库 → 返回结果
                    ↘ DBX 桌面端（打开或展示结果）

原生安装（推荐）

无需 Node.js。macOS 或 Linux 执行：

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

Windows 在 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：

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 快速开始

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

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

支持的 AI 助手

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。

- 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__<tool>。请保持 serverName: dbx 稳定，避免工具名和权限规则发生变化。连接访问范围和执行模式仍统一在 DBX 设置 → MCP 中管理。

工具列表

DBX MCP 当前提供以下工具（具体可用工具取决于构建功能及权限设置）：

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 的发现和读取会复用对应 Tool 的白名单，以及连接、分组、数据库和运行时范围限制。查询参数值必须进行 URI 编码。SQL 执行和所有可写操作仍只通过 Tool 提供。

读取 Kafka 消息

包含 mq-admin 的构建在本地和 Web 模式下均提供 dbx_peek_messages。通过 connection_id 或 connection_name 选择已保存的 Kafka 连接，并指定 topic。工具遵守 MCP 连接范围及工具白名单，允许读取只读连接和生产连接，不提交消费位点。

{
  "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 服务端设置；使用独立启动器时，在启动器环境中设置。

原生 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 事务执行有界回滚，然后销毁连接。

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 开关，因此两次调用之间撤销权限会立即生效。

写入归属的身份

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 客户端。

不同客户端的字段名称可能不同，但核心配置如下：

{
  "type": "http",
  "url": "http://127.0.0.1:5225/mcp",
  "headers": {
    "Authorization": "Bearer <DBX Desktop 页面展示的 Token>"
  }
}

本机客户端建议保留默认回环监听。绑定到局域网地址时，必须开启 允许远程访问，并填写精确的允许 Host；浏览器客户端还必须填写精确的 Origin。客户端通过非默认端口访问时，允许的 Host 应写成 host:port。轮换 Token 会立即使旧凭证失效。

本地连接

这是默认模式。MCP 使用 DBX 中保存的连接配置。原生可执行的连接不要求 DBX 桌面端保持运行；需要 Desktop bridge 或已安装 Agent/驱动的连接仍依赖对应运行时。

常见的本地数据库文件路径：

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 <token>"}。目标为自签名 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：

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_TOKEN>。浏览器客户端还需要在 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 中保存一份权威策略，并在每次请求时重新读取：

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。

常见问题

升级后的凭据访问

独立 macOS MCP 在后台运行时不弹出钥匙串对话框。已有加密密钥被锁定或拒绝访问时，启动会保留 KEYRING_ACCESS_FAILED（可能包含在 SECRET_KEY_UNAVAILABLE 中），而不是反复要求输入密码。先解锁登录钥匙串；对于旧版绑定构建哈希的授权，在终端对 MCP 客户端实际使用的同一个官方程序执行一次：

"$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。凭据库拒绝访问或密钥损坏时，不应自动生成替代加密密钥。

系统要求

• Node.js 18.18.0 或更高版本
• 已安装 DBX，并至少配置一个数据库连接
• Agent/JDBC 数据库需要匹配的 Agent、驱动和 JRE
• 使用两个桌面 UI 工具时，需要保持 DBX 桌面端运行