OpenAPI MCP Server Core 工具使用指南 - OpenAPI Explorer

調用阿里雲OpenAPI時，需要尋找API名稱、拼裝請求參數、處理分頁和跨地區調用。OpenAPI MCP Server Core版（以下簡稱“Core版”）提供15個內建工具，通過自然語言即可完成API調用、多步編排、Terraform資源管理、協助文檔檢索。可用於常見的AI Agent（例如：Qoder、Claude Code、CodeX等）。以下逐一說明每個工具的功能、參數和使用方式。

前提條件

已完成Core版MCP Server的配置和接入。具體操作，參見OpenAPI MCP Server 使用指南。
確認MCP串連。在AI Agent對話中輸入“列出阿里雲有哪些計算相關的產品”，如果返回產品列表則串連正常。

工具總覽

Core版包含15個工具，按功能分為以下五個類別：

類別	工具	用途
API發現與探索	ListProducts	列出所有阿里雲產品及元資訊
	ListApis	列出指定產品的所有API
	GetApiDefinition	擷取API的完整參數定義
	SearchApis	基於自然語言描述推薦匹配的OpenAPI
	ListProductRegions	列出產品支援的地區
API執行	GenerateCLICommand	產生CLI命令（不執行）
API執行	CallCLI	執行阿里雲CLI命令
進階編排	RunScript	執行Python指令碼，支援多API編排
進階編排	GetTask	輪詢非同步任務狀態
基礎設施即代碼	GetPresignedUrl	產生OSS預簽名URL
基礎設施即代碼	RunIaC	執行Terraform HCL代碼
文檔檢索	SearchDocuments	搜尋協助文檔
	GetDocument	擷取文檔Markdown本文
	GetDocumentTree	瀏覽產品文檔分類樹
	GrepDocuments	按關鍵詞匹配文檔內容

工具詳情

API發現與探索

ListProducts

當需要瞭解阿里雲有哪些產品時，AI Agent通過此工具查詢產品目錄。例如輸入“阿里雲有哪些計算的產品”，AI Agent會提取關鍵詞並篩選出計算相關的產品列表。

使用指導

描述中明確產品關鍵字，例如“阿里雲有哪些計算的產品”優於“阿里雲有哪些產品”。
查詢結果可作為後續對話的上下文，例如先問“有哪些資料庫產品”，再針對具體產品追問操作細節。

工具調用樣本

輸入：

{
  "filter": "計算"
}

輸出：

[
  {
    "code": "Ess",
    "name": "Auto Scaling",
    "group": "彈性計算",
    "style": "RPC",
    "versions": ["2014-08-28", "2022-02-22"],
    "defaultVersion": "2022-02-22"
  },
  {
    "code": "Ecs",
    "name": "Elastic Compute Service",
    "group": "彈性計算",
    "style": "RPC",
    "versions": ["2014-05-26"],
    "defaultVersion": "2014-05-26"
  },
  {
    "code": "Eci",
    "name": "Elastic Container Instance",
    "group": "彈性計算",
    "style": "RPC",
    "versions": ["2018-08-08"],
    "defaultVersion": "2018-08-08"
  }
]
// 實際返回更多，此處僅展示3個

ListApis

當使用者的操作意圖涉及某個產品但AI Agent需要確認具體的API操作時，會通過此工具瀏覽該產品的API列表。例如輸入“幫我給ECS執行個體分配公網IP”，AI Agent可能先查詢ECS有哪些相關API，再選擇合適的介面執行。

使用指導

描述操作意圖時盡量明確產品和動作，例如“給ECS執行個體分配公網IP”優於“分配IP”。

工具調用樣本

輸入：

{
  "product": "Ecs",
  "filter": "Instance"
}

輸出：

[
  {
    "summary": "為一台ECS執行個體分配一個公網IP地址。",
    "apiName": "AllocatePublicIpAddress",
    "title": "分配公網IP"
  },
  {
    "summary": "本介面用於為一台或多台ECS執行個體授予RAM角色。",
    "apiName": "AttachInstanceRamRole",
    "title": "為執行個體授予RAM角色"
  }
]
// 實際返回更多，此處僅展示2個

