阿里雲 OpenAPI MCP Server 提供標準化介面協議，支援通過自然語言調用雲資源 API，並可通過 OAuth、AK 靜態憑證和 RAM 許可權管理實現安全訪問與調優。 - OpenAPI Explorer

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，希望大模型直接調用而無需搜尋匹配，建議使用自訂版。

選擇認證方式

選擇版本後，還需選擇認證方式。API MCP Server 支援以下兩種認證方式：

OAuth 認證（互動認證）：通過瀏覽器自動跳轉登入，令牌到期後需重新登入。
靜態憑證認證：完成一次預檢查後，通過靜態憑證串連，無需瀏覽器。

對比項	OAuth 認證（互動認證）	AK 靜態憑證認證
適用情境	有瀏覽器互動的案頭用戶端、日常開發和探索性操作。	無圖形介面伺服器、CI/CD 流水線、AI Agent 無人值守整合。
授權方式	瀏覽器跳轉，使用者登入後授權。	環境變數傳入 AK，無需瀏覽器跳轉。
許可權身份	觸發授權的使用者身份。	AK 對應的 RAM 使用者身份。
安全性	令牌短期有效，安全性更高。	長期靜態憑證，需注意安全風險。

前提條件

使用API MCP Server 前，請根據認證方式完成以下準備：

OAuth 認證

適用於有瀏覽器互動的案頭用戶端情境，許可權跟隨使用者，令牌短期有效，安全性更高。

登入阿里雲帳號。如果使用 RAM 使用者操作，需為其授予相應許可權。具體操作，請參見為RAM使用者授予操作MCP Server的許可權。
使用管理員帳號前往RAM 控制台 - OAuth 應用 - 第三方應用，安裝 OpenAPI MCP Server 官方應用並分配，否則 MCP 服務將無法進行 OAuth 授權。具體操作，請參見安裝和授權第三方應用。

靜態憑證認證

適用於無瀏覽器互動情境（如 CI/CD 流水線、CLI 環境、AI Agent）。支援通過環境變數傳遞AccessKey（AK）憑據；若本地已登入阿里雲CLI，MCP 代理會自動複用現有憑據，無需額外配置。

已安裝 Python（>= 3.13）和 uv。
登入阿里雲帳號且已建立 AK，該 AK 對應的 RAM 使用者或 RAM 角色已授予系統權限原則 AliyunOpenAPIMCPServerStaticCredentialAccess。您可以前往RAM 控制台為 RAM 使用者授予該策略。
首次使用前，需執行預檢查（應用授權）命令，檢查帳號是否已完成應用授權。如未完成，命令會開啟瀏覽器引導您完成授權；預檢查針對阿里雲帳號生效，可在任意有瀏覽器的裝置上執行，與使用MCP的機器無需相同：。uvx alibabacloud.mcp-proxy@latest --server-url <MCP 串連地址> pre-check --site-type INTL。

擷取 MCP 服務端點（Endpoint）

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

Core 版

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

登入阿里雲 OpenAPI MCP 服務控制台。
在左側導覽列，單擊Core頁簽。頁面將顯示 Streamable HTTP Endpoint 和 SSE Endpoint。
如需修改 OAuth 或進階配置，單擊對應的修改按鈕：
- 多帳號 MCP：用於在多帳號情境下統一管理 MCP Server。具體操作，請參見多帳號情境下如何使用OpenAPI MCP Server。
- 公網配置：開啟公網訪問後，MCP 服務可通過公網訪問，適用於本地開發調試、跨地區協作或外部系統整合。
- 自訂 VPC 白名單：適用於對網路安全有嚴格管控要求的情境。

自訂版

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

登入阿里雲 OpenAPI MCP 服務控制台。
在左側導覽列，單擊自訂 > 建立，進入 MCP 配置頁面。
填寫以下資訊：
- 名稱：長度為 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 服務添加說明資訊。
單擊建立，並確認風險提示。建立完成後，頁面將顯示 Streamable HTTP Endpoint 和 SSE Endpoint。

說明

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

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

配置用戶端

擷取服務端點後，請在用戶端配置串連。此配置適用於 Core 版和自訂版。阿里雲 OpenAPI MCP 服務控制台內建了Cherry Studio、通義靈碼/Cursor/Windsurf/VSCode、Claude Code和Codex等常見用戶端的配置模板。MCP 具有廣泛的相容性，其他支援該協議的用戶端或程式也可參照實際情況自行配置。

認證支援兩種方式：

