MaxCompute MCP 服务使用文档

核心能力

• Catalog元数据浏览与搜索：按项目、Schema、表、字段、分区层级浏览，支持自然语言搜索。

• 表管理与元数据维护：创建表（支持生命周期、主键、部分列更新等选项）、插入少量数据、更新表注释/标签/列描述。

• 身份与权限检查：查看当前账号身份，并结合 MaxCompute 授权信息排查访问问题。

• 认证与授权：

  • Remote MCP 使用阿里云 OAuth 授权；

  • Local MCP 支持 AK/SK、STS、Credentials URI、ECS RAM Role 以及阿里云默认凭证链。

• 服务端客户端注册（Client ID Metadata Documents，CIMD）：

  已启用该能力的环境支持服务端或自托管客户端以 HTTPS 元数据文档 URL 作为 client_id，跳过动态客户端注册（Dynamic Client Registration，DCR），但仍需在登录后的授权确认页明确同意。详见配置服务端客户端（Client ID Metadata Documents）。

• SQL分析与执行：

  支持语句校验、扫描数据量和计算单元（Compute Unit，CU）用量预估、只读或写入 SQL 执行、实例状态查询及结果读取。写入 SQL 和元数据变更需要用户确认。

• 智能分析：

  根据自然语言生成只读 SQL 草稿、诊断作业问题、分析计算配额（Quota）的使用情况，并在结果中说明证据范围和处理建议。

• 表元数据分析：

  检查表结构和分区元数据，不扫描表数据。

• SemanticSpec 管理：

  创建和维护用于描述数据语义的 SemanticSpec 草稿、查看已发布版本，并通过语义发现 DataScan 生成和应用建议。

• 知识库搜索与问答：

  Remote MCP 内置 MaxCompute 文档知识库，支持关键词搜索和自然语言问答，返回带引用的回答。

• Skill 发现与读取：Remote MCP 内置 MCP Skill 资源，客户端可通过 tools/list 发现并读取 Skill 内容，用于 Information Schema 语义分析、反馈指引等场景。

• Information Schema 运维与治理分析：

  • Remote MCP 已内置 Information Schema 语义包；

  • Local MCP 需要额外安装对应 Skill。

• 多语言工具信息：Remote MCP 在 tools/list 中提供简体中文、繁体中文和英文的工具标题及简介，并单独标记工具是否依赖模型。

架构概览

MCMCP采用分层架构设计，从上到下分为以下层级：

• 用户Agent生态：支持 Claude Code、Codex、Qwen Code、Cursor、Qoder 等 MCP 客户端接入。

• MaxCompute Skills集合：Agent 可以结合语义包、常用命令、开发模板和使用限制完成更复杂的任务。

• MCMCP服务：把 MaxCompute OpenAPI、StorageAPI、CatalogAPI 等能力封装成 MCP 工具。

• MaxCompute底层能力：覆盖 Metadata、Compute Engines 和 Storage 等产品能力。

工具列表显示信息

• 多语言工具显示信息

  Remote MCP 在 tools/list 的每个工具对象中提供面向用户界面的多语言显示信息。支持该扩展的客户端可读取 _meta["com.aliyun.maxcompute/display"]，按界面语言显示简体中文（zh-CN）、繁体中文（zh-TW）或英文（en）标题和简介。

  客户端应以每次 tools/list 返回的工具集合为准，不维护独立的工具清单。所选语言缺失或扩展版本不受支持时，回退到标准 title、name 和 description 字段。需要显示模型依赖标识时，仅在 _meta["com.aliyun.maxcompute/model_backed"] 为 true 时标记为依赖 MaxAgent。显示信息仅用于界面呈现，不能作为权限、计费或调用安全判断的依据。

• 智能分析能力

  自然语言 SQL、作业诊断和配额分析是 Remote MCP 的三项智能分析工具，均为只读：不会自动执行生成的 SQL，不会重跑或取消作业，也不会修改配额容量和调度配置。

  模型分析可能消耗 MaxAgent Credits，一次工具调用可能触发多次模型调用。当模型能力或所需证据不可用时，工具可能返回 partial 结果，应结合 warnings 和 missing_evidence 判断可用结论。

