OpenAPI MCP Server Core 工具使用指南-OpenAPI Explorer(OpenAPI)-阿里云帮助中心

调用阿里云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": "弹性伸缩",
    "group": "弹性计算",
    "style": "RPC",
    "versions": ["2014-08-28", "2022-02-22"],
    "defaultVersion": "2022-02-22"
  },
  {
    "code": "Ecs",
    "name": "云服务器 ECS",
    "group": "弹性计算",
    "style": "RPC",
    "versions": ["2014-05-26"],
    "defaultVersion": "2014-05-26"
  },
  {
    "code": "Eci",
    "name": "弹性容器实例",
    "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通过此工具搜索阿里云官方帮助文档。例如输入“函数计算冷启动怎么优化”或“OSS Bucket Policy怎么配置”，AI Agent会检索匹配的官方文档。

使用指导

提问中包含产品名称可提高搜索结果的相关性，例如“OSS跨域配置”优于“跨域配置”。
需要查看特定产品的文档时指明产品名，例如“函数计算的冷启动优化文档”优于“冷启动优化”。

工具调用示例

输入：

{
  "query": "ECS实例创建",
  "limit": 3
}

输出：

{
  "results": [
    {
      "doc_id": 108442,
      "title": "创建方式",
      "url": "https://help.aliyun.com/zh/ecs/user-guide/create-instances/",
      "product": "云服务器 ECS",
      "content": "本文介绍创建ECS实例的几种方式...",
      "website": "cn",
      "language": "zh"
    },
    {
      "doc_id": 151725,
      "title": "ECS实例交付（创建）方式",
      "url": "https://help.aliyun.com/zh/ecs/user-guide/provisioning-methods-of-ecs-instances",
      "product": "云服务器 ECS",
      "content": "手动创建单台或多台实例...",
      "website": "cn",
      "language": "zh"
    }
  ],
  "matched_filters": {
    "product": "",
    "doc_type": null,
    "website": "cn",
    "language": "zh"
  }
}

GetDocument

AI Agent通过SearchDocuments找到相关文档后，通过此工具读取完整内容以回答用户问题。例如输入“函数计算冷启动怎么优化？”，AI Agent会先搜索定位文档，再读取全文后组织答案。

使用指导

AI Agent在搜索到文档后会自动读取内容并整理回答，整个过程对用户透明。

工具调用示例

输入：

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

输出：

{
  "doc_id": 108442,
  "url": "https://help.aliyun.com/ecs/user-guide/create-instances",
  "title": "创建实例",
  "product": "ecs",
  "content": "本文介绍创建ECS实例的几种方式..."
}

GetDocumentTree

当用户想了解某个产品的文档结构时，AI Agent通过此工具浏览文档目录树。例如输入“OSS的文档目录是怎样的”或“ECS有哪些用户指南”。

使用指导

提问时指明产品名称，例如“OSS有哪些文档分类”“ECS的用户指南下有哪些章节”。

工具调用示例

输入：

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

输出：

{
  "product": "云服务器 ECS",
  "website": "cn",
  "language": "zh",
  "children": [
    {"title": "用户指南", "doc_id": 2399509, "url": "https://help.aliyun.com/ecs/user-guide", "children": []},
    {"title": "开发参考", "doc_id": 2399511, "url": "https://help.aliyun.com/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://help.aliyun.com/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://help.aliyun.com/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
  }
}

基于文档解决问题

用户输入：

函数计算冷启动延迟很高，有什么优化方案？

AI Agent可能的工具调用链路：

通过SearchDocuments工具搜索“函数计算冷启动优化”，找到《函数计算冷启动优化最佳实践》文档（doc_id: 2513659）。
通过GetDocument工具读取该文档全文，获取冷启动定义和优化方案。
通过GetDocumentTree工具浏览函数计算的文档目录，了解还有哪些性能相关的文档章节。

涉及的工具：SearchDocuments、GetDocument、GetDocumentTree

完整调用数据

Step 1 - SearchDocuments输入：

{
  "query": "函数计算冷启动优化",
  "limit": 2
}

Step 1 - SearchDocuments输出：

{
  "results": [
    {
      "doc_id": 2513659,
      "title": "函数计算冷启动优化最佳实践",
      "url": "https://help.aliyun.com/zh/functioncompute/fc/use-cases/best-practice-for-reducing-cold-start-latencies",
      "product": "函数计算",
      "content": "本文介绍如何通过设置函数计算的最小实例数优化弹性实例的冷启动问题，提高函数性能。"
    }
  ]
}

Step 2 - GetDocument输入：

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

Step 2 - GetDocument输出（节选）：

{
  "doc_id": 2513659,
  "title": "函数计算冷启动优化最佳实践",
  "product": "functioncompute",
  "content": "本文介绍如何通过设置函数计算的最小实例数优化弹性实例的冷启动问题，提高函数性能。\n\n## 什么是冷启动\n函数计算默认使用弹性实例，即按请求自动弹性，收到请求时系统自动创建实例处理请求，无请求后实例自动回收。"
}

Step 3 - GetDocumentTree输入：

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

Step 3 - GetDocumentTree输出（节选）：

{
  "product": "函数计算",
  "children": [
    {"title": "云沙箱（FC Agent Sandbox）", "doc_id": 3030518},
    {"title": "云函数", "doc_id": 2838600}
  ]
}
// 实际返回更多，此处仅展示2个