全部產品
Search

搜尋本產品

    OpenAPI Explorer：API MCP Server 使用指南

    文件中心

    OpenAPI Explorer：API MCP Server 使用指南

    更新時間：Mar 25, 2026

    MCP（Model Context Protocol）是大模型與外部工具和資料來源互動的標準化協議。阿里雲 OpenAPI Explorer 提供 OpenAPI MCP Server，支援通過自然語言調用阿里雲 API 操作雲上資源。

    選擇使用方式

    阿里雲 OpenAPI MCP Server 提供以下兩種使用方式：

    對比項

    Core 版

    自訂版

    上手速度

    快：登入控制台後直接擷取端點（Endpoint）。

    中：需建立服務並選擇 API。

    API 覆蓋範圍

    覆蓋全部阿里雲 OpenAPI。

    僅覆蓋已選擇的 API。

    API 匹配方式

    大模型通過語義搜尋自動匹配並調用 API。當多個 API 功能相近時，可能需要更明確的提示詞。

    選定的 API 直接作為 Tool 暴露，大模型無需搜尋即可調用。

    調優能力

    不支援

    支援：可修改 API 描述和參數。

    服務數量

    每個帳號一個。

    可建立多個，按情境劃分。

    適用情境

    快速體驗、探索性操作、跨產品聯動。

    固定商務程序、明確 API 需求、需要調優的情境。

    選擇建議

    • 如需快速上手，或進行跨多個雲產品的操作，建議使用 Core 版。

    • 如已明確所需 API，希望大模型直接調用而無需搜尋匹配，建議使用自訂版。

    前提條件

    1. 登入阿里雲帳號。如果使用 RAM 使用者操作，需為其授予相應許可權。具體操作，請參見為RAM使用者授予操作MCP Server的許可權。

    2. 使用管理員帳號前往RAM 控制台 - OAuth 應用 - 第三方應用，安裝 OpenAPI MCP Server 官方應用並分配，否則 MCP 服務將無法進行 OAuth 授權。具體操作，請參見安裝和授權第三方應用。

    擷取 MCP 服務端點（Endpoint）

    Core 版和自訂版的用戶端配置流程一致，區別在於擷取 MCP 服務端點的方式不同。

    Core 版

    登入後，系統將為 Core 版自動分配 MCP 服務端點，通過內建工具組合覆蓋全部阿里雲 OpenAPI。

    1. 登入阿里雲 OpenAPI MCP 服務控制台。

    2. 在左側導覽列，單擊Core頁簽。頁面將顯示 Streamable HTTP Endpoint 和 SSE Endpoint。

      image

    3. 如需修改 OAuth 或進階配置，單擊對應的修改按鈕：

      • 多帳號 MCP：用於在多帳號情境下統一管理 MCP Server。具體操作，請參見多帳號情境下如何使用OpenAPI MCP Server。

      • 公網配置：開啟公網訪問後，MCP 服務可通過公網訪問，適用於本地開發調試、跨地區協作或外部系統整合。

      • 自訂VPC白名單：適用於對網路安全有嚴格管控要求的情境。

    自訂版

    自訂版需先建立 MCP 服務並選擇所需 API。每個選定的 API 直接作為 MCP Tool 暴露給大模型，無需經過語義搜尋即可調用。

    1. 登入阿里雲 OpenAPI MCP 服務控制台。

    2. 在左側導覽列，單擊自訂 > 建立，進入 MCP 配置頁面。

      image

      填寫以下資訊：

      • 名稱：長度為 3~16 位，支援小寫字母、數字、底線（_）和短劃線（-）。例如 mcp-demo。

      • 文檔語言：選擇 Tools 中 API 描述所使用的語言。

      • OAuth 配置：

        • 阿里雲官方 OAuth：適用於本地用戶端，例如通義靈碼、Cherry Studio、Cursor 等。

        • 自訂 OAuth：適用於自建平台或第三方服務，例如自部署的 Dify、AgentScope，以及 Claude Web/Mobile 等。

      • 多帳號 MCP：用於在多帳號情境下統一管理 MCP Server。具體操作，請參見多帳號情境下如何使用OpenAPI MCP Server。

      • 雲產品與 API 列表：為 MCP 服務配置 API Tools。

      • Terraform Tools：以 Terraform HCL 代碼的方式定義 MCP Tools。Terraform Tools 僅支援建立資源，不支援修改資源。具體操作，請參見OpenAPI MCP Server中如何使用Terraform Tools。

      • 系統 Tools：官方預設的 Tools，選擇後自動整合到 MCP 服務中。

      • MCP 指令：用於提示大模型如何使用該 MCP，需要用戶端支援 MCP 標準協議的 Instructions 欄位。

      • 備忘：為 MCP 服務添加說明資訊。

    3. 單擊建立，並確認風險提示。建立完成後，頁面將顯示 Streamable HTTP Endpoint 和 SSE Endpoint。

    說明

    建議單個 MCP Server 選擇的 API 數量不超過 30 個。如需使用更多 API，建議建立多個 MCP Server。

    如果在 VPC 環境中使用 MCP，請優先使用頁面中顯示的 VPC 端點。

    配置用戶端

    擷取 MCP 服務端點後，在用戶端中配置串連。以下配置方式適用於 Core 版和自訂版。支援的用戶端包括Cherry Studio、通義靈碼、Cursor、Cline等。

    一鍵配置

    控制台的 MCP 服務端點頁面提供一鍵配置功能，支援將端點直接寫入用戶端。單擊一鍵配置，選擇勘探端，按照提示完成操作。

    image

    配置過程中，瀏覽器將彈出使用者授權頁面，單擊授權即可。

    image

    以 Cherry Studio 為例，授權成功後，MCP 工具載入完成：

    image

    手動設定

    Cherry Studio

    1. 進入設定 > MCP伺服器，選擇添加 > 快速建立來添加 MCP 伺服器。

      image

    2. 填入名稱，類型選擇可串流的HTTP，URL 填入擷取的 Streamable HTTP Endpoint。

      image

    3. 單擊右上方的儲存按鈕，瀏覽器將自動跳轉至阿里雲 OAuth 授權頁面。確認授權資訊後，單擊授權。

      image

    4. 完成授權後，Cherry Studio 會自動啟動 MCP 服務。

      image

    通義靈碼

    1. 開啟通義靈碼外掛程式，在介紹頁面中單擊MCP工具。

    2. 在快顯視窗的右上方，單擊+，選擇手動添加。

      image

    3. 在添加MCP服務視窗中填入以下內容，然後單擊立即添加。

      名稱

      MCP 服務的名稱，建議與控制台建立的服務名稱保持一致。

      類型

      固定選擇STDIO。

      命令

      固定為npx。

      參數

      格式為 mcp-remote-alibaba-cloud <SSE Endpoint>。僅支援 SSE Endpoint，可從 MCP 服務端點頁面擷取。

    4. 在 OAuth 頁面完成授權。

      image

      在通義靈碼中啟用 MCP 的效果如下：

      image

    Cursor

    1. 在 Cursor 功能表列，依次選擇File > Preferences > Cursor Settings > Tools & Integrations，然後單擊Add Custom MCP配置 MCP Server。

      image

    2. 從 MCP Server 配置頁面複製內容，粘貼到 mcp.json 檔案中，並按 Ctrl+S 儲存。

      image

    3. 在 OAuth 頁面完成授權。

      image

    4. 在 Cursor Settings 中可以查看已配置的 MCP Server 資訊。

      image

    Cline

    1. 在 VS Code 中開啟 Cline 外掛程式，並輸入 API Key。

    2. 在 Cline 頂部功能表列，單擊MCP Servers配置 MCP Server。

      image

      image

    3. 在 OAuth 頁面完成授權。

      image

    4. 授權完成後，Cline 底部的 MCP Servers 地區出現新配置的 MCP Server，表示配置成功。

      image

    使用 MCP

    配置完成後，在用戶端中使用自然語言即可操作雲資源。更多整合方式，請參見更多整合 MCP 方式。

    • Core 版：直接用自然語言描述需求。大模型自動搜尋匹配的 API、擷取參數定義並執行調用，無需指定 API 名稱和參數。例如，輸入“幫我查詢杭州地區的 ECS 執行個體”，大模型自動找到 DescribeInstances API 並完成調用。

    • 自訂版：配置的 API 直接作為 Tool 暴露給大模型，無需搜尋匹配，調用路徑更短。當存在多個功能相近的 API 時，自訂版能確保大模型調用指定的 API。

    Cherry Studio

    1. 在文本輸入框的菜單中選擇 MCP 伺服器。

      image

    2. 測試 MCP 功能。例如，查詢某個地區下的 ECS 執行個體數量：

      請幫我查詢regionId為cn-chengdu的ECS執行個體列表，並設定x_mcp_region_id。

      image

      說明

      如果 API 選擇或參數設定出現偏差，可嘗試最佳化提示詞。自訂版還可通過 MCP 調優進一步解決。

    Cursor

    1. 選擇 Model 和 API Key。由於 Cursor 對 LLM provider 有要求（具體請參見Supported providers），因此在選擇 Model 和 API Key 時需參考其說明。本樣本使用預設值。

    2. 在 Cursor 對話方塊中單擊Add Context，選擇 MCP Server。

      image

    3. 在對話方塊中輸入自然語言測試 MCP 功能，例如“請幫我查詢成都地區的 ECS 執行個體數量，僅顯示執行個體個數。”。按斷行符號鍵發送後，根據提示資訊單擊Run tool繼續執行。

      image

    4. 查看 MCP 執行結果。如果 API 選擇或參數設定出現偏差，可嘗試最佳化提示詞。自訂版還可通過 MCP 調優進一步解決。

      image

    通義靈碼

    1. 在通義靈碼中選擇智能體並輸入提示內容，例如查詢成都地區的 ECS 執行個體列表，並設定 x_mcp_region_id。

      image

    2. 根據通義靈碼的提示執行 MCP 工具。

      image

    3. 查看結果。如果 API 選擇或參數設定出現偏差，可嘗試最佳化提示詞。自訂版還可通過 MCP 調優進一步解決。

      image

    Cline

    1. 在 Cline 交談視窗中輸入自然語言測試 MCP 功能，例如“請幫我查詢成都地區的 ECS 執行個體數量”。

      image

      Cline 自動選擇已配置的 MCP Server 中的 DescribeInstances 工具，並從輸入中提取 RegionId 參數值。

    2. 查看 MCP 執行結果。如果 API 選擇或參數設定出現偏差，可嘗試最佳化提示詞。自訂版還可通過 MCP 調優進一步解決。

      image

    MCP 調優（僅適用於自訂版）

    Core 版通過內建工具自動處理 API 搜尋和調用，不支援調優。

    當大模型選擇了錯誤的 API 或傳遞了不正確的參數時，可在服務端修改 API 的概述、說明和請求參數描述，協助大模型更準確地理解和調用 API。

    樣本一：操作非 cn-hangzhou 地區的資源時，可能會出現報錯或資料不準確

    MCP 底層通過 x_mcp_region_id 切換 Endpoint。如果大模型未能根據輸入理解需要傳遞 x_mcp_region_id，將預設操作 cn-hangzhou 地區的資源。

    可以通過以下兩種方式解決：

    • 在提問時明確指示大模型設定 x_mcp_region_id。

      請幫我查詢regionId為cn-qingdao的ECS執行個體列表，並設定x_mcp_region_id。

    • 在 MCP 服務端調整 API 的概述或請求參數 RegionId 的描述。

      例如，在 API 概述中補充“將使用者描述的地區傳遞給 x_mcp_region_id”，或在 RegionId 的描述中添加“如果參數 RegionId 存在，必須將其與 x_mcp_region_id 一起傳遞”。

      操作步驟：

      1. 訪問自訂API MCP SERVER，單擊目標 MCP 服務作業列的編輯。

      2. 選中待調優的 API，單擊其操作列的編輯。

        image

      3. 修改概述、API 請求說明或 API 參數描述等。

      4. 儲存修改後，在用戶端斷開並重新串連 MCP 服務，使修改生效。

    樣本二：刪除 API 中部分非必填參數

    部分非必填參數在特定情境下無需使用，可在 MCP 服務端刪除。刪除後，大模型在產生參數時會忽略這些參數，降低錯誤率並減少 Token 消耗。

    MCP 存取控制

    image

    AI Agent 整合 OpenAPI MCP Server 後，Agent 本身不具備訪問雲資源的許可權，必須由使用者觸發授權流程，以代理使用者身份進行操作。例如，用戶端通過喚起 OAuth 流程，在使用者授權後，Agent 才能獲得臨時的存取權限。所有操作均需使用者授權，Agent 能執行的任務受限於使用者自身的許可權，實現了最小許可權原則。此外，Action Trail記錄的是實際執行操作的使用者身份。

    適用情境：CherryStudio、通義靈碼、Qwen Code、Cursor、Claude Code、Dify、AgentScope、LangGraph 等用戶端 Agent 或需要代理使用者身份的情境。

    更多整合 MCP 方式

    常見問題

    1. Tools 中的 API，在 MCP 用戶端是否都可以調用？

    不一定。調用是否成功取決於發起 OAuth 授權的 RAM 使用者的許可權。如果該 RAM 使用者沒有某個 API 的調用許可權，則大模型也無法調用該 API。

    解決方案：為 RAM 使用者授予相應 API 的許可權。具體操作，請參見管理RAM使用者的許可權。

    重要

    為防止大模型因理解錯誤而調用刪除資源的 API，導致業務受到影響，建議不要為 RAM 使用者授予刪除資源的許可權。

    2. 使用 RAM 使用者建立 MCP Server 時，提示無許可權操作

    解決方案：

    • 為 RAM 使用者授予系統權限原則 AliyunOpenAPIMCPServerFullAccess。具體操作，請參見管理RAM使用者的許可權。

    • 為 RAM 使用者授予自訂權限原則：

      1. 使用管理員帳號在RAM 控制台建立自訂權限原則。具體操作，請參見建立自訂權限原則。

        權限原則內容如下：

        點擊查看 MCP Server 操作相關權限原則

        該權限原則包括建立、更新、查詢及刪除 MCP Server 的許可權，以及查詢 MCP 系統工具的許可權。

        {
  "Version": "1",
  "Statement": [
    {
      "Action": [
        "openapiexplorer:*Mcp*",
        "ram:*Application*"
      ],
      "Resource": "*",
      "Effect": "Allow"
    }
  ]
}

      2. 使用管理員帳號為目標 RAM 使用者授予該自訂許可權。具體操作，請參見管理RAM使用者的許可權。

    3. MCP Server 串連端點（Endpoint）暴露後，是否會被他人盜用？

    不會。用戶端配置端點後會觸發 OAuth 授權流程，使用者需登入並授權。系統驗證發起授權的 RAM 使用者所屬主帳號與 MCP Server 所屬主帳號是否一致，只有兩者一致時才能訪問。