智能分析工具使用前准备

使用上述三个工具前，请确认以下条件：

• MCP 客户端已通过浏览器 OAuth 或本地启动器连接 Remote MCP。

• 当前认证身份具有目标 MaxCompute 项目、作业或配额的相应访问权限。

• 请求中的 region 与目标资源所在地域一致。

• 使用 MaxAgent 模型能力时，当前身份在所选地域具有有效的 MaxAgent 配额和充足的 Credits。

• 使用 Generate SQL 查询租户元数据或历史作业时，当前身份满足相应的Information Schema 要求访问条件。

• 如需配额历史容量利用率或作业消耗数据，当前服务地域需支持相应的历史观测能力。

通常只需在对话中说明目标，由 Agent 选择工具并填写参数；也可以按照本文的 JSON 示例直接调用 MCP 工具。

智能分析工具结果说明

三个工具都返回 MCP 结构化结果。重点关注以下字段：

• ok：工具调用协议是否正常完成。ok=true 不代表证据一定完整。

• data：SQL 草稿、诊断结果、配额观测结果等业务数据。

• meta.outcome 或 metadata.outcome：业务结果状态。

• warnings：非致命限制或降级说明。

• missing_evidence：未取得的证据及原因。

• usage：模型调用次数及模型报告的 Token 用量。

常见 outcome：

不要把 partial 当作“接口调用失败”。应根据 missing_evidence 判断当前结论能回答哪些问题，以及是否需要补充权限、范围或进一步诊断。排障时不要复制认证信息或完整后端响应。

生成 SQL

在 cn-shanghai 的 sales_dw.dwd 中，生成一条 SQL，统计最近 30 天各渠道的支付订单数和支付金额，
按支付金额降序排列。只生成并校验 SQL，先不要执行。

{
  "question": "统计最近 30 天各渠道的支付订单数和支付金额，按支付金额降序排列",
  "region": "cn-shanghai",
  "sources": [
    {
      "project": "sales_dw",
      "schema": "dwd"
    }
  ],
  "analysis_context": {
    "project": "sales_dw",
    "schema": "dwd"
  }
}

{
  "question": "找出每场比赛积分最高的车队，并统计赛季累计积分",
  "region": "cn-shanghai",
  "sources": [
    {
      "project": "analytics",
      "schema": "formula_1",
      "tables": ["constructors", "constructorresults", "races"]
    }
  ]
}

{
  "question": "查询最近 7 天 CU 消耗最高的 20 个作业，返回 Instance ID、项目、提交人和 CU 小时",
  "region": "cn-shanghai",
  "analysis_context": {
    "project": "<当前身份在该地域可创建查询 Instance 的 project>"
  }
}

作业诊断

{
  "instance_id": "<INSTANCE_ID>",
  "project": "sales_dw",
  "region": "cn-shanghai",
  "depth": "standard"
}

诊断 sales_dw 中的作业 <INSTANCE_ID>。先判断失败阶段和最可能原因，给出可执行的修复建议，
不要重跑或取消作业。

继续深挖这个作业。首轮结论还不能解释根因，请检查可用的失败 Worker 日志和阶段证据，
并区分已确认事实、推断和仍缺失的证据。

配额分析

{
  "region": "cn-shanghai",
  "quota_nickname": "team_etl_quota",
  "question": "分析最近 7 天 CPU 资源最高的 10 个作业，并说明可验证的异常信号"
}

分析 cn-shanghai 的 team_etl_quota。找出最近 7 天 CPU 消耗最高的作业；只有存在直接作业异常信号时才归因为异常作业，否则明确为原因未知。只给建议，不要修改配额或作业。

{
  "region": "cn-shanghai",
  "question": "比较最近 7 天有实际作业的计算配额，按作业 CPU 使用量排序；包年包月另列容量利用率，按量和 Spot 不计算容量百分比"
}

比较我在 cn-shanghai 最近 7 天有实际作业的计算配额，包括包年包月、按量付费和 Spot；
按作业 CPU 使用量排序并列出高消耗作业，只对包年包月配额补充容量利用率。

Information Schema 要求