OAuth 認證（互動認證）：通過瀏覽器自動跳轉授權。
靜態憑證認證：通過環境變數傳入AK或使用阿里雲CLI憑據。

重要

AK 是長期靜態憑證，泄露後可被持續利用。使用時請務必遵守以下安全規範，詳情請參見建立AccessKey：

禁止使用主帳號 AK，必須使用 RAM 使用者的 AK，並僅授予所需的最小許可權。
禁止寫入程式碼到 mcp.json 等納入版本控制的檔案中，建議通過環境變數或Key Management Service注入。
建議定期輪換 AK，降低憑證泄露風險。

OAuth認證（預設）

OAuth 認證為預設認證方式。該流程通過調用本地瀏覽器引導使用者完成授權，適用於具備圖形介面互動能力的案頭用戶端，以及日常開發和探索性操作環境。

登入阿里雲 OpenAPI MCP 服務控制台，進入Core版或自訂版的MCP 服務端點頁面，單擊一鍵配置，選擇 OAuth 認證（預設），然後選擇對應的用戶端頁簽，按照配置模板完成配置。配置過程中，瀏覽器如果彈出使用者授權頁面，單擊授權即可。

Cherry Studio

前提條件：已安裝 Cherry Studio。

可通過以下方式完成配置：

一鍵配置：在控制台配置模板頁面，單擊一鍵配置至 Cherry Studio，按提示完成操作。
手動設定：進入 Cherry Studio 的設定 > MCP 伺服器，選擇添加 > 快速建立，填入名稱，類型選擇可串流的 HTTP，URL 填入 Streamable HTTP Endpoint 地址。也可選擇從JSON匯入，粘貼頁面中的配置 JSON。

儲存後，瀏覽器將自動跳轉至阿里雲 OAuth 授權頁面，完成授權後即可啟動 MCP 服務。

通義靈碼/Cursor/Windsurf/VSCode

前提條件：已安裝 Node.js 和 npm。

可通過以下方式完成配置：

一鍵配置（僅 Cursor 支援）：在控制台配置模板頁面，單擊一鍵配置至 Cursor，按提示完成操作。
手動設定：將控制台頁面中的配置 JSON 粘貼到用戶端的 MCP 設定檔中。

各用戶端的配置方式：

通義靈碼：開啟通義靈碼外掛程式，在介紹頁面中單擊MCP 工具，在快顯視窗右上方單擊 + 選擇手動添加。名稱自訂，類型選擇 STDIO，命令填 npx，參數填 mcp-remote-alibaba-cloud <Streamable HTTP Endpoint>。
Cursor：在功能表列依次選擇 File > Preferences > Cursor Settings > Tools & Integrations，單擊 Add Custom MCP，將 JSON 粘貼到 mcp.json 檔案中儲存。設定檔通常位於 ~/.cursor/mcp.json 或專案根目錄 .cursor/mcp.json。
Windsurf：將 JSON 粘貼到 ~/.windsurf/mcp.json 或專案根目錄 .windsurf/mcp.json。
VSCode：在設定中搜尋 MCP，按提示添加配置。

配置儲存後，首次使用需通過瀏覽器完成 OAuth 授權。如未自動跳轉，請重啟應用。

Claude Code

前提條件：已安裝 Claude Code。

請在終端執行以下命令添加 MCP 伺服器。注意將 <Streamable HTTP Endpoint> 替換為控制台中擷取的實際地址：

claude mcp add openapi-mcp-core -- npx mcp-remote-alibaba-cloud "<Streamable HTTP Endpoint>"

執行以下命令查詢已添加的MCP：

claude mcp list

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

Codex

前提條件：已安裝 Codex CLI。

請在終端執行以下命令添加 MCP 伺服器。注意將 <Streamable HTTP Endpoint> 替換為控制台中擷取的實際地址：

codex mcp add openapi-mcp-core -- npx mcp-remote-alibaba-cloud "<Streamable HTTP Endpoint>"

執行以下命令查詢已添加的MCP：

codex mcp list

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

靜態憑證認證

靜態憑證認證通過本地代理 alibabacloud.mcp-proxy 完成認證，無需瀏覽器跳轉。適用於自動化流水線、純命令列環境、AI Agent 無人值守等情境。

登入阿里雲 OpenAPI MCP 服務控制台，進入Core版或自訂版的MCP 服務端點頁面，單擊一鍵配置，選擇靜態憑證認證，然後選擇對應的用戶端頁簽，按照配置模板完成配置。

