DataNexa 帮助文档

第一次打开 DataNexa#

DataNexa 是一个运行在你本机的数据库 MCP 网关。它把 SQLite、MySQL、PostgreSQL 以及通过 JDBC 接入的数据库，统一成一份 MCP 服务提供给 AI Agent，并在查询到达数据库之前完成只读校验、资源限制与审计记录。

安装与首次启动

1. 从 GitHub Releases 下载对应系统的安装包，安装后启动 DataNexa。安装包不内置 Java 运行时，JDBC 功能会在需要时单独准备。
2. 首次打开会进入概览页。此时 MCP 服务尚未启动，连接数为 0，属于正常状态。
3. 建议先完成新建数据库连接 → 测试连接 → 启动 MCP 服务 → 接入 Agent 四步。

截图占位 · 01 01-overview.png 概览页全貌：侧边栏、服务状态卡、四项指标、快速开始与最近日志。 建议 1600 × 1000 · PNG · 浅色主题 · 服务保持运行中

你的数据存在哪里

导出连接文件会把数据库密码写入文件（默认要求设置加密密码）。请只在受控位置保存，迁移完成后及时删除。

六个页面分别做什么#

DataNexa 的左侧导航固定为六项：概览、数据库连接、工具、访问控制、审计日志、设置。日常使用基本沿着这条路径：先在「数据库连接」里准备数据源，再到「概览」启动服务，最后把配置交给 Agent。

截图占位 · 02 02-sidebar-navigation.png 左侧导航栏特写：六个菜单项、底部服务状态与主题切换。 建议 720 × 1000 · PNG · 深色主题

顶栏与全局状态

页面右上角的快捷操作随页面变化：在「数据库连接」页可以一键紧急断连，在「审计日志」页可以打开筛选，在「访问控制」页可以快速创建令牌。

侧边栏底部始终显示 MCP 服务的状态：服务运行中 · 端口 或 服务已停止。点击状态可以在概览页查看详情。

主题、语言与动效

• 主题：侧边栏底部的按钮在浅色与深色之间切换；「设置 → 通用 → 显示」还可以选择「跟随系统」。
• 语言：「设置 → 通用 → 显示 → 界面语言」可在简体中文与 English 之间切换，立即生效。
• 动效：「MCP 被调用时显示能量脉冲」默认开启。调用成功与失败会在概览状态卡上留下不同颜色的反馈。

四步接入 Agent#

如果你刚装好 DataNexa，跟着这一章走一遍即可完成最小可用配置。每一步都可以在后续章节找到更细的说明。

截图占位 · 03 03-quickstart-cards.png 概览页「快速开始」三张卡片：连接数据库、启动服务、接入 Agent。 建议 1400 × 760 · PNG · 浅色主题

完成前的自查清单

• 连接状态为「启用」，而不是「暂停」。
• 服务状态显示「运行中」，并记下端点地址与端口。
• Bearer 鉴权开启时，客户端配置里带有正确的 Authorization 头。
• 至少保持 datanexa_list_connections 与 datanexa_get_schema 两个工具开启，便于 Agent 先发现数据结构。
• 在「审计日志」中能看到刚才的调用记录。

添加数据库连接#

这一章说明一条连接怎么建、怎么测、怎么停，以及密码最后落在哪里。做完之后你会得到一条「能连、能查、能停」的只读连接，后面的 MCP 服务与 Agent 才有数据可用。

连接列表与右侧检查器

「数据库连接」页面分两栏：左边是全部连接，右边是当前选中连接的明细。每条记录显示数据库图标、名称、状态标签和一行地址摘要：SQLite 显示数据库文件，MySQL 与 PostgreSQL 显示 host:port，JDBC 显示 JDBC URL。

行内右侧是五个图标按钮，鼠标悬停会显示名称：电源图标切换启用与暂停，线缆图标是「测试连接」，放大镜图标是「诊断连接」且对 JDBC 连接不可用，竖排点图标打开编辑，垃圾桶图标删除。连接被暂停后，测试与诊断都会失效。复制入口只在右侧检查器里：点那里的连接名即复制，并提示「连接名已复制。」。

右侧检查器列出这台连接的全部关键参数：主机、端口、数据库、用户名、SSL 模式、最大返回行数、查询超时（毫秒）、最大连接数、最大结果大小（按 KiB 显示）。SQLite 的主机一栏固定显示 LOCAL；JDBC 连接只显示 JDBC URL，其余地址字段不适用。

截图占位 · 04 04-connections-list.png 画面内容：连接列表至少 3 条（含启用与暂停各一），右上角「新建连接」，行内测试/编辑入口，右侧检查器，左侧侧边栏。 建议 1600 × 1000 · PNG · 浅色主题

新建一条连接

新建和编辑共用同一个弹窗，分为基础信息、连接地址、凭证与限制三段。保存前可以先点「测试连接」，用当前填写的值试连一次，不会先写入配置。

截图占位 · 05 05-connection-editor.png 画面内容：新建连接弹窗，类型下拉加上已填写的 MySQL 或 PostgreSQL 字段，密码输入框打码，下方是限额区域与「测试连接」「保存连接」。 建议 1400 × 1000 · PNG · 浅色主题

字段与默认值

下表列出弹窗里的全部字段。标注「必填」的字段留空时保存会被拒绝，并给出对应的错误提示。

四项限额决定单次查询最多能返回多少内容。填超出范围的值会被自动夹到最近的边界，数值换算关系是 1 KiB = 1024 字节。

密码存在哪里

连接元数据保存在 TOML 配置文件里，密码单独存入本机凭证库。配置文件只保存形如 vault://local_db 的引用，不是密码本身；凭证库就是操作系统的凭证存储，服务名固定为 com.mingo.datanexa。

「凭证与限制」组底部会显示当前状态，例如「当前凭证：vault://local_db。DataNexa 不会把明文密码写入配置文件。」，没有存过密码时显示「尚未保存」。点「清除已保存凭证」会把该连接在凭证库里的条目删掉，之后这条连接必须重新输入密码才能使用。

「测试连接」与「诊断连接」的区别

两个按钮长得像，做的事情完全不同。「测试连接」会真的连一次数据库：成功时提示「连接可用 · 耗时」，失败时把数据库返回的错误原样带出来。原生连接测试失败后还会附上一段本地诊断信息，方便一起判断。