GetApiDefinition

當使用者的操作請求涉及API調用時，AI Agent通常先通過SearchApis或ListApis找到目標API，再通過此工具擷取該API的參數定義，最後構造正確的調用。例如輸入“查詢杭州地區的ECS執行個體”，AI Agent會先定位到DescribeInstances介面，再通過此工具確認需要哪些參數後執行。

使用指導

描述操作意圖時盡量具體，AI Agent定位到正確的API後會自動確認參數並執行。

工具調用樣本

輸入：

{
  "product": "Ecs",
  "apiVersion": "2014-05-26",
  "apiName": "DescribeInstances"
}

輸出：

{
  "summary": "本介面支援根據不同請求條件查詢執行個體列表",
  "methods": ["post", "get"],
  "parameters": ["...關45個參數，此處省略"],
  "responses": {"...": "省略"},
  "errorCodes": ["...省略"]
}

SearchApis

當不確定具體API名稱時，AI Agent通過此工具根據自然語言描述匹配對應的阿里雲OpenAPI。例如輸入“怎麼查看ECS執行個體的監控資料”，AI Agent會搜尋並找到相關的監控類API。

使用指導

描述中包含產品名稱，例如“查詢ECS安全性群組規則”優於“查詢安全性群組”。
複雜需求拆分為多個獨立問題分別提問，每個問題對應一個API操作。
已明確API名稱時直接告知AI Agent（如“用DescribeInstances查詢”），可跳過搜尋步驟。

工具調用樣本

輸入：

{
  "prompt": "怎麼查看ECS執行個體的監控資料",
  "limit": 3
}

輸出：

[
  {
    "apiName": "DescribeInstanceMonitorData",
    "code": "Ecs",
    "description": "調用DescribeInstanceMonitorData查詢一台ECS執行個體的監控資訊。可查詢的指標包括ECS執行個體的vCPU使用率、突發效能執行個體積分、接收的資料流量、發送的資料流量、平均頻寬等。",
    "weight": 0.98,
    "version": "2014-05-26"
  },
  {
    "apiName": "QueryMetricList",
    "code": "Cms",
    "description": "查詢一段時間內指定產品執行個體的監控資料。",
    "weight": 0.85,
    "version": "2016-09-22"
  },
  {
    "apiName": "DescribeMetricLast",
    "code": "Cms",
    "description": "查詢指定監控項的最新監控資料。",
    "weight": 0.75,
    "version": "2019-01-01"
  }
]

ListProductRegions

當操作涉及地區選擇時，AI Agent通過此工具確認目標地區是否支援該產品。例如輸入“ECS在烏蘭察布能用嗎”或“幫我在新加坡建立一台ECS”，AI Agent會先確認地區可用性。

使用指導

提問中明確產品名稱和目標地區，例如“ECS在烏蘭察布能用嗎”優於“烏蘭察布能用嗎”。
涉及多個地區時逐一說明，例如“幫我確認ECS在杭州、上海、新加坡是否都能用”。

工具調用樣本

輸入：

{
  "product": "Ecs"
}

輸出：

{
  "code": 0,
  "data": {
    "type": "regional",
    "endpoints": [
      {
        "regionId": "us-west-1",
        "regionName": "美國（矽谷）",
        "public": "ecs.us-west-1.aliyuncs.com",
        "vpc": "ecs-vpc.us-west-1.aliyuncs.com"
      },
      {
        "regionId": "cn-hangzhou",
        "regionName": "華東1（杭州）",
        "public": "ecs.cn-hangzhou.aliyuncs.com",
        "vpc": "ecs-vpc.cn-hangzhou.aliyuncs.com"
      }
    ]
  }
}
// 實際返回更多，此處僅展示2個

API執行

GenerateCLICommand