說明

如果本地已完成阿里雲CLI登入（aliyun configure），代理會自動讀取 CLI 憑據，無需在配置中設定 env 環境變數。

Cherry Studio

前提條件：

已安裝Cherry Studio、Python（>= 3.13）和 uv。
AccessKey 具有 AliyunOpenAPIMCPServerStaticCredentialAccess 系統許可權。
首次使用前，需務必執行控制台上的預檢查命令檢查帳號授權狀態。該命令可在任意有瀏覽器的裝置上執行，與運行代理的機器無需相同。

可通過以下方式完成配置：

在 Cherry Studio 中通過設定 > MCP 伺服器 > 添加 > 從 JSON 匯入粘貼配置。務必將 Access Key ID/Secret 替換為您的真實密鑰；若已配置阿里雲CLI，可直接移除 env 欄位以複用本地憑據。

配置完成後，重啟 Cherry Studio 並發送測試請求（如查詢某地區的 ECS 執行個體列表），確認 API 正常調用即表示靜態憑證認證成功。

通義靈碼/Cursor/Windsurf/VSCode

前提條件：

已安裝通義靈碼/Cursor/Windsurf/VSCode、Python（>= 3.13）和 uv。
AccessKey 具有 AliyunOpenAPIMCPServerStaticCredentialAccess 系統許可權。
首次使用前，需務必執行控制台上的預檢查命令檢查帳號授權狀態。該命令可在任意有瀏覽器的裝置上執行，與運行代理的機器無需相同。

各用戶端的配置方式：

通義靈碼：在外掛程式的 MCP 工具頁面中手動添加，類型固定選擇STDIO，命令填 uvx，參數填 alibabacloud.mcp-proxy@latest --server-url <Streamable HTTP Endpoint> --site-type INTL，並在環境變數中添加 ALIBABA_CLOUD_ACCESS_KEY_ID 和 ALIBABA_CLOUD_ACCESS_KEY_SECRET。
Cursor：將 JSON 粘貼到 ~/.cursor/mcp.json 或專案根目錄 .cursor/mcp.json。並替換AK ID與Secret。
Windsurf：將 JSON 粘貼到 ~/.windsurf/mcp.json 或專案根目錄 .windsurf/mcp.json。並替換AK ID與Secret。
VSCode：在設定中搜尋 MCP，按提示添加配置。

若已配置阿里雲CLI，可直接移除環境變數的配置以複用本地憑據。

配置完成後，儲存並重啟用戶端，發送測試請求確認 API 正常調用即表示靜態憑證認證成功。

Claude Code

前提條件：

已安裝 Claude Code、Python（>= 3.13）和 uv。
AccessKey 具有 AliyunOpenAPIMCPServerStaticCredentialAccess 系統許可權。
首次使用前，需務必執行控制台上的預檢查命令檢查帳號授權狀態。該命令可在任意有瀏覽器的裝置上執行，與運行代理的機器無需相同。

可通過以下方式完成配置：

請在終端執行以下命令添加 MCP 伺服器。注意將<Access Key ID>、<Access Key Secret> 和 <Streamable HTTP Endpoint> 替換為真實值。

若已配置阿里雲CLI，可直接移除環境變數的配置以複用本地憑據。

claude mcp add openapi-mcp-core --env ALIBABA_CLOUD_ACCESS_KEY_ID=<Access Key ID> --env ALIBABA_CLOUD_ACCESS_KEY_SECRET=<Access Key Secret> -- uvx alibabacloud.mcp-proxy@latest --server-url "<Streamable HTTP Endpoint>" --site-type INTL

執行以下命令查詢已添加的MCP：

claude mcp list

Codex

前提條件：

已安裝 Codex、Python（>= 3.13）和 uv。
AccessKey 具有 AliyunOpenAPIMCPServerStaticCredentialAccess 系統許可權。
首次使用前，需務必執行控制台上的預檢查命令檢查帳號授權狀態。該命令可在任意有瀏覽器的裝置上執行，與運行代理的機器無需相同。

可通過以下方式完成配置：

請在終端執行以下命令添加 MCP 伺服器。注意將<Access Key ID>、<Access Key Secret> 和 <Streamable HTTP Endpoint> 替換為真實值。

若已配置阿里雲CLI，可直接移除環境變數的配置以複用本地憑據。

