Data Management:Upgrade from DMS MCP to Agent Data Gateway MCP

Synchronize DMS data sources

Before you use the new MCP, synchronize the relevant DMS data sources to Agent Data Gateway. DMS plans to automatically synchronize the relevant existing data sources to Agent Data Gateway before November 30, 2026. To use the new MCP before that date, manually synchronize the DMS data sources by performing the following steps:

1. Log on to the Agent Data Gateway console.

2. In the left-side navigation pane, choose Data Sources > Connection Management.

3. On the Connection Management page, click DMS Instance Sync.

   Note

   Alternatively, on the Overview page of the Agent Data Gateway console, click Get Started, and then click DMS data source sync in the Select Datasource section.

4. Select the data sources that you want to use from the instances that are hosted in DMS, and then complete the synchronization. Only DMS instances that are securely hosted can be synchronized.

Create an agent identity

Before you connect to and use the MCP, create an agent identity by performing the following steps:

1. Log on to the Agent Data Gateway console.

2. In the left-side navigation pane, choose Identities & Permissions > My Agent Identity, and then click Create Agent Identity.

3. In the dialog box that appears, configure the following agent identity parameters, and then click Submit:

   Parameter	Description
   Name	Enter a name for the agent identity.
   AccessToken Expiration Time	Set the expiration time of the agent access token. An empty value indicates that the token never expires.
   Permission Mode	Select the permission mode of the agent identity: Permissions Follow User: The agent inherits the current user permissions in real time. Permission Narrowing Mode: Select the agent permissions as needed within the scope of the user permissions. Independent permissions: The agent does not inherit the current user permissions. After the identity is created, the agent obtains data permissions through permission requests.

4. In the dialog box, copy and securely save the generated access token, and then click Close. The access token is displayed only once when it is created and cannot be viewed again after you close the dialog box.

Connect to Agent Data Gateway MCP

After you synchronize the data sources, connect to the new MCP by using the following methods.

Replace MCP tools

After you connect to the new MCP, replace the legacy MCP tools in your applications with the new ones. The following table lists the mapping and descriptions between the main legacy DMS MCP tools and the new MCP tools.

The resource discovery chain in the new version is unified as follows:

catalogUuid
  → databaseUuid
    → table qualifiedName
      → columns, indexes, or SQL execution

Agent upgrade

Add the following content to the system prompt or upgrade prompt of your agent to help it upgrade smoothly to the new MCP:

You are using Agent Data Gateway MCP. Follow these call rules:

1. Do not call legacy DMS MCP tools such as executeScript, getDatabase,
   getInstance, getTableDetailInfo, listTables, or searchDatabase.

2. The legacy instance is called a catalog in the new version:
   Use meta_catalog_search to locate the instance and obtain the catalogUuid;
   call meta_catalog_get when you need the details.

3. When you query databases:
   - If the catalogUuid is known, call meta_database_list;
   - If only the database name is known, call meta_database_search;
   - After you obtain the databaseUuid, call meta_database_get for the details.

4. When you query tables, use meta_table_list and save the returned qualifiedName.
   To query full table details, call meta_table_columns and
   meta_table_indexes separately.

5. When you execute SQL, use exec_sql:
   - Pass databaseUuid first;
   - Submit only one SQL statement per call;
   - Split multiple SQL statements into multiple sequential calls;
   - If any statement fails, stop the subsequent calls and report the failure;
   - Do not claim that multiple calls have transaction atomicity or are automatically rolled back.

6. When exec_sql returns NEEDS_CONFIRMATION, the user must review it first,
   and then retry with the confirm reason; do not skip confirmation by default.

7. List tools use NextToken cursor-based pagination. When hasMore=true,
   pass the returned NextToken as-is to get the next page instead of using legacy page-number pagination.

8. A visible data source does not mean that execution permission is granted. When ACCESS_DENIED occurs,
   remind the user to check the agent identity and instance authorization, and do not retry the SQL repeatedly.

Considerations for replacing executeScript

In physical database scenarios, the legacy executeScript can receive multiple SQL statements and execute them in sequence, but it does not guarantee transaction atomicity for the entire script. In logical database scenarios, only one SQL statement is allowed. The new exec_sql currently supports only a single SQL statement and does not support batch multi-statement execution. Follow these rules when you upgrade:

• Split multiple SQL statements into multiple exec_sql calls.

• Execute the statements one by one in the original script order.

• If any statement fails, stop the subsequent calls and report the failure.

• Do not claim that multiple calls are automatically rolled back or have transaction atomicity.

• When NEEDS_CONFIRMATION is returned, complete a manual review, and then retry with the confirm reason.

• The legacy logic parameter does not map to a new parameter. The target resource is expressed by the new databaseUuid. Logical databases that are not yet connected to the gateway cannot be upgraded directly.

Single SQL statement call example:

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

meta_table_list replacement example

The legacy getTableDetailInfo is replaced by two queries: meta_table_columns and meta_table_indexes. First obtain the qualifiedName of the table by using meta_table_list, and then query the columns and indexes separately:

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

The two results together constitute the business result of the legacy getTableDetailInfo.