「诊断连接」不连数据库，只读本地配置与凭证库，然后给出一行摘要：连接名称、类型和凭证状态，必要时再加一条针对性的提示。凭证状态有六种取值——「不需要」（SQLite）、「未保存」、「已保存空密码」、「已保存」、「凭证引用存在，但本机凭证库里找不到密码」、「读取本机凭证库失败」。诊断只在原生连接上可用，JDBC 连接不会显示这个按钮。

紧急断连

连接页顶部有一个三角警告图标的动作，名字是「紧急断连」。它的用途是当你怀疑 Agent 正在做不该做的事时，用一次点击切断所有数据库访问，而不是逐条去关连接。

• 前置条件：MCP 服务必须在运行，服务已停止时按钮是灰的。
• 按下之后：进行中的请求被取消，已打开的原生连接池与 JDBC 会话全部关闭，界面上所有连接操作同时禁用。
• 恢复：同一按钮此时显示为「退出紧急断连」，再点一次即回到正常状态，连接开关回到进入前的样子。

导入与导出

入口在「设置 → 通用 → 导入/导出」，面板里只有两个动作：「导出连接」和「导入连接」。导出前必须二选一：设置加密密码，或者选择不加密导出。

加密导出需要输入两遍「加密密码」，至少 8 个字符，两次不一致会提示「两次输入的加密密码不一致。」。这个密码不会被保存，文件一旦丢失就无法恢复。选择「不加密导出」时会先弹出警告，列出三条风险，并要你勾选「我了解导出文件会以明文保存数据库密码」才允许继续。

导入是追加，不是覆盖：文件里的每条连接都会拿到一个新的内部 ID，与现有连接同名也不会覆盖。个别条目无法导入时会被跳过，提示会写成「已新建 N 个数据库连接，跳过 M 个无法导入的连接。」。加密文件会先要求输入密码，并显示文件的导出时间；密码错误提示「加密密码错误，或文件已损坏。」。单个导入文件上限 5 MB、最多 1000 条连接。

排错

仍然连不上时，先点「诊断连接」确认凭证状态，再看「审计日志」里有没有对应的失败记录。开启调试日志后，连接测试失败的原因也会写进日志文件。

通过 JDBC 连接其他数据库#

SQLite、MySQL、PostgreSQL 之外，DataNexa 可以借 JDBC 驱动连到更多数据库。这一章讲清楚三件事的先后关系——Java 运行时、驱动 Bundle、连接，以及这项能力在哪里会失效。

JDBC 支持的范围与限制

原生连接只覆盖三种数据库，且每种都做了针对性适配。其他数据库（例如各类国产库、ClickHouse、Hive、Oracle 等）没有一个统一的协议，只能借 JDBC 驱动去连。设置页把这一项标成「JDBC 支持」，标签上带一个「预览」角标，意思是功能可用但还在演进。

代价是 DataNexa 无法替每个驱动、每个数据库版本、每种 SQL 方言做验证。设置页底部常驻两段说明：一段是「无论驱动原生能力如何，DataNexa 的只读保护与超时兜底始终生效」，另一段是风险摘要，点「查看详情」可以看到完整清单。风险归成四类：兼容性、方言、资源、驱动本身。

第一步：Java 运行时

JDBC 驱动是一段 Java 代码，必须有一个 Java 运行时来跑。入口在「设置 → JDBC 支持」，页面最上方是「Java 运行时」卡片，显示可用或不可用、Java 版本、以及来源。

• 来源有两种：「DataNexa Java 运行时」（由应用下载托管）和「外部 Java 运行时」（你指定的 JAVA_HOME）。
• 下载：运行时不可用时卡片上出现「下载 DataNexa Java 运行时」，过程依次显示准备、下载、校验、解压、安装五个阶段。
• 更新：托管运行时可以点「检查 Java 运行时更新」，有新版本时按钮变成「更新到 {版本}」。
• 换成外部运行时：文件夹图标是「选择外部 Java 运行时」；选过之后出现「使用 DataNexa Java 运行时」用来切回。
• 卸载：托管运行时存在时才有垃圾桶按钮，确认后删除；外部运行时不受影响，JDBC 会话运行期间不允许卸载。

截图占位 · 08 08-jdbc-runtime.png 画面内容：Java 运行时卡片，显示可用状态、Java 版本、来源（DataNexa Java 运行时），以及右上角的更新与卸载入口。 建议 1400 × 900 · PNG · 浅色主题

第二步：安装驱动 Bundle

驱动卡片上有两个动作：「安装驱动」从 Maven 仓库拉取，「导入本地驱动」直接选本地 JAR 或目录。两者都要求 Java 运行时可用，否则按钮是灰的。安装完成后生成一个 Bundle：目录里是 JAR 与一份清单，清单记录每个 JAR 的大小与 SHA-256，每次使用前都会校验，文件被改动或缺失会直接报「驱动 Bundle 不完整或已损坏」。清单里另有一块能力探测结果，见下一节。

从 Maven 安装时需要填「显示名称」和「Maven 坐标」，坐标格式是 groupId:artifactId:version，例如 org.postgresql:postgresql:42.7.4。「Maven 镜像源」可选 Maven Central、Aliyun、Huawei Cloud、Tencent Cloud，或选「自定义仓库」后填自己的 HTTPS 地址。过程中依次显示：准备安装、下载运行时依赖、校验文件完整性、检测 JDBC Driver、创建驱动 Bundle。

导入本地驱动时填「显示名称」，再用「选择 JAR 文件」挑文件；也可以直接在路径框里写多条路径，用分号分隔，路径可以是 JAR 也可以是包含 JAR 的目录。安装时要能从 JAR 里找到至少一个 JDBC Driver 实现，否则会失败；成功后被发现的类就记在 Bundle 里，新建连接时不必再填。

截图占位 · 07 07-jdbc-drivers.png 画面内容：设置 → JDBC 支持，已安装驱动列表（显示名称、坐标、Driver Class、占用大小）加「驱动原生支持」能力标识，右上角「安装驱动」「导入本地驱动」。 建议 1600 × 1000 · PNG · 浅色主题

能力标识什么时候出现

每行驱动下方有「驱动原生支持」一栏，后面跟两枚标识：「只读限制」和「超时限制」。对勾表示驱动接受 setReadOnly 或 setQueryTimeout，叉号表示驱动拒绝，未探测时显示「测试连接后检测」。