Generate SQL 可以使用租户级 Information Schema 视图。配额分析的容量利用率和作业证据均不使用 Information Schema。Generate SQL 仅允许服务端白名单中的视图，例如：

• SYSTEM_CATALOG.INFORMATION_SCHEMA.TASKS

• SYSTEM_CATALOG.INFORMATION_SCHEMA.TASKS_HISTORY

Generate SQL 使用这些视图时需要满足以下条件：

1. 当前认证身份具有租户级 Information Schema 读取权限。主账号通常具备默认访问能力；RAM 用户或 RAM 角色是否可访问取决于租户管理员配置。

2. 当前身份在目标地域至少有一个可见的 MaxCompute project，可用于提交只读 Information SchemaSQL，并具有创建查询 Instance 所需权限。

3. 目标地域已经提供上述租户级视图及其后端依赖。

安全和范围限制：

• Generate SQL 允许读取内置 Skill 记录的租户级视图，但不能指定未知系统视图或与物理表混合查询。

• Generate SQL 在模型选择系统视图前加载 Information Schema 根 Skill，用视图的数据粒度、时效和字段判断所需事实来源；选择完成后再加载对应视图的完整字段文档。

• Generate SQL 的系统视图草稿必须包含时间范围和 LIMIT。

• 查询始终为只读，不会修改配额、调度配置或作业。

智能分析工具组合场景

1. 用 maxcompute_generate_sql 生成并校验最近 30 天渠道收入 SQL。
2. 用户审核并确认后，用 maxcompute_sql_execute 执行 execute_args。
3. 如果作业失败或明显变慢，用 maxcompute_diagnose_job 分析该 Instance。

1. 省略 quota_nickname，用 maxcompute_analyze_quota_usage 查找最近 7 天内有作业的计算配额。
2. 按实际作业消耗查找高消耗作业；只对包年包月配额查看容量利用率。
3. 对存在异常信号的 Instance 调用 maxcompute_diagnose_job。
4. 根据作业证据优化 SQL 或调度；不要仅凭历史消耗自动扩容。

分析 team_etl_quota 最近 7 天失败作业的 owner 分布和 CPU 消耗；
对 CPU 消耗最高的失败 Instance 深挖原因。

智能分析工具使用建议

• 只提供当前工具支持的范围字段：Generate SQL 使用 region、sources 和可选 analysis_context；作业诊断使用 project 和 Instance ID 或 Logview URL；配额分析使用region 和精确配额 Nickname。不要把其他工具的上下文字段混入当前调用。

• SQL 生成时，已知数据范围就提供 sources，避免宽泛发现得到零候选或多个歧义数据集。

• 作业诊断先用 standard，只有结论不足或明确要求继续调查时再用 deep。

• 配额分析先比较已返回的作业消耗，再对少量热点配额和 Instance 深挖；不要把部分结果称为全量清单。

• 始终区分已确认事实、模型判断和 missing_evidence。

• 任何扩容、调度、迁移、SQL 执行、重跑或取消操作都应由用户单独确认。

通用调用规则

• 工具只能访问当前身份有权访问的 MaxCompute 资源；不要把工具可见性等同于资源授权。

• 发现候选表后，应读取准确的表结构再生成或执行 SQL，不要根据表名猜测字段、分区或 schema。

• 写 SQL、创建表、插入数据、更新元数据、修改 SemanticSpec 等写操作必须由客户端先获得用户明确确认。网关不会替客户端完成交互式二次确认。

• 大结果集应使用分页、缩小查询范围或异步实例读取。Local MCP 还可以通过本地 file://output_uri 写入文件；该路径属于 Local MCP 所在机器，不是 MCP 客户端所在机器。

• maxcompute_sql_execute 的 execution_mode 默认为 wlm。使用 MaxQA（MCQA v2）时必须显式传execution_mode=maxqa 和交互式 quota_name，且不能同时传settings.odps.task.wlm.quota。后续状态、结果或取消调用只需传正常的 project 和instance_id，不应传递或保存服务端使用的 MaxQA connection 或 cookie。

MCP 客户端看不到工具

• 浏览器 OAuth 直连时，确认 Remote MCP 服务地址包含 /mcp，并且同一个客户端配置没有混用公网与 VPC 服务地址。