當使用者要求“只產生命令不執行”或AI Agent需要預覽命令時，通過此工具產生CLI命令字串。AI Agent通常先通過GetApiDefinition確認參數，再通過此工具產生命令，最後由CallCLI執行。例如輸入“幫我產生查詢杭州ECS執行個體的命令”，AI Agent會返回可在本地終端執行的完整命令。

使用指導

如果需要在本地終端手動執行命令，可要求AI Agent“只產生命令不執行”，產生的命令可直接複製使用。

工具調用樣本

輸入：

{
  "product": "Ecs",
  "apiVersion": "2014-05-26",
  "apiName": "DescribeInstances",
  "regionId": "cn-hangzhou",
  "jsonApiParameters": "{\"Status\": \"Running\", \"PageSize\": 100}"
}

輸出：

{
  "cli": "aliyun ecs describe-instances --page-size 100 --status Running --region cn-hangzhou"
}

CallCLI

當AI Agent明確知道要執行哪個API操作時，通過此工具直接調用。這是Core版中調用API的主要工具（Primary tool）。例如輸入“查詢杭州地區運行中的ECS執行個體”，AI Agent會構造CLI命令並執行查詢。

使用指導

此工具執行的CLI命令在遠程伺服器運行，無法讀取本地檔案。
寫操作（建立、修改、刪除資源）可能產生費用，建議要求AI Agent執行前先確認操作內容。

工具調用樣本

輸入：

{
  "command": "aliyun ecs describe-instances --biz-region-id cn-hangzhou --status Running"
}

輸出：

{
  "Instances": {
    "Instance": []
  },
  "PageNumber": 1,
  "PageSize": 10,
  "TotalCount": 0
}

進階編排

RunScript

當單次API調用無法滿足需求時，AI Agent通過此工具編寫指令碼完成大量操作。例如輸入“統計所有地區的ECS執行個體數量”或“檢查所有安全性群組是否有高風險規則”，AI Agent會編寫並髮腳本同時查詢多個資源。

使用指導

需要匯總、對比或大量操作時，描述清楚範圍和目標，例如“統計所有地區的ECS執行個體數量”“檢查所有安全性群組是否有高風險規則”。
指令碼執行可能需要數秒到數十秒，耐心等待結果返回即可。

工具調用樣本

輸入：

{
  "script": "regions = ['cn-hangzhou', 'cn-shanghai', 'cn-beijing']\nresponses = await asyncio.gather(*[\n    call_cli(product='Ecs', action='DescribeInstances',\n             params={'RegionId': r, 'PageSize': 100})\n    for r in regions\n], return_exceptions=True)\nresult = {r: res.get('TotalCount', 0) if isinstance(res, dict) else str(res)\n    for r, res in zip(regions, responses)}"
}

輸出：

{
  "processID": "proc_1f7b02be133a41ee89135fafb833a972",
  "status": "Running",
  "nextAction": "CallGetTask",
  "result": null,
  "waitTimedOut": true,
  "message": "任務未終態，請調用 AlibabaCloud___GetTask 等待結果。",
  "error": null
}

GetTask

當RunScript或RunIaC的任務執行時間較長時，AI Agent通過此工具等待任務完成並擷取結果。執行耗時較長的操作（如跨地區巡檢、Terraform部署）時可能觸發此工具。

使用指導

執行耗時較長的操作（如跨地區巡檢、批量查詢）時，耐心等待結果返回即可。
如果涉及人工審批，按提示完成審批次程序後結果會繼續返回。

工具調用樣本

輸入：

{
  "processID": "proc_1f7b02be133a41ee89135fafb833a972",
  "waitTimeoutSeconds": 25
}

輸出：

{
  "processID": "proc_1f7b02be133a41ee89135fafb833a972",
  "status": "Succeeded",
  "nextAction": "None",
  "result": {
    "cn-hangzhou": 0,
    "cn-shanghai": 0,
    "cn-beijing": 0
  }
}

基礎設施即代碼

GetPresignedUrl

當RunIaC或RunScript工具需要引用外部檔案時，AI Agent通過此工具產生臨時上傳連結。例如Terraform代碼超過64 KB，或指令碼需要處理預上傳的資料檔案時，AI Agent會先通過此工具上傳檔案再執行後續操作。