探测不是安装时做的，而是在真正用到驱动的时候：在连接页对这条 JDBC 连接执行一次「测试连接」，或者让 Agent 发起一次查询。结果写回 Bundle 清单里的能力字段，之后一直显示，不需要重复探测（只改写这一块，JAR 文件本身不动，SHA-256 校验也就不会失效）。驱动拒绝某项能力只会让查询继续跑，不会让查询失败，这也是为什么「叉号」不等于「不能用」。

第三步：新建 JDBC 连接

在「数据库连接」页新建连接，类型选 JDBC，地址区域会变成四个字段。底部会提示一句：JDBC 技术预览支持通过 MCP 执行受控只读查询，未知方言或无法确认安全的语句会被拒绝。

与原生连接相比，JDBC 连接少了主机、端口、数据库、SSL 模式四项——这些都在 URL 里——也少了「诊断连接」这个按钮，因为诊断依赖原生驱动才会有的本地信息。限额、启用状态、测试连接、审计记录的行为与原生连接一致。

只读与超时是怎么兜底的

JDBC 路径没有方言专用的解析器，用的是通用 SQL 解析。策略引擎会先尝试解析这条语句：解析不了就拒绝，能解析但不是单条语句也拒绝，解析出来又不是只读形态（DDL、DML、带副作用的函数等）同样拒绝。也就是说，宽松的方向不可选，只会在「能确认安全」时才放行。

行数上限在 JDBC 路径下不是通过改写 SQL 加的 LIMIT，而是在读取结果集时逐行计数，达到上限就停止并标记为「截断」；结果大小超限时同样截断。查询本身可能已经在数据库侧执行完，行数限制并不会减少数据库的负载。

超时是双份的：DataNexa 侧给整次操作设一个上限，驱动侧再尝试设置语句级超时。驱动不支持语句超时（例如某些只读文件型驱动）时，第一条仍然生效，只是粒度更粗。

排错

JDBC 的失败原因通常只出现在提示条和调试日志里。开启调试日志后，驱动解析、超时、JDBC 辅助进程（sidecar）意外退出等问题都会留下记录，反馈问题时一并附上。

启动 MCP 服务并接入 Agent#

这一章说明 MCP 服务怎么启动、端点长什么样、鉴权如何开启，以及「复制接入配置」到底生成了什么。照着走一遍，你的 Agent 就能通过本机地址访问已启用的只读连接。

服务生命周期

入口在概览页顶部的状态卡。按钮在「启动服务」与「停止服务」之间切换，同一张卡片上还显示已启用的连接数、已启用的工具数和近 24 小时调用次数。侧边栏底部始终显示服务状态与端口，任何页面都能看到。

关闭窗口不会停止服务：窗口会被隐藏到托盘，MCP 服务继续在后台响应请求。只有从托盘菜单选择退出，进程才会真正结束。

截图占位 · 09 09-service-card.png 概览页服务状态卡：运行中、启停按钮、连接与工具计数、近 24 小时调用；下方快速开始第三步「复制接入配置」，左侧侧栏显示端口。 建议 1400 × 820 · PNG · 浅色主题 · 服务保持运行中

监听地址与端点

端点由监听地址、端口和固定路径 /mcp 组成。默认是 http://127.0.0.1:17321/mcp；监听地址和端口在「设置 → 通用 → MCP 服务策略」中修改，服务运行中修改会重启监听，绑定失败会自动回滚到原设置。

Bearer 鉴权

「要求 Bearer 密钥」默认开启，开关在「设置 → 通用 → MCP 服务策略 → 访问控制」。每个请求都要带 Authorization: Bearer <token>，密钥来自「访问控制」里创建的访问令牌；令牌同时决定这次连接能看到哪些数据库和工具。

关闭开关会先弹出确认框，说明失去密钥保护后的影响。确认后立即生效，不需要重启服务。

复制接入配置

在「概览 → 快速开始 → 接入 Agent」卡片上点「复制接入配置」。复制到剪贴板的内容由三段组成：一句说明、一行配置引导，以及下面这份 JSON。粘贴给 Agent，它就能据此写入你所用客户端的配置。

生成的 JSON 结构固定为 mcpServers.datanexa：transport 写 streamable-http，url 是当前端点，开启 Bearer 时再带上 headers.Authorization。它是一份通用配置，不针对某个客户端做字段转换。

{
  "mcpServers": {
    "datanexa": {
      "transport": "streamable-http",
      "url": "http://127.0.0.1:17321/mcp",
      "headers": {
        "Authorization": "Bearer PASTE_YOUR_TOKEN_HERE"
      }
    }
  }
}

• 关闭 Bearer 时：直接复制，JSON 里没有 headers 字段。
• 只有一个启用的令牌时：直接复制，密钥已写入 Authorization。
• 有多个启用的令牌时：先弹出「选择访问令牌」，选中后才复制，避免把别的 Agent 的密钥交出去。
• 一个启用的令牌都没有时：不会复制任何内容，而是跳到「访问控制」页，先创建一个令牌。

首次验证

配置写入客户端后，不要急着让它查业务数据，先按下面的顺序验证：

1. 让 Agent 调用 datanexa_list_connections。返回的是已启用的连接清单，不含密码；看不到某个连接，说明它被暂停或该令牌无权访问。
2. 再调用 datanexa_get_schema 查看表与视图，确认 Agent 看到的结构范围符合预期。
3. 回到「审计日志」，确认刚才两次调用都有记录，并核对工具名、连接与状态。

开机自启动与后台策略

三项开关都在「设置 → 通用 → 启动与后台」，它们决定开机后服务能否自动恢复：

排错

创建和管理访问令牌#

访问控制把同一个本地服务的权限拆成多个命名令牌：每个 Agent 用自己的密钥，只能看到被允许的连接与工具。这一章讲清楚令牌怎么建、密钥什么时候失效，以及熔断之后怎么恢复。

前提：先开启 Bearer

访问控制依赖 Bearer 鉴权。开启 Bearer 时，请求先由密钥识别出令牌身份，再按令牌的权限过滤数据库和工具；关闭 Bearer 时，请求没有身份，令牌也就无从约束。

如果 Bearer 是关闭的，打开「访问控制」只会看到一块提示，而不是令牌列表。点提示里的「开启 Bearer 密钥」即可，它会同时改写服务配置。

令牌列表与操作

访问控制页分左右两栏：左侧列表显示名称、启用状态、短 ID 与最近使用时间，右侧面板显示创建时间、权限与接入入口。行内四个按钮分别对应停用/启用、重命名、轮换与删除，危险操作都会先弹确认框。