• 确认浏览器 OAuth 直连所用客户端支持 Streamable HTTP、OAuth 和 tools/list。

• 本地启动器的 command 是否指向已安装的 alibabacloud-maxcompute-mcp-server，以及在同一运行环境中执行 alibabacloud-maxcompute-mcp-server --help 是否成功。

• MAXCOMPUTE_CATALOG_CONFIG 是否指向可读的配置文件，或 MAXCOMPUTE_REGION 和 MAXCOMPUTE_NETWORK 是否同时设置。

• default 是否因 Remote MCP 不可用而选择了 local。缺少本地依赖时，按错误提示安装alibabacloud-maxcompute-mcp-server[local]。

• 实际工具列表是否包含目标工具。Remote MCP 使用 maxcompute_* 工具名；local模式使用原有 SDK 工具名，两者不能直接互换。

• 修改配置后，重启 Cursor、Claude Code 或对应的 MCP 客户端。

认证、连接或权限失败

• 浏览器 OAuth 直连时，是否已经由用户本人完成阿里云 OAuth 授权。如果 OAuth页面没有打开，检查客户端是否支持 MCP OAuth，以及本机浏览器或回调端口是否被拦截。

• 浏览器 OAuth 直连出现 401 时，重新授权并确认客户端保存的访问令牌未过期或被清理。

• 确认本地启动器已取得有效的 AccessKey、STS 临时凭证、凭证 URI 或默认凭证链凭证，并确认 STS 安全令牌未过期。本地启动器不需要浏览器 OAuth。

• region 和 network 是否与目标 MaxCompute 环境一致；原有配置中的 FE 与 CatalogAPI 服务地址是否指向同一地域和网络类型。

• 确认 VPC 环境可以访问同一地域的 CatalogAPI VPC 服务地址和 MCP VPC 服务地址。VPC配置不能切换到公网 MCP。

• remote 模式在 Remote MCP 不可用时返回错误；default 模式会尝试使用本地 SDK 工具。

• 出现 403 时，确认当前阿里云账号已获得目标项目的 MaxCompute 和 RAM 权限。

• 确认对话或工具参数中的目标地域 ID 正确；未显式指定时，服务使用当前入口的默认地域。

• 使用凭证 URI 时，确认启动器所在机器可以访问 ALIBABA_CLOUD_CREDENTIALS_URI。

• 先用 Remote MCP 的 maxcompute_access_check 或 local 模式的 check_access 验证当前身份，再排查具体工具。

元数据搜索失败

Remote MCP 的 maxcompute_schema_search_metadata 和 local 模式的 search_meta_data 使用相同的 Catalog 查询语法。常见错误原因包括：

• 使用 local 模式的 search_meta_data，但未配置 namespaceId 或 MAXCOMPUTE_NAMESPACE_ID。Remote MCP 不需要该配置。

• 查询语句缺少 type=TABLE、type=RESOURCE 或 type=SCHEMA。

• 同时使用了不兼容的 project 和 region 条件。

SQL 解析、执行或结果读取失败

如果 SQL 表名解析失败，先用 Remote MCP 的 maxcompute_schema_describe_table 或 Local MCP 的 get_table_schema 读取表结构，让 Agent 使用返回的准确表引用。3 层模型常见表名格式是schema.table 或 project.schema.table；2 层模型常见表名格式是 table 或 project.table。

如果 Remote MCP 将 SQL 拒绝为写操作，确认这确实是用户希望执行的写入，并在获得用户确认后显式使用 mode=write；不要为了绕过只读校验而修改模式。

如果 SQL 执行超时或结果被截断：

• 优先使用异步执行。

  • Remote MCP 通过 maxcompute_sql_get_status 和 maxcompute_sql_fetch_result 续查；

  • Local MCP 通过 get_instance_status 和 get_instance 续查。

• Remote MCP 使用 limit 和 cursor 分页并缩小查询范围。Local MCP 还可以使用output_uri=file:///path/to/result.jsonl 写入 Local MCP 所在机器。

• 执行前先调用对应的资源用量预估工具，并根据 tools/list 中的参数定义限制资源消耗。