使用MCP服务

功能概述

Agent 数据网关 MCP 服务基于 MCP（Model Context Protocol）Streamable HTTP 协议，把数据网关的核心能力开放给支持 MCP 的 AI 客户端（如 Qoder、Cursor、Codex、Claude Code、OpenCode）。配置完成后，AI 客户端中的 Agent 可以调用标准 MCP 工具完成数据资产发现、权限核对、知识检索和 SQL 执行等操作，全过程遵循数据网关既有的身份、权限、安全策略和审计约束。

MCP 服务具备以下特性：

• 传输协议：MCP Streamable HTTP。

• 身份认证：每个请求需携带 Authorization: Bearer <Access Token>。

• 权限边界：MCP 不扩大用户权限，调用继续执行数据网关的 ACL、安全策略和审计。

• 凭证处理：MCP 服务不保存用户的 Access Token。

准备工作

使用 MCP 服务前，请完成以下准备：

1. 登录Agent 数据网关控制台，开通服务并创建 Agent 身份。具体操作，请参见快速接入Agent数据网关。

2. 为该 Agent 身份授予需要访问的实例或数据权限。具体操作，请参见管理数据源和管理 Agent 身份与权限。

3. 获取对应地域（Region）的 Agent Access Token。

4. 选择与 Access Token 相同地域的 MCP Endpoint。

服务 Endpoint

MCP 服务按地域提供独立的 Endpoint。请根据 Access Token 所在地域选择对应的 Endpoint。当前正式环境支持以下地域：

配置 MCP 客户端

在 MCP 客户端的配置中加入以下内容，并将 Endpoint 与 Access Token 替换为您的正式环境信息：

{
  "mcpServers": {
    "dgate": {
      "url": "https://dgate-mcp-cn-hangzhou.aliyuncs.com/mcp/dgate",
      "headers": {
        "Authorization": "Bearer <ACCESS_TOKEN>"
      }
    }
  }
}

不同客户端的配置文件位置和界面入口可能不同，但核心配置只有两项：MCP URL 和 Authorization Header。保存后请重新加载 MCP 服务；部分客户端需要重启或新建会话才能刷新工具列表。

验证连接与权限

请检查 dgate MCP 是否可用，并按顺序执行：
1. 调用 acl_whoami，确认当前身份；
2. 调用 acl_my_permissions，列出当前真实数据权限；
3. 调用 meta_catalog_list，列出可见的数据实例；
4. 如果存在已授权数据库，调用 exec_sql 执行 SELECT 1；
5. 汇总每一步的状态；失败时给出 errorCode、errorMessage 和 requestId，不要输出 Access Token。

curl -sS -X POST \
  'https://dgate-mcp-cn-hangzhou.aliyuncs.com/mcp/dgate' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

工具清单

当前正式服务注册 13 个 MCP 工具，按用途分为元数据、数据源、权限、知识、执行和扩展六类。

常用参数说明：

• 列表类工具使用 MaxResults 和 NextToken 分页。返回 pagination.hasMore=true 时，将 pagination.nextToken 原样传入下一次调用。

• meta_database_list 需要 CatalogUuid；meta_table_list 需要 DatabaseUuid。

• meta_table_columns 和 meta_table_indexes 需要 databaseUuid 与 tableQualifiedName。

• wiki_search 需要 wikiUuid 与 query。

• 使用 gateway_call 前，请先调用 gateway_describe 查看 Action、参数以及是否属于写操作。

执行 SQL 或命令

exec_sql 每次只执行一条 statement。调用时至少通过以下一种方式指定目标：

• databaseUuid。

• catalogUuid，可配合 qualifiedName 指定数据库或 schema。

• catalogName，可配合 qualifiedName 指定数据库或 schema。

常用可选参数包括 timeout、maxRows、columnTruncate 和 waitSeconds。建议先执行带 LIMIT 的只读语句，并逐步缩小查询范围。

返回结果与常见状态

业务工具返回结构化结果，其中 requestId 是排障时定位链路的重要信息。列表类工具通过 pagination 字段表示是否还有下一页。

exec_sql 的常见执行状态如下：

权限及安全

常见问题

以下是使用MCP服务过程中常见的问题及对应处理方式。如未包含您遇到的问题，可以进行问题反馈。

提交问题时，请提供发生时间、地域、MCP 工具名、脱敏后的参数、errorCode、errorMessage 和 requestId，请勿提供完整的 Access Token。