截图占位 · 11 11-access-tokens.png 访问控制页：2–3 个访问令牌、启用状态、最近使用时间，右侧权限摘要与「复制 Agent Prompt」入口。 建议 1600 × 1000 · PNG · 浅色主题

创建令牌

入口在「访问控制」页顶部右侧的「创建令牌」按钮。创建过程只有一步：给令牌起一个能区分用途的名字。

1. 起名时写清使用者和用途，例如「笔记本 Cursor」「报表 Agent」。名称长度 1–80 个字符，之后还能改。
2. 确认后令牌立即创建，新密钥同时写入剪贴板，界面不会回显明文。
3. 在右侧权限面板按需关闭数据库与工具。新令牌默认允许所有「全局已启用」的连接和工具。
4. 点权限面板上方的「复制 Agent Prompt」，把带密钥的完整配置交给这个 Agent。

权限粒度

权限分两栏：数据库权限控制这个令牌能看到、能查哪些连接；工具权限控制它能调用哪些 MCP 工具。两栏都显示「已允许 / 全局已启用」的数量。

关闭某个连接后，它不会再出现在该令牌的 datanexa_list_connections 结果里；即使 Agent 拿着连接 ID 直接调用，也会被拒绝并记录为拦截。关闭某个工具后，它不会出现在 tools/list 中，直接调用同样会被拒绝。

密钥、轮换与失效

密钥不在页面上回显。创建或轮换后，新密钥会直接写入系统剪贴板；之后需要重新获取时，用该令牌的「复制 Agent Prompt」，它会取出密钥并拼成完整配置，同样只进剪贴板。

所以「密钥只给你一次」并不准确：只要你还能复制 Prompt，就还能拿到密钥。真正的控制手段是停用、轮换与删除——三者都立即生效，不需要重启服务。

自动熔断

自动熔断在「设置 → 安全 → 访问令牌自动熔断」。它统计单个令牌在窗口内的拦截次数，达到阈值就自动停用该令牌，避免一个配置错误的 Agent 反复越权。

开关默认关闭，且必须先开启 Bearer 才能打开；窗口与阈值也只在熔断开启后可调。

触发时发生的事情是确定的：

1. 窗口内该令牌的拦截记录数达到阈值，熔断器立即把令牌置为停用。
2. 写入一条审计记录，工具名为「自动熔断」，状态为拦截，原因里写明窗口、次数与阈值。
3. 该令牌之后的所有请求返回 401，直到你手动重新启用。
4. 重新启用后计数从头开始，窗口内早于上次熔断的拦截不再累计。

审计里怎么认出令牌

审计记录按令牌归属，列表与详情显示「名称（短 ID）」，短 ID 是令牌 UUID 去掉连接符后的前 8 位。筛选项里也能直接按令牌过滤。

• 没有令牌身份的记录：用来源标注区分——「系统」表示应用自身的动作，「未鉴权请求」表示 Bearer 关闭期间进来的调用，「旧版请求」表示历史遗留数据。
• 已删除的令牌：名称后追加「已删除」，用于把历史记录与现存令牌区分开。
• 熔断事件：工具列显示「自动熔断」，状态为拦截，可作为这条令牌的出问题起点。

最佳实践

• 一个 Agent 一个令牌。便于单独停用与追责，也能在审计里一眼看出是谁在查。
• 从最小权限开始。只留这个 Agent 真正需要的连接与工具；不确定时先关掉 datanexa_execute_readonly_sql，用结构发现类工具跑通流程。
• 定期轮换。把轮换当作换密码：怀疑泄露时立刻轮换，而不是只停用再启用。
• 换机或离职即处理。对应令牌直接删除；需要留档时先导出审计，再删。
• 不要把同一个令牌发给多个 Agent。共享密钥会让审计失去区分度，也无法单独收回某一方的权限。

排错

七个工具的参数与用法#

Agent 能做什么，取决于你开放了哪些工具。这一章逐个说明七个工具的用途、参数、返回和限制，以及只读策略在它们背后如何生效。

工具总表

七个工具分为三组，与「工具」页上的分组一致。关闭任意一个工具，Agent 的 tools/list 里就不会再出现它。

截图占位 · 13 13-tools-grid.png 工具页全貌：三个分组、七张工具卡与开关，顶部显示已启用数量。 建议 1600 × 1000 · PNG · 深色主题

结构发现：先看清有什么

三个工具都不读业务行，只读元数据。建议在提示词里要求 Agent 先调用它们，再决定查哪张表。

数据访问：读样本与执行查询

这两个工具会真正读到业务数据。是否开放、开放给哪个令牌，需要单独决定。

一次只读查询的请求

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "datanexa_execute_readonly_sql",
    "arguments": {
      "connection_id": "demo-mysql",
      "sql": "SELECT id, total FROM orders ORDER BY created_at DESC LIMIT 5"
    }
  }
}

返回的 structuredContent（content 里是同一份 JSON 文本，此处省略）。策略引擎会把最外层行数收紧到 max_rows + 1，用一行额外数据判断是否被截断：

{
  "policy": {
    "allowed": true,
    "reason": "只读 SQL 策略已允许该语句。",
    "rewritten_sql": "SELECT id, total FROM orders ORDER BY created_at DESC LIMIT 6"
  },
  "result": {
    "columns": ["id", "total"],
    "rows": [
      { "id": 42, "total": 128.5 },
      { "id": 41, "total": 76.0 }
    ],
    "row_count": 2,
    "truncated": false,
    "returned_bytes": 63,
    "elapsed_ms": 12,
    "rewritten_sql": "SELECT id, total FROM orders ORDER BY created_at DESC LIMIT 6"
  }
}

一次被拒绝的写操作

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "datanexa_execute_readonly_sql",
    "arguments": {
      "connection_id": "demo-mysql",
      "sql": "DELETE FROM orders WHERE id = 42"
    }
  }
}

{
  "policy": {
    "allowed": false,
    "reason": "只读策略已阻止 DDL、DML、破坏性语句和可能产生副作用的 SQL。",
    "rewritten_sql": null
  },
  "result": null
}

分析与策略：不读业务数据

这两个工具适合在开放查询能力之前先给 Agent 用：一个看执行计划，一个只做静态预检。

只读策略会拦下什么

