数据管理 DMS：从 DMS MCP 升级到 Agent 数据网关 MCP

同步 DMS 数据源

使用新版 MCP 前，需要先将相关 DMS 数据源同步到 Agent 数据网关。DMS 计划于 2026 年 11 月 30 日前将相关存量数据源自动同步至 Agent 数据网关。如需在该日期之前使用新版MCP，请按以下步骤手动同步 DMS 数据源：

1. 登录Agent 数据网关控制台。

2. 在左侧导航栏选择数据源 > 连接管理。

3. 在连接管理页面，点击DMS 实例同步。

   说明

   您也可以在Agent 数据网关控制台的概览页中单击快速开始，然后在选择数据源区域点击DMS 数据源同步。

4. 从已托管在 DMS 的实例中选择需要使用的数据源并完成同步。当前仅支持同步已安全托管的 DMS 实例。

创建 Agent 身份

在接入使用 MCP 前，按照以下步骤创建 Agent 身份：

1. 登录Agent 数据网关控制台。

2. 在左侧导航栏，选择身份与权限 > 我的Agent身份，然后点击创建Agent身份。

3. 在弹出的对话框中，设置以下 Agent 身份参数，然后点击提交：

   参数	说明
   名称	输入 Agent 身份的名称。
   AccessToken到期时间	设置 Agent Access Token 的过期时间。空值表示永不过期。
   权限模式	选择 Agent 身份的权限模式： 权限跟随用户：Agent 实时继承当前用户权限。 权限收窄模式：在用户权限内按需勾选 Agent 的权限。 独立权限：Agent 不继承当前用户权限，创建后通过权限申请获得数据权限。

4. 在对话框内，复制并妥善保存生成的 Access Token，然后点击关闭。该 Access Token 仅在创建时展示一次，关闭后将无法再次查看。

接入 Agent 数据网关 MCP

完成数据源同步后，您可以通过以下方式接入新版 MCP。

替换 MCP Tool

接入新版 MCP 后，您需要在应用中将旧版的 MCP Tool 替换为新版。下表中列出旧版 DMS MCP 的主要 Tool 与新版 MCP 中 Tool 的映射关系与说明。请参照

新版资源发现链路统一为：

catalogUuid
  → databaseUuid
    → table qualifiedName
      → 字段、索引或 SQL 执行

Agent 升级

您可以将以下内容加入 Agent 的系统提示词或升级提示词，帮助 Agent 平滑升级到新版 MCP：

你正在使用 Agent 数据网关 MCP。请遵循以下调用规则：

1. 不再调用 executeScript、getDatabase、getInstance、
   getTableDetailInfo、listTables、searchDatabase 等旧 DMS MCP Tool。

2. 旧版 instance 在新版中称为 catalog：
   使用 meta_catalog_search 定位实例，取得 catalogUuid；
   需要详情时调用 meta_catalog_get。

3. 查询数据库时：
   - 已知 catalogUuid：调用 meta_database_list；
   - 只知道数据库名称：调用 meta_database_search；
   - 取得 databaseUuid 后，调用 meta_database_get 查询详情。

4. 查询表时，使用 meta_table_list，并保存返回的 qualifiedName。
   查询完整表详情时，分别调用 meta_table_columns 和
   meta_table_indexes。

5. 执行 SQL 时使用 exec_sql：
   - 优先传入 databaseUuid；
   - 每次只能提交一条 SQL 或 statement；
   - 多条 SQL 必须按顺序拆成多次调用；
   - 任意一条失败时停止后续调用并报告失败；
   - 不得声称多次调用具有事务原子性或会自动回滚。

6. exec_sql 返回 NEEDS_CONFIRMATION 时，必须先由用户审查，
   再携带 confirm 理由重试；不得默认跳过确认。

7. 列表工具采用 NextToken 游标分页。hasMore=true 时，
   原样携带返回的 NextToken 获取下一页，不再使用旧页码分页。

8. 数据源可见不代表具备执行权限。遇到 ACCESS_DENIED 时，
   提醒用户检查 Agent 身份和实例授权，不要反复重试 SQL。

替换executeScript的注意事项

旧版 executeScript 在物理数据库场景可以接收多条 SQL 并依次执行，但不保证整个脚本的事务原子性；逻辑数据库场景最多只允许一条 SQL。新版 exec_sql 当前只支持单个 SQL 或 statement，不支持批量多语句。迁移时应遵循以下规则：

• 将多条 SQL 拆成多次 exec_sql 调用。

• 按原脚本顺序逐条执行。

• 任意一条失败时停止后续调用并报告失败。

• 不得声称多次调用会自动回滚或具有事务原子性。

• 命中 NEEDS_CONFIRMATION 时，必须经过人工审查，再携带 confirm 理由重试。

• 旧 logic 参数不映射为新版参数，目标资源由新版 databaseUuid 表达；尚未接入网关的逻辑库当前无法直接迁移。

单条 SQL 调用示例：

{
  "name": "exec_sql",
  "arguments": {
    "databaseUuid": "<database-uuid>",
    "statement": "SELECT id, status FROM orders LIMIT 20",
    "maxRows": 100,
    "waitSeconds": 110
  }
}

meta_table_list替换示例

旧版 getTableDetailInfo 由 meta_table_columns 和 meta_table_indexes 两次查询共同替代。先通过 meta_table_list 取得表的 qualifiedName，然后分别查询字段和索引：

{"name":"meta_table_columns","arguments":{"databaseUuid":"<database-uuid>","tableQualifiedName":"trade.orders"}}
{"name":"meta_table_indexes","arguments":{"databaseUuid":"<database-uuid>","tableQualifiedName":"trade.orders"}}

两次结果共同组成旧版 getTableDetailInfo 的业务结果。