使用指導

涉及大檔案上傳時，可能需要等待上傳完成後再執行後續操作。

RunIaC

當需要建立、變更或銷毀雲資源時，AI Agent可能通過此工具以Terraform方式管理基礎設施。例如輸入“在杭州建立一個VPC，CIDR為172.16.0.0/16”，AI Agent會先產生資源配置並預覽變更，確認後再執行建立。

使用指導

描述資源需求時明確地區、規格和命名，例如“在杭州建立一個VPC，CIDR為172.16.0.0/16，名稱為mcp-demo-vpc”。
涉及資源變更時可能需要人工審批，按提示完成審批次程序即可。

文檔檢索

SearchDocuments

當使用者提出產品使用、配置方法、報錯排查等知識性問題時，AI Agent通過此工具搜尋阿里雲官方協助文檔。例如輸入“Function Compute冷啟動怎麼最佳化”或“OSS Bucket Policy怎麼配置”，AI Agent會檢索匹配的官方文檔。

使用指導

提問中包含產品名稱可提高搜尋結果的相關性，例如“OSS跨網域設定”優於“跨網域設定”。
需要查看特定產品的文檔時指明產品名，例如“Function Compute的冷啟動最佳化文檔”優於“冷啟動最佳化”。

工具調用樣本

輸入：

{
  "query": "ECS執行個體建立",
  "limit": 3
}

輸出：

{
  "results": [
    {
      "doc_id": 108442,
      "title": "建立方式",
      "url": "https://www.alibabacloud.com/help/zh/ecs/user-guide/create-instances/",
      "product": "Elastic Compute Service",
      "content": "本文介紹建立ECS執行個體的幾種方式...",
      "website": "cn",
      "language": "zh"
    },
    {
      "doc_id": 151725,
      "title": "ECS執行個體交付（建立）方式",
      "url": "https://www.alibabacloud.com/help/zh/ecs/user-guide/provisioning-methods-of-ecs-instances",
      "product": "Elastic Compute Service",
      "content": "手動建立單台或多台執行個體...",
      "website": "cn",
      "language": "zh"
    }
  ],
  "matched_filters": {
    "product": "",
    "doc_type": null,
    "website": "cn",
    "language": "zh"
  }
}

GetDocument

AI Agent通過SearchDocuments找到相關文檔後，通過此工具讀取完整內容以回答使用者問題。例如輸入“Function Compute冷啟動怎麼最佳化？”，AI Agent會先搜尋定位文檔，再讀取全文後組織答案。

使用指導

AI Agent在搜尋到文檔後會自動讀取內容並整理回答，整個過程對使用者透明。

工具調用樣本

輸入：

{
  "doc_id": 108442,
  "max_length": 500
}

輸出：

{
  "doc_id": 108442,
  "url": "https://www.alibabacloud.com/help/ecs/user-guide/create-instances",
  "title": "建立執行個體",
  "product": "ecs",
  "content": "本文介紹建立ECS執行個體的幾種方式..."
}

GetDocumentTree

當使用者想瞭解某個產品的文檔結構時，AI Agent通過此工具瀏覽文檔分類樹。例如輸入“OSS的文檔目錄是怎樣的”或“ECS有哪些使用者指南”。

使用指導

提問時指明產品名稱，例如“OSS有哪些文檔分類”“ECS的使用者指南下有哪些章節”。

工具調用樣本

輸入：

{
  "doc_id": 108442,
  "depth": 1
}

輸出：

{
  "product": "Elastic Compute Service",
  "website": "cn",
  "language": "zh",
  "children": [
    {"title": "使用者指南", "doc_id": 2399509, "url": "https://www.alibabacloud.com/help/ecs/user-guide", "children": []},
    {"title": "開發參考", "doc_id": 2399511, "url": "https://www.alibabacloud.com/help/ecs/developer-reference", "children": []},
    {"title": "產品計費", "doc_id": 25396, "children": []},
    {"title": "常見問題", "doc_id": 2983136, "children": []}
  ]
}
// 本樣本depth為1，僅返回頂層節點。depth設為2或3時，children中會包含下級章節