凡是让 Agent 自己写 SQL 的入口，都走同一套策略引擎：执行只读查询、解释 SQL，以及在执行前做静态预检。引擎先按方言把语句解析成语法树，再逐条检查，判断依据是语句结构而不是字符串匹配，所以注释或字符串字面量里出现的关键词不会造成误判。用结构化参数传表名的工具不经过这套解析，它们只拼出一条固定的 SELECT，并按标识符白名单校验表名。

放行之后还有三层限制：最外层行数会被收紧到 max_rows + 1，多取的一行只用于判断是否截断；结果超过连接允许的字节数时同样标记 truncated，并可能返回被截断的单元格；查询超过时限会中止并记为「超时」。这些都在结果对象里如实反映，Agent 不应该拿截断结果推断总量。

工具开关、令牌权限与 JDBC 差异

工具开关是全局的：关闭后，tools/list 不再返回该工具，直接调用会收到「工具已关闭」的错误。它适合长期限制 Agent 能做什么。

如果开了 Bearer 鉴权，还可以在「访问控制」里为每个令牌单独勾选数据库与工具。令牌没被授权的工具，调用会返回「未授权给该访问令牌」，与全局关闭的报错不同，便于在审计里区分。

JDBC 连接的能力取决于驱动：datanexa_list_connections 返回的 capabilities 会列出该连接支持与不支持的工具。不要假设所有连接都能采样行或解释查询。

实践建议：始终保留 datanexa_list_connections 与 datanexa_get_schema；datanexa_sample_rows 按需开放；datanexa_execute_readonly_sql 只给确实需要自由查询的 Agent，并配合最小权限令牌。

查看审计日志#

把数据库交给 Agent 之后，最想知道的是它到底做了什么。审计日志按时间记录每一次工具调用：谁发起的、查了哪个库、执行了什么 SQL、结果如何。

记录了什么

每次工具调用都会写入本地 SQLite，包括成功、被策略拒绝、超时、结果被截断与执行出错。服务启动等系统动作也会记录，来源显示为「系统」。审计写入失败会直接让调用失败，不会出现「执行了但没有记录」的情况。

一条记录包含：时间、令牌、工具、连接、状态、原因、耗时、返回行数与 SQL 文本。SQL 会保存实际执行的版本（策略改写后的 SQL），因此你能看到行数限制是怎么加上去的。

列表与筛选

列表按时间倒序展示「时间、令牌、工具、连接、状态、详情」六列。详情列显示简短原因或「{rows} 行 / {elapsed}ms」，一眼能看出哪些调用没有返回数据。

右上角「筛选」支持开始日期、结束日期、工具、连接、状态与令牌六个条件，可组合使用；「清除筛选」恢复全量。列表每页 50 条，单次最多加载 5000 条，超出后请用筛选或时间范围缩小范围。

截图占位 · 15 15-audit-list.png 审计列表：多行记录、状态徽标、时间/工具/连接列与「筛选」入口。 建议 1600 × 1000 · PNG · 浅色主题

详情：一次调用到底发生了什么

点击任意一行打开「日志详情」，可以看到完整令牌、工具、连接、状态、耗时与行数；被拒绝或出错时还有「原因」，SQL 区域保留可复制的原始语句。

SQL 文本最多保存 20000 个字符，超出会被截断并标注；原因最多保留 500 个字符。需要完整 SQL 时，应在调用方或调试日志里另行留存。

截图占位 · 16 16-audit-detail.png 日志详情弹窗：令牌、工具、连接、状态、耗时/行数、原因与 SQL。 建议 1200 × 900 · PNG · 浅色主题

脱敏与保留

SQL 字面量脱敏默认关闭，日志会按原样保存语句。开启后，字符串、数字等字面量会被统一替换为 REDACTED，结构、表名与函数名保留，仍然可以判断语句类型。

开启脱敏后，解析失败的语句记为 [SQL REDACTED: PARSE FAILED]，方言无法识别的记为 [SQL REDACTED: DIALECT UNKNOWN]，不会退回到明文保存。

保留天数默认 7 天，可选 3、7、15、30 天。每次写入新记录时，应用会顺手删除早于截止时间的记录，所以日志不会无限增长；修改保留天数不会找回已删除的历史。

审计页的「清理日志」用于手动清空全部记录，通常在交接或排障后使用，操作前请确认不再需要这些证据。审计库与配置在同一目录，备份时不要只拷 config.toml。

三种拦截来源

「拒绝」状态可能来自三个完全不同的地方。看原因文案就能区分，处理方式也不同。

启动服务、自动启动 MCP 与熔断动作本身也会留下系统记录，令牌列显示「系统」。排查「令牌为什么突然失效」时，先找那条自动熔断记录，再回看它之前的拒绝记录。

用审计排查问题

设置项说明#

设置页决定 DataNexa 怎样运行：服务开不开、Agent 手里有多少权限、日志留多久、驱动与运行时放在哪里。下面按 5 个标签页说明每组选项改的是什么、会影响哪些地方，以及什么时候需要改。

通用：服务策略、显示、启动、审计、导入导出

通用分 5 组。第一组直接影响 MCP 服务本身，后面几组影响本机体验与数据留存；每组的改动范围各不相同，改之前先对照下表。

• 监听地址与端口：端口输入框接受 1–65535，越界的取值会被夹回范围；监听地址只接受 127.0.0.1 或 localhost。
• 启动与后台：勾选「登录时启动 DataNexa」后，「启动 DataNexa 时自动开启 MCP 服务」会自动打开并锁定，因为开机自启动后，服务会随登录一起常驻。
• 轻量模式：开启后，窗口关闭 5 分钟会自动释放窗口界面资源，后台 MCP 服务与已建连接不受影响。
• 审计日志：保留天数可选 3 / 7 / 15 / 30 天；「脱敏 SQL 字面量」默认关闭，关闭时 SQL 里的字符串与数字原样写入，打开后字面量统一替换为占位符；解析失败或方言未知时，整条 SQL 会被替换为对应的 REDACTED 标记，不会回退到明文。

截图占位 · 17 17-settings-general.png 画面内容：设置 → 通用，可见 MCP 服务策略、显示、启动与后台、审计日志、导入/导出五个分组。 建议 1600 × 1000 · PNG · 浅色主题

安全：拦截统计、六层防护、自动熔断

安全标签页是一块仪表盘，不是开关面板：顶部数字是过去 24 小时内被拒绝的数据库操作数，取自界面已加载的审计记录（最多 5000 条，达到上限会显示加号提示实际次数可能更多）。两个按钮分别打开「策略检查台」和「审计日志」。这一页只有熔断参数可以改，其余各层由程序固定。