codex mcp add openapi-mcp-core --env ALIBABA_CLOUD_ACCESS_KEY_ID=<Access Key ID> --env ALIBABA_CLOUD_ACCESS_KEY_SECRET=<Access Key Secret> -- uvx alibabacloud.mcp-proxy@latest --server-url "<Streamable HTTP Endpoint>" --site-type INTL

執行以下命令查詢已添加的MCP：

codex mcp list

使用 MCP

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

Core 版：直接用自然語言描述需求。大模型自動搜尋匹配的 API、擷取參數定義並執行調用，無需指定 API 名稱和參數。例如，輸入"幫我查詢杭州地區的 ECS 執行個體"，大模型自動找到 DescribeInstances API 並完成調用。
自訂版：配置的 API 直接作為 Tool 暴露給大模型，無需搜尋匹配，調用路徑更短。當存在多個功能相近的 API 時，自訂版能確保大模型調用指定的 API。

Cherry Studio

在文本輸入框的菜單中選擇 MCP 伺服器。
選擇 openapi-mcp-core 伺服器，確認條目右側顯示綠色對勾表示已啟用。
測試 MCP 功能。例如，查詢某個地區下的 ECS 執行個體數量：
```
請幫我查詢regionId 為 cn-chengdu 的 ECS 執行個體列表，並設定 x_mcp_region_id。
```
說明
如果 API 選擇或參數設定出現偏差，可嘗試最佳化提示詞。自訂版還可通過 MCP 調優進一步解決。

Cursor

選擇 Model 和 API Key。由於 Cursor 對 LLM provider 有要求（具體請參見Supported providers），因此在選擇 Model 和 API Key 時就參考其說明。本樣本使用預設值。
在 Cursor 對話方塊中單擊Add Context，選擇 MCP Server。
在對話方塊中輸入自然語言測試 MCP 功能，例如"請幫我查詢成都地區的 ECS 執行個體數量，僅顯示執行個體個數。"。按斷行符號鍵發送後，根據提示資訊單擊Run tool繼續執行。
查看 MCP 執行結果。如果 API 選擇或參數設定出現偏差，可嘗試最佳化提示詞。自訂版還可通過 MCP 調優進一步解決。

通義靈碼

在通義靈碼中選擇智能體並輸入提示內容，例如查詢成都地區的 ECS 執行個體列表，並設定 x_mcp_region_id。
根據通義靈碼的提示執行 MCP 工具。
查看結果。如果 API 選擇或參數設定出現偏差，可嘗試最佳化提示詞。自訂版還可通過 MCP 調優進一步解決。

Cline

在 Cline 交談視窗中輸入自然語言測試 MCP 功能，例如"請幫我查詢成都地區的 ECS 執行個體數量"。
Cline 自動選擇已配置的 MCP Server 中的 DescribeInstances 工具，並從輸入中提取 RegionId 參數值。
查看 MCP 執行結果。如果 API 選擇或參數設定出現偏差，可嘗試最佳化提示詞。自訂版還可通過 MCP 調優進一步解決。

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，單擊其操作列的編輯。
3. 修改概述、API 請求說明或 API 參數描述等。
4. 儲存修改後，在用戶端斷開並重新串連 MCP 服務，使修改生效。

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

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

MCP 存取控制

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

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

常見問題

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

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

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

重要

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

使用 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使用者的許可權。

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

不會。用戶端配置端點後，OAuth 認證會觸發 OAuth 授權流程，使用者需登入並授權。系統驗證發起授權的 RAM 使用者所屬主帳號與 MCP Server 所屬主帳號是否一致，只有兩者一致時才能訪問。靜態憑證認證下，存取權限受限於 AK 對應的 RAM 使用者權限，盜用者無法超越該許可權範圍。

靜態憑證認證和 OAuth 認證如何選擇？

根據使用情境選擇合適的認證方式：

OAuth 認證：適用於有瀏覽器互動的案頭用戶端情境。許可權跟隨使用者，令牌短期有效，安全性更高。推薦日常開發和探索性操作優先使用 OAuth。
AK 靜態憑證認證：適用於自動化流水線、純命令列環境（無圖形介面的伺服器）、AI Agent 無人值守整合等不便進行瀏覽器跳轉的情境。許可權跟隨 AK 對應的 RAM 身份，需自行管理憑證安全。

AK Secret 不慎泄露怎麼辦？

立即在 RAM 控制台禁用或刪除該 AccessKey。
建立新的 AccessKey 並更新用戶端配置。
檢查泄露期間的Action Trail日誌（ActionTrail），確認是否有異常調用。