GrepDocuments

當使用者的問題涉及特定術語、配置項或錯誤碼時，AI Agent通過此工具在指定產品文檔中精確匹配關鍵詞。例如輸入“ECS文檔裡InstanceChargeType有哪些取值”或“幫我在OSS文檔中查一下CORS相關的內容”。

使用指導

提問時同時指明產品和關鍵詞，例如“在ECS文檔中搜尋DescribeInstanceAttribute”。
關鍵詞越精確匹配結果越相關，多個關鍵詞之間是AND關係。

工具調用樣本

輸入：

{
  "product": "ecs",
  "pattern": "DescribeInstanceAttribute",
  "limit": 3
}

輸出：

{
  "product_code": "ecs",
  "pattern": "DescribeInstanceAttribute",
  "matches": [
    {
      "title": "DescribeInstanceAttribute - 查詢執行個體屬性資訊",
      "url": "https://www.alibabacloud.com/help/ecs/developer-reference/api-ecs-2014-05-26-describeinstanceattribute",
      "matched_text": "DescribeInstanceTypes - 查詢執行個體規格資訊列表\nDescribeInstanceAttribute - 查詢執行個體屬性資訊\nModifyInstanceAttribute - 修改執行個體屬性資訊",
      "line_no": 986
    }
  ],
  "total": 1,
  "truncated": false,
  "llms_txt_url": "https://www.alibabacloud.com/help/zh/ecs/llms.txt"
}

典型使用情境

以下情境展示多個工具協作完成複雜任務的完整鏈路。

查詢安全性群組規則

使用者輸入：

幫我查一下杭州地區的安全性群組有哪些規則

AI Agent可能的工具調用鏈路：

通過SearchApis工具搜尋“查詢ECS執行個體關聯的安全性群組規則”，定位到DescribeSecurityGroupAttribute介面（信賴度0.98）。
通過GetApiDefinition工具確認該介面需要SecurityGroupId和RegionId兩個必填參數。
通過CallCLI工具執行查詢，返回安全性群組規則列表（包含方向、協議、連接埠範圍、源地址等資訊）。

涉及的工具：SearchApis、GetApiDefinition、CallCLI

完整調用資料

Step 1 - SearchApis輸入：

{
  "prompt": "查詢ECS執行個體關聯的安全性群組規則",
  "limit": 2
}

Step 1 - SearchApis輸出：

[
  {
    "apiName": "DescribeSecurityGroupAttribute",
    "code": "Ecs",
    "description": "本介面主要用於查詢一個指定安全性群組的詳細資料，並關聯查詢安全性群組規則詳細資料列表。",
    "weight": 0.98,
    "version": "2014-05-26"
  },
  {
    "apiName": "DescribeSecurityGroupReferences",
    "code": "Ecs",
    "description": "本介面用於查詢一個或多個指定安全性群組已經被授權的其他安全性群組列表資訊。",
    "weight": 0.75,
    "version": "2014-05-26"
  }
]

Step 3 - CallCLI輸入：

{
  "command": "aliyun ecs describe-security-group-attribute --security-group-id sg-bp16kuncwlmc3849phsj --biz-region-id cn-hangzhou"
}

Step 3 - CallCLI輸出（節選）：

{
  "InnerAccessPolicy": "Accept",
  "Permissions": {
    "Permission": [
      {
        "Direction": "ingress",
        "IpProtocol": "ALL",
        "Policy": "Accept",
        "PortRange": "-1/-1",
        "SourceCidrIp": "0.0.0.0/0"
      }
    ]
  },
  "SecurityGroupId": "sg-bp16kuncwlmc3849phsj",
  "SecurityGroupName": "China-Office-China-ec"
}

跨地區批量巡檢

使用者輸入：

統計杭州、上海、北京三個地區各有多少台ECS執行個體