• 六层防护：L1 网络、L2 认证、L3 语法、L4 数据库、L5 资源、L6 审计。只有 L2 会随 Bearer 开关变化，关闭时标题变成「全链路数据安全防护未完全启用」，并标出「未启用」。
• 自动熔断：同一令牌在统计窗口（1/5/10/30/60 分钟，默认 10）内被拒次数达到阈值（3/5/10/20/50 次，默认 5）就自动停用并写一条审计。调用量大、Agent 常写错 SQL 时可以把阈值调高；Bearer 未开启时整组不可用。
• 策略检查台：只做静态预检，选 MySQL / PostgreSQL / SQLite 方言，得到「允许执行」或「已拒绝」、原因，必要时还有改写后的 SQL。它不连接真实数据库，也不写审计日志。

六层防护各自的机制、能挡什么、挡不住什么，见安全模型；令牌被熔断后如何恢复，见访问控制；拦截记录怎么筛，见审计日志。

截图占位 · 18 18-settings-security.png 画面内容：设置 → 安全，24 小时拦截统计、六层防护列表与熔断设置。 建议 1600 × 1000 · PNG · 深色主题

JDBC 支持：只在这里管运行时与驱动

这个标签页带「预览」徽标，负责 Java 运行时与驱动 Bundle 两件事。新建 JDBC 连接、填 Driver Class、拼 JDBC URL 以及排错都在JDBC 支持一章，这里只说它与设置的关系；只有在需要连接原生不支持的数据库时，才需要进这一页。

• Java 运行时：显示是否可用、版本与来源（DataNexa 下载或外部）。可以下载托管运行时、检查更新、选择外部运行时、切回托管或卸载托管运行时；卸载只删除 DataNexa 下载的那一份，外部运行时不受影响。
• JDBC 驱动：按 Maven 坐标安装，或导入本地 JAR。列表显示 Driver Class、体积与两项「驱动原生支持」标识（只读限制、超时限制）；未探测时显示「测试连接后检测」，执行一次测试连接或 MCP 查询后才会记录结果。
• 保证与风险：底部固定写明「无论驱动原生能力如何，DataNexa 的只读保护与超时兜底始终生效」，旁边可展开风险详情，列出方言解析与资源消耗方面的限制。

存储与性能：磁盘、缓存与资源

顶部两张卡片切换视图：空间占用看磁盘，资源监控看 CPU 与内存。数据每 5 秒自动刷新一次，不需要手动点刷新。磁盘吃紧、或怀疑某次查询把内存吃满时，先来这里看。

• 空间占用：给出总大小、占比条与逐项明细（Java 运行时、JDBC 驱动、Maven 仓库、审计与日志、访问控制、配置文件、调试日志、其他文件），每项都标出真实路径。
• 释放空间：只清理 Maven 下载缓存和调试日志；已安装驱动、审计日志与配置不受影响。没有可清理项时，弹窗会直接说明。
• 资源监控：总 CPU 与内存按 DataNexa、JDBC 驱动、系统其他占用拆分；下面按进程列出 PID、CPU 与内存，驱动运行时状态异常或卡住时可以「停止运行时」。
• 打开数据目录：在文件管理器里打开 DataNexa 的数据目录，明细里的路径可以在这里逐一核对。

关于：版本、更新与调试入口

版本号、更新通道与应用入口都集中在这个面板，页脚放官方主页与 GitHub 项目页。版本对不上、或要反馈问题时，从这里取信息。

• 更新：可手动检查；有新版本时能看更新说明或立即更新。本地编译版本不显示更新日志链接，只提供 Releases 入口。
• 更新偏好：「每天自动检查更新」默认开启；「更新下载加速」由 GH-Proxy 提供，开启后检查更新、下载安装包与 Java 运行时都经该服务访问 GitHub，只转发公开的 Release 文件，安装包与运行时仍会校验签名与 SHA-256。
• 调试日志：默认隐藏，连续点 5 次版本号才会出现。开启前会弹出确认框（仅用于排查问题、有轻微性能开销、内容已脱敏），开启后可按旁边的按钮直接打开日志文件夹。

它防什么，不防什么#

这一章把 DataNexa 的防护拆成可以逐条核对的清单：假设了什么前提、每一道防护各挡什么、哪些风险留在防护之外，以及凭据到底放在哪里。看完你应该能判断自己的部署还差哪一层。

威胁模型：三个前提

DataNexa 的假设很具体：本机的操作系统与登录账户可信，安装包没有被替换，数据库账号由你在连接里配置。在这些前提下，它要保证的是「Agent 提议的操作在到达数据库之前被检查」。

它不假设 Agent 一定有恶意，但即使 Agent 有 bug 或被诱导，也只能拿到你授权的那些数据库与工具。

六层防护，再加两道令牌闸门

下面的顺序就是一次调用的实际经历：先过网络与认证，再过语法与数据库，最后被资源限额和审计收尾。前六行与设置页「安全」标签里的 L1–L6 一一对应，最后两行是令牌自带的两道闸门。任何一层拒绝，调用都不会继续往下走。

能防与不能防

凭据与数据放在哪里

「设置 → 存储与性能」会为每个存储项列出实际路径。下表说明各自存了什么、靠什么保护。

导出连接与紧急断连的操作见数据库连接；令牌的权限勾选、轮换与恢复见访问控制。

JDBC 的额外风险

JDBC 是唯一能连接 DataNexa 没有原生支持的数据库的通道，代价是防护从结构化的语法规则退化为有限判断。

• 驱动及其依赖以本地 Java 代码运行，与你同权限，安装即等于信任。
• 未知方言下，只读策略可能只能做有限的检查，无法保证识别所有写入或其他副作用。
• 部分数据库能力不可用；复杂查询即使结果被截断，也可能已在数据库侧消耗资源。

建议这样配置

1. 给 DataNexa 单独建只读账号，只授 SELECT 与读取元数据所需的权限。
2. 保持「要求 Bearer 密钥」开启，一个 Agent 一个令牌。
3. 只勾选该 Agent 真正需要的数据库连接与工具，不要一律全开。
4. 开启自动熔断，并按调用量调整统计窗口与阈值。
5. 审计保留期选得比排查周期长；需要把日志交给别人看时，打开 SQL 字面量脱敏。
6. 能走原生连接就不走 JDBC；确实要用时，只用可信来源、版本明确的驱动。
7. 不再需要 MCP 服务时，在概览页停止它，不要让端口长期可用。

边界声明

换个说法：DataNexa 把「Agent 直接连数据库」变成「Agent 通过一个会检查、会限流、会记账的网关连数据库」，但它不改变数据库账号本身的权限。

需要更强保证时，请在数据库侧收紧权限与网络访问，而不是只依赖 DataNexa。发现可疑记录，先从审计日志找到那次调用，再到访问控制核对该令牌的权限是否合理。

常见问题#

这一章按「症状 → 原因 → 处理」整理排错路径。多数问题在概览页状态、审计日志和调试日志里就能定位，不需要重装。

应用打不开，或 MCP 服务起不来

症状：双击图标没有窗口；或窗口打开了，但概览页服务状态一直是「启动失败」，托盘菜单提醒「MCP 服务启动失败」。

原因：通常是端口被其他程序占用，或者 config.toml 被手工改坏、无法通过配置校验。

1. 把指针停在概览页服务状态上读取原始错误；端口冲突一般带有 Address already in use。
2. 换一个端口：设置 → 通用 → MCP 服务策略 → 端口，保存后回到概览页点「启动服务」。端口范围 1–65535，监听地址只能是 127.0.0.1 或 localhost。
3. 仍然打不开时，退出应用，把 config.toml 改名备份后重新启动，应用会写回默认配置；连接需要重新添加，数据库密码仍保存在系统凭证库中。
4. 如果开启开机自启动时提示登录项注册失败，macOS 需要应用已签名并从 .app 中运行；签名与系统权限问题只能由安装方式解决。

Agent 连不上，或收到 401 / 403

症状：Agent 报连接被拒绝、请求超时，或返回 401、403。

原因：服务没有运行；客户端填的端口与实际监听端口不一致；Bearer 鉴权开启但请求没带密钥，或密钥在「手动轮换」后已失效；访问令牌被停用或自动熔断；请求的 Host / Origin 不是本机地址。

1. 在概览页确认状态是「运行中」，端点形如 http://127.0.0.1:17321/mcp；需要核对时以「设置 → 通用 → MCP 服务策略」里的监听地址与端口为准。
2. 401 表示缺少或无效的 Bearer 密钥：在客户端配置 Authorization: Bearer <token>，密钥可到「访问控制」用该令牌的「复制 Agent Prompt」重新取回；轮换后所有客户端都要同步更新。
3. 403 表示 Host 或 Origin 不被允许：请求必须使用 127.0.0.1 / localhost，经反向代理或局域网地址访问会被拒绝。
4. 客户端需要 POST JSON-RPC，Content-Type: application/json，Accept 同时包含 application/json 与 text/event-stream；GET 返回 405 属正常，说明该端点不提供流式 GET。

查询被拒绝

症状：Agent 报告语句被拒绝，例如「只读策略已阻止 DDL、DML、破坏性语句和可能产生副作用的 SQL。」或「每次工具调用只允许一条 SQL 语句。」

原因：语句不是单条只读查询；工具或数据库连接不在该令牌的权限内；工具在工具页被关闭；紧急断连正在生效。

1. 改成单条 SELECT、安全的 WITH ... SELECT 或 EXPLAIN；不要拼接多条语句，SELECT INTO、文件导入导出和明显有副作用的函数都会被拦。
2. 先用「设置 → 安全 → 策略检查台」以相同方言预检，确认是策略问题还是权限问题。
3. 到「访问控制」核对该令牌的数据库与工具权限；提示会区分「工具未授权」与「连接未授权」。
4. 到「工具」页确认工具开关；被关闭的工具不会出现在 Agent 的工具列表里。
5. 若提示紧急断连生效，先在「数据库连接」页顶部或概览页服务状态卡退出紧急断连，再让 Agent 重试。

查询超时，或结果被截断

症状：审计记录状态为「超时」或「截断」；提示「查询超过 8000ms 超时上限。该连接已丢弃，下次调用会重新建立连接。」

原因：连接默认限制为查询超时 8000ms、最大返回行数 500、单次结果上限 1 MiB。扫描大表或返回大字段时，会先撞上其中一个上限。

1. 缩小范围：加过滤条件、只取需要的列、先聚合再取数，比直接放宽限额更有效。
2. 在连接编辑里调整「查询超时毫秒」与「最大返回行数」（上限 60000ms、5000 行），需要时再放宽「最大结果大小」。
3. 返回结果里 truncated 为 true 时不完整，不要用它推断总行数或做全量统计。
4. 超时后连接会被丢弃，下一次调用会自动重连，不需要重启服务或重新保存连接。

SQLite 数据库打不开

症状：「测试连接」失败，提示无法打开数据库或只读打开失败。

原因：SQLite 连接以只读方式打开文件。路径不对、文件不存在、当前系统账号没有读权限，或文件被其他程序独占时都会失败。

1. 在连接编辑里确认「数据库文件」是完整路径，包含文件名与后缀，不要只填目录。
2. 确认运行 DataNexa 的系统账号对文件有读权限，对文件所在目录有读写权限。
3. 关闭可能持有写锁的客户端或同步工具后重试；把库文件放在同步盘、网络盘上也容易出现锁冲突。
4. 加密或专有格式的库文件不能直接连接，需要先在原工具里导出为普通 SQLite 文件。

MySQL 时间显示不对

症状：时间字段的值与在 MySQL 客户端里看到的结果差几个小时。

原因：DataNexa 把时间类型的值统一按 UTC 返回。MySQL 的 TIMESTAMP 会按会话时区转换，DATETIME 不转换，服务器时区、会话时区与读取端理解不一致时就会产生偏移。

1. 在 Agent 侧按 UTC 解读返回值，再在展示层转成本地时区，不要直接当成本地时间使用。
2. 需要本地时间时在 SQL 里显式转换（例如 CONVERT_TZ），不要依赖连接默认时区。
3. 对照服务器的 time_zone 与会话时区，确认写入时用的是哪一套规则，再判断是读取问题还是存储问题。

JDBC 驱动装不上

症状：安装驱动失败，提示「Maven 坐标必须使用 groupId:artifactId:version 格式」「Maven 完成后没有生成 JDBC 驱动 JAR 文件」或「已安装的 Bundle 未提供任何 JDBC Driver 实现」。

