MaxCompute：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 中的參數定義限制資源消耗。