AI Agent可能的工具調用鏈路：

通過RunScript工具編寫並髮腳本，同時查詢三個地區的執行個體數量。
指令碼執行逾時（超過20秒），返回processID。
通過GetTask工具輪詢任務狀態，等待指令碼執行完成後擷取結果。

涉及的工具：RunScript、GetTask

完整調用資料

Step 1 - RunScript輸入：

{
  "script": "regions = ['cn-hangzhou', 'cn-shanghai', 'cn-beijing']\nresponses = await asyncio.gather(*[\n    call_cli(product='Ecs', action='DescribeInstances',\n             params={'RegionId': r, 'PageSize': 100})\n    for r in regions\n], return_exceptions=True)\nresult = {r: res.get('TotalCount', 0) if isinstance(res, dict) else str(res)\n    for r, res in zip(regions, responses)}"
}

Step 1 - RunScript輸出（逾時）：

{
  "processID": "proc_1f7b02be133a41ee89135fafb833a972",
  "status": "Running",
  "nextAction": "CallGetTask",
  "result": null,
  "waitTimedOut": true,
  "message": "任務未終態，請調用 AlibabaCloud___GetTask 等待結果。"
}

Step 2 - GetTask輸入：

{
  "processID": "proc_1f7b02be133a41ee89135fafb833a972",
  "waitTimeoutSeconds": 25
}

Step 2 - GetTask輸出：

{
  "processID": "proc_1f7b02be133a41ee89135fafb833a972",
  "status": "Succeeded",
  "nextAction": "None",
  "result": {
    "cn-hangzhou": 0,
    "cn-shanghai": 0,
    "cn-beijing": 0
  }
}

基於文檔解決問題

使用者輸入：

Function Compute冷啟動延遲很高，有什麼最佳化方案？

AI Agent可能的工具調用鏈路：

通過SearchDocuments工具搜尋“Function Compute冷啟動最佳化”，找到《Function Compute冷啟動最佳化最佳實務》文檔（doc_id: 2513659）。
通過GetDocument工具讀取該文檔全文，擷取冷啟動定義和最佳化方案。
通過GetDocumentTree工具瀏覽Function Compute的文檔目錄，瞭解還有哪些效能相關的文檔章節。

涉及的工具：SearchDocuments、GetDocument、GetDocumentTree

完整調用資料

Step 1 - SearchDocuments輸入：

{
  "query": "Function Compute冷啟動最佳化",
  "limit": 2
}

Step 1 - SearchDocuments輸出：

{
  "results": [
    {
      "doc_id": 2513659,
      "title": "Function Compute冷啟動最佳化最佳實務",
      "url": "https://www.alibabacloud.com/help/zh/functioncompute/fc/use-cases/best-practice-for-reducing-cold-start-latencies",
      "product": "Function Compute",
      "content": "本文介紹如何通過設定Function Compute的最小執行個體數最佳化彈性執行個體的冷啟動問題，提高函數效能。"
    }
  ]
}

Step 2 - GetDocument輸入：

{
  "doc_id": 2513659,
  "max_length": 300
}

Step 2 - GetDocument輸出（節選）：

{
  "doc_id": 2513659,
  "title": "Function Compute冷啟動最佳化最佳實務",
  "product": "functioncompute",
  "content": "本文介紹如何通過設定Function Compute的最小執行個體數最佳化彈性執行個體的冷啟動問題，提高函數效能。\n\n## 什麼是冷啟動\nFunction Compute預設使用彈性執行個體，即按請求自動彈性，收到請求時系統自動建立執行個體處理請求，無請求後執行個體自動回收。"
}

Step 3 - GetDocumentTree輸入：

{
  "product": "functioncompute",
  "depth": 1
}

Step 3 - GetDocumentTree輸出（節選）：

{
  "product": "Function Compute",
  "children": [
    {"title": "雲沙箱（FC Agent Sandbox）", "doc_id": 3030518},
    {"title": "雲函數", "doc_id": 2838600}
  ]
}
// 實際返回更多，此處僅展示2個