原因：坐标写错或版本不存在；镜像源不可达、不是 HTTPS；驱动 JAR 里没有 java.sql.Driver 实现；本地导入时只选了驱动 JAR，没有带上运行时依赖。

1. 按 groupId:artifactId:version 填写坐标，先在 Maven Central 确认该版本存在。
2. 换一个可访问的 HTTPS 镜像源，或改用「导入本地驱动」。
3. 本地导入时把驱动 JAR 及其依赖一起选中；安装后仍未发现 Driver Class 的，在连接里手工填写 Driver Class。
4. 删除驱动前先删除或改用引用它的连接，仍被连接引用的驱动无法删除。

缺少 Java 运行时

症状：使用 JDBC 连接时报「DataNexa Java 运行时尚未安装。请下载或选择外部 Java 运行时。」或「选定的外部 Java 运行时不可用。」

原因：安装包不内置 Java 运行时；选择的外部运行时被移动或删除；托管运行时下载后校验失败。

1. 打开 设置 → JDBC 支持，点「下载 DataNexa Java 运行时」，完成后重试 JDBC 连接。
2. 本机已有 JDK 时，用「选择外部 Java 运行时」指向它的主目录；更换后原连接不需要重建。
3. 下载慢或中断时，可开启「设置 → 关于 → 更新下载加速」重试；仍失败时手动安装 JDK 再选择外部运行时。
4. JDBC 会话运行期间不能卸载运行时，先停止相关会话再卸载。

审计日志没有记录

症状：审计页一直显示「暂无访问记录。」

原因：没有发生真正的工具调用；筛选条件把已有记录过滤掉了；记录已超过保留天数被自动清理；审计存储迁移未完成时 MCP 服务不会启动。

1. 先清除筛选条件：时间范围、工具、连接、状态或令牌都可能把记录过滤掉。
2. 让 Agent 调用一次 datanexa_list_connections 或执行一条只读查询，再刷新审计页。
3. 确认「设置 → 通用 → 审计日志 → 日志保留天数」；默认 7 天，可选 3、7、15、30 天。
4. 若提示审计日志迁移失败，按提示重试；旧日志确认不再需要时，可选择隔离旧日志并继续。
5. datanexa_policy_check 也会留下审计记录；如果连它都没有，说明请求没有到达服务端，先检查服务状态与鉴权。

语言或主题没有生效

症状：切换界面语言或主题后界面没有变化，重启后又变回原样。

原因：语言默认跟随系统，只有主动选择才会写入配置；主题不写入 config.toml，由界面本地保存；语言只接受 zh-CN 与 en 两个值。

1. 语言有两个入口：概览页顶部的语言按钮，或「设置 → 通用 → 显示 → 界面语言」。
2. 中文系统默认中文，其他语言默认英文；修改系统语言后需要重启应用才会跟随。
3. 主题在「设置 → 通用 → 显示 → 主题」里切换「跟随系统 / 浅色 / 深色」，保存后立即生效；未生效时重启应用再看。
4. 手工编辑配置时，language 只能写 zh-CN 或 en，其他值会被清空并回退到系统语言。

数据目录、重置与卸载残留

症状：想备份或彻底重置配置；或卸载重装后，旧连接、旧审计记录仍然存在。

原因：配置、审计与访问控制数据库在配置目录，驱动、Maven 缓存、Java 运行时与调试日志在数据目录。卸载程序不会删除这些目录，也不会清理系统凭证库。

1. 打开目录：设置 → 存储与性能 → 打开数据目录；具体路径见第 13 章，macOS 与 Windows 上配置目录和数据目录是同一个文件夹。
2. 备份优先用「导入/导出 → 导出连接」；导出文件包含明文密码，用完及时删除。
3. 彻底重置：退出应用后重命名或删除 config.toml、audit.db、access-control.db 再启动，应用会重建默认配置；连接和审计记录会丢失，密码仍留在系统凭证库。
4. 卸载后要清理干净，删除上述目录，并在系统「钥匙串访问」或「凭据管理器」中删除 com.mingo.datanexa 条目。

如何反馈问题

症状：以上路径都试过仍然失败，或界面给出的错误无法判断原因。这时请带上可复现的信息一起反馈。

1. 在 GitHub Issues 提交，写清复现步骤、期望结果和实际结果。
2. 附上环境信息：操作系统、数据库类型与版本；涉及 JDBC 时补充驱动名称与版本。
3. 附调试日志：设置 → 关于连续点按版本号区域 5 次开启「启用调试日志」，复现问题后在设置中打开日志文件夹取文件。
4. 提交前移除连接字符串、数据库名、账号、Token、SQL 字面量和业务数据；安全问题不要发公开 Issue。

附录#

这一章把散落在各章的查表信息集中起来：文件位置、配置示例、默认值、工具名、术语与链接。排错时可以把它当作对照表使用。

文件与目录位置

配置、审计与访问控制数据库放在配置目录，驱动、Maven 缓存、Java 运行时与调试日志放在数据目录。macOS 与 Windows 上两者是同一个文件夹。应用内的「设置 → 存储与性能 → 打开数据目录」直接打开数据目录。

配置文件示例

下面是 config.toml 的等价示例，字段与默认值来自应用本身。密码不会写入该文件，连接只保存一个指向系统凭证库的引用。修改前请先退出应用，改坏后应用可能无法启动。

version = 1

[server]
host = "127.0.0.1"
port = 17321
require_token = true

[settings]
audit_retention_days = 7
audit_redact_sql_literals = false
auto_check_updates = true
github_acceleration = false
auto_start_mcp = false
auto_run_mcp = false
auto_lightweight_mode = false
mcp_activity_effects = true
language = ""
auto_circuit_breaker = false
auto_circuit_breaker_window_minutes = 10
auto_circuit_breaker_threshold = 5
debug_logging_enabled = false

[[connections]]
id = "local_data"
name = "Local Data"
type = "sqlite"
enabled = true
database = "/Users/you/data/local.db"
max_rows = 500
query_timeout_ms = 8000
max_connections = 1
max_result_bytes = 1048576

默认值速查

工具名速查

七个工具分三组；工具名需要在客户端或提示词里精确引用，区分大小写。关闭的工具不会出现在 Agent 的工具列表里，详细参数见第 08 章。

术语表

MCP 协议支持

支持 2025-03-26、2025-06-18、2025-11-25 三个协议版本；客户端不发送版本头时，按 2025-03-26 处理。

相关链接