OpenAPI MCP Server Core Tool Usage Guide-OpenAPI Explorer(OpenAPI)-阿里云帮助中心

When calling Alibaba Cloud OpenAPI, it is necessary to look up API names, assemble request parameters, and handle pagination and cross-region calls. OpenAPI MCP Server Core Edition (hereinafter “Core Edition”) provides 15 built-in tools that enable API calls, multi-step orchestration, Terraform resource management, and documentation search through natural language. It is compatible with common AI Agents (e.g., Qoder, Claude Code, CodeX). The following describes the function, parameters, and usage of each tool.

Prerequisites

Core Edition MCP Server configuration and integration has been completed. For details, see OpenAPI MCP Server.
Verify the MCP connection. Enter “List Alibaba Cloud compute-related products” in the AI Agent conversation. If a product list is returned, the connection is working properly.

Tool Overview

Core Edition includes 15 tools, categorized into the following five groups:

Category	Tool	Description
API Discovery	ListProducts	List all Alibaba Cloud products and metadata
	ListApis	List all APIs under a specified product
	GetApiDefinition	Get complete parameter definitions of an API
	SearchApis	Recommend matching OpenAPI based on natural language description
	ListProductRegions	List regions supported by a product
API Execution	GenerateCLICommand	Generate CLI command (without executing)
API Execution	CallCLI	Execute Alibaba Cloud CLI command
Advanced Orchestration	RunScript	Execute Python scripts with multi-API orchestration
Advanced Orchestration	GetTask	Poll asynchronous task status
Infrastructure as Code	GetPresignedUrl	Generate OSS presigned URL
Infrastructure as Code	RunIaC	Execute Terraform HCL code
Document Search	SearchDocuments	Search documentation
	GetDocument	Get document Markdown content
	GetDocumentTree	Browse product document directory tree
	GrepDocuments	Match document content by keyword

Tool Details

API Discovery

ListProducts

When it is necessary to learn which Alibaba Cloud products are available, the AI Agent uses this tool to query the product catalog. For example, entering “What compute-related products does Alibaba Cloud have” causes the AI Agent to extract keywords and filter the product list accordingly.

Usage Guidance

Specify product keywords in the description. For example, “What compute-related products does Alibaba Cloud have” is better than “What products does Alibaba Cloud have”.
Query results can serve as context for subsequent conversations. For example, first ask “What database products are available”, then follow up with specific operational details for a particular product.

Tool Call Example

Input:

{
  "filter": "compute"
}

Output:

[
  {
    "code": "Ess",
    "name": "Auto Scaling",
    "group": "Elastic Computing",
    "style": "RPC",
    "versions": ["2014-08-28", "2022-02-22"],
    "defaultVersion": "2022-02-22"
  },
  {
    "code": "Ecs",
    "name": "Elastic Compute Service",
    "group": "Elastic Computing",
    "style": "RPC",
    "versions": ["2014-05-26"],
    "defaultVersion": "2014-05-26"
  },
  {
    "code": "Eci",
    "name": "Elastic Container Instance",
    "group": "Elastic Computing",
    "style": "RPC",
    "versions": ["2018-08-08"],
    "defaultVersion": "2018-08-08"
  }
]
// More results returned, only 3 shown here

ListApis

When a user operation involves a specific product but the AI Agent needs to confirm the exact API operation, this tool is used to browse the product API list. For example, entering “Allocate a public IP to an ECS instance” may cause the AI Agent to first query which ECS APIs are relevant, then select the appropriate one to execute.

Usage Guidance

Be as specific as possible about the product and action when describing operational intent. For example, “allocate a public IP to an ECS instance” is better than “allocate IP”.

Tool Call Example

Input:

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

Output:

[
  {
    "summary": "Allocates a public IP address to an ECS instance.",
    "apiName": "AllocatePublicIpAddress",
    "title": "Allocate Public IP"
  },
  {
    "summary": "Attaches a RAM role to one or more ECS instances.",
    "apiName": "AttachInstanceRamRole",
    "title": "Attach RAM Role to Instance"
  }
]
// More results returned, only 2 shown here

GetApiDefinition

When a user request involves an API call, the AI Agent typically first locates the target API through SearchApis or ListApis, then uses this tool to get the API parameter definitions, and finally constructs the correct call. For example, entering “Query ECS instances in Hangzhou region” causes the AI Agent to first locate the DescribeInstances API, then confirm the required parameters through this tool before executing.

Usage Guidance

Be as specific as possible when describing operational intent. Once the AI Agent locates the correct API, it automatically confirms parameters and executes.

Tool Call Example

Input:

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

Output:

{
  "summary": "Queries an instance list based on different request conditions",
  "methods": ["post", "get"],
  "parameters": ["...45 parameters total, omitted here"],
  "responses": {"...": "omitted"},
  "errorCodes": ["...omitted"]
}

SearchApis

When the exact API name is unknown, the AI Agent uses this tool to match the corresponding Alibaba Cloud OpenAPI based on a natural language description. For example, entering “How to view ECS instance monitoring data” causes the AI Agent to search and find relevant monitoring APIs.

Usage Guidance

Include the product name in the description. For example, “query ECS security group rules” is better than “query security groups”.
Break complex requirements into multiple independent questions, each corresponding to a single API operation.
When the API name is already known, specify it directly to the AI Agent (e.g., “use DescribeInstances to query”) to skip the search step.

Tool Call Example

Input:

{
  "prompt": "How to view ECS instance monitoring data",
  "limit": 3
}

Output:

[
  {
    "apiName": "DescribeInstanceMonitorData",
    "code": "Ecs",
    "description": "Calls DescribeInstanceMonitorData to query monitoring information for an ECS instance. Available metrics include vCPU utilization, burstable instance credits, received data traffic, sent data traffic, and average bandwidth.",
    "weight": 0.98,
    "version": "2014-05-26"
  },
  {
    "apiName": "QueryMetricList",
    "code": "Cms",
    "description": "Queries monitoring data for a specified product instance over a period of time.",
    "weight": 0.85,
    "version": "2016-09-22"
  },
  {
    "apiName": "DescribeMetricLast",
    "code": "Cms",
    "description": "Queries the latest monitoring data for a specified metric.",
    "weight": 0.75,
    "version": "2019-01-01"
  }
]

ListProductRegions

When an operation involves region selection, the AI Agent uses this tool to confirm whether the target region supports the product. For example, entering “Can ECS be used in Ulanqab” or “Create an ECS instance in Singapore” causes the AI Agent to first verify region availability.

Usage Guidance

Specify both the product name and target region in the query. For example, “Can ECS be used in Ulanqab” is better than “Can it be used in Ulanqab”.
When multiple regions are involved, specify each one. For example, “Confirm whether ECS is available in Hangzhou, Shanghai, and Singapore”.

Tool Call Example

Input:

{
  "product": "Ecs"
}

Output:

{
  "code": 0,
  "data": {
    "type": "regional",
    "endpoints": [
      {
        "regionId": "us-west-1",
        "regionName": "US (Silicon Valley)",
        "public": "ecs.us-west-1.aliyuncs.com",
        "vpc": "ecs-vpc.us-west-1.aliyuncs.com"
      },
      {
        "regionId": "cn-hangzhou",
        "regionName": "China (Hangzhou)",
        "public": "ecs.cn-hangzhou.aliyuncs.com",
        "vpc": "ecs-vpc.cn-hangzhou.aliyuncs.com"
      }
    ]
  }
}
// More results returned, only 2 shown here

API Execution

GenerateCLICommand

When instructed to “only generate the command without executing” or when the AI Agent needs to preview a command, this tool generates a CLI command string. The AI Agent typically first confirms parameters through GetApiDefinition, then generates the command through this tool, and finally executes it via CallCLI. For example, entering “Generate a command to query ECS instances in Hangzhou” returns a complete command that can be executed in a local terminal.

Usage Guidance

To manually execute a command in the local terminal, request the AI Agent to “only generate the command without executing.” The generated command can be copied and used directly.

Tool Call Example

Input:

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

Output:

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

CallCLI

When the AI Agent knows exactly which API operation to execute, this tool is used to make the call directly. This is the primary tool for API calls in Core Edition. For example, entering “Query running ECS instances in Hangzhou region” causes the AI Agent to construct a CLI command and execute the query.

Usage Guidance

CLI commands executed by this tool run on a remote server and cannot read local files.
Write operations (create, modify, or delete resources) may incur charges. Request the AI Agent to confirm the operation content before execution.

Tool Call Example

Input:

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

Output:

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

Advanced Orchestration

RunScript

When a single API call cannot fulfill the requirement, the AI Agent uses this tool to write scripts for batch operations. For example, entering “Count ECS instances across all regions” or “Check all security groups for high-risk rules” causes the AI Agent to write concurrent scripts to query multiple resources simultaneously.

Usage Guidance

When aggregation, comparison, or batch operations are needed, clearly describe the scope and objective. For example, “Count ECS instances across all regions” or “Check all security groups for high-risk rules”.
Script execution may take seconds to tens of seconds. Wait patiently for the result to return.

Tool Call Example

Input:

{
  "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)}"
}

Output:

{
  "processID": "proc_1f7b02be133a41ee89135fafb833a972",
  "status": "Running",
  "nextAction": "CallGetTask",
  "result": null,
  "waitTimedOut": true,
  "message": "Task not in terminal state. Call AlibabaCloud___GetTask to wait for result.",
  "error": null
}

GetTask

When a RunScript or RunIaC task takes a long time to execute, the AI Agent uses this tool to wait for task completion and retrieve the result. This tool may be triggered during time-consuming operations such as cross-region inspection or Terraform deployment.

Usage Guidance

For time-consuming operations (such as cross-region inspection or batch queries), wait patiently for the result to return.
If manual approval is required, complete the approval process as prompted and the result will continue to return.

Tool Call Example

Input:

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

Output:

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

Infrastructure as Code

GetPresignedUrl

When RunIaC or RunScript tools need to reference external files, the AI Agent uses this tool to generate a temporary upload link. For example, when Terraform code exceeds 64 KB or a script needs to process pre-uploaded data files, the AI Agent first uploads the file through this tool before executing subsequent operations.

Usage Guidance

When large file uploads are involved, it may be necessary to wait for the upload to complete before executing subsequent operations.

RunIaC

When cloud resources need to be created, modified, or destroyed, the AI Agent may use this tool to manage infrastructure via Terraform. For example, entering “Create a VPC in Hangzhou with CIDR 172.16.0.0/16” causes the AI Agent to first generate the resource configuration and preview the changes, then execute the creation after confirmation.

Usage Guidance

When describing resource requirements, specify the region, specifications, and naming clearly. For example, “Create a VPC in Hangzhou with CIDR 172.16.0.0/16, named mcp-demo-vpc”.
Resource changes may require manual approval. Complete the approval process as prompted.

Document Search

SearchDocuments

When a knowledge-based question about product usage, configuration methods, or error troubleshooting is asked, the AI Agent uses this tool to search Alibaba Cloud official documentation. For example, entering “How to optimize Function Compute cold start” or “How to configure OSS Bucket Policy” triggers a search for matching official documents.

Usage Guidance

Including the product name in the query improves search result relevance. For example, “OSS cross-origin configuration” is better than “cross-origin configuration”.
When documentation for a specific product is needed, specify the product name. For example, “Function Compute cold start optimization documentation” is better than “cold start optimization”.

Tool Call Example

Input:

{
  "query": "ECS instance creation",
  "limit": 3
}

Output:

{
  "results": [
    {
      "doc_id": 108442,
      "title": "Creation Methods",
      "url": "https://help.aliyun.com/zh/ecs/user-guide/create-instances/",
      "product": "Elastic Compute Service",
      "content": "This topic describes several methods of creating ECS instances...",
      "website": "cn",
      "language": "zh"
    },
    {
      "doc_id": 151725,
      "title": "ECS Instance Provisioning Methods",
      "url": "https://help.aliyun.com/zh/ecs/user-guide/provisioning-methods-of-ecs-instances",
      "product": "Elastic Compute Service",
      "content": "Manually create one or more instances...",
      "website": "cn",
      "language": "zh"
    }
  ],
  "matched_filters": {
    "product": "",
    "doc_type": null,
    "website": "cn",
    "language": "zh"
  }
}

GetDocument

After the AI Agent locates relevant documents through SearchDocuments, this tool is used to read the full content to answer the question. For example, entering “How to optimize Function Compute cold start?” causes the AI Agent to first search and locate the document, then read the full text and organize the answer.

Usage Guidance

The AI Agent automatically reads and organizes the content after locating documents. The entire process is transparent to the user.

Tool Call Example

Input:

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

Output:

{
  "doc_id": 108442,
  "url": "https://help.aliyun.com/ecs/user-guide/create-instances",
  "title": "Create Instances",
  "product": "ecs",
  "content": "This topic describes several methods of creating ECS instances..."
}

GetDocumentTree

When a user wants to understand the documentation structure of a product, the AI Agent uses this tool to browse the document directory tree. For example, entering “What does the OSS documentation structure look like” or “What user guides does ECS have”.

Usage Guidance

Specify the product name in the query. For example, “What document categories does OSS have” or “What chapters are under the ECS user guide”.

Tool Call Example

Input:

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

Output:

{
  "product": "Elastic Compute Service",
  "website": "cn",
  "language": "zh",
  "children": [
    {"title": "User Guide", "doc_id": 2399509, "url": "https://help.aliyun.com/ecs/user-guide", "children": []},
    {"title": "Developer Reference", "doc_id": 2399511, "url": "https://help.aliyun.com/ecs/developer-reference", "children": []},
    {"title": "Billing", "doc_id": 25396, "children": []},
    {"title": "FAQ", "doc_id": 2983136, "children": []}
  ]
}
// This example uses depth=1, returning only top-level nodes. Set depth to 2 or 3 to include sub-chapters

GrepDocuments

When a question involves specific terms, configuration items, or error codes, the AI Agent uses this tool to perform exact keyword matching within a specified product documentation. For example, entering “What values does InstanceChargeType have in ECS documentation” or “Search for CORS-related content in OSS documentation”.

Usage Guidance

Specify both the product and keyword in the query. For example, “Search for DescribeInstanceAttribute in ECS documentation”.
More precise keywords yield more relevant results. Multiple keywords have an AND relationship.

Tool Call Example

Input:

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

Output:

{
  "product_code": "ecs",
  "pattern": "DescribeInstanceAttribute",
  "matches": [
    {
      "title": "DescribeInstanceAttribute - Query instance attribute information",
      "url": "https://help.aliyun.com/ecs/developer-reference/api-ecs-2014-05-26-describeinstanceattribute",
      "matched_text": "DescribeInstanceTypes - Query instance type information list\nDescribeInstanceAttribute - Query instance attribute information\nModifyInstanceAttribute - Modify instance attribute information",
      "line_no": 986
    }
  ],
  "total": 1,
  "truncated": false,
  "llms_txt_url": "https://help.aliyun.com/zh/ecs/llms.txt"
}

Typical Use Cases

The following scenarios demonstrate complete workflows where multiple tools collaborate to accomplish complex tasks.

Query Security Group Rules

User input:

Check the security group rules in the Hangzhou region

Possible AI Agent tool call chain:

Uses SearchApis to search “Query security group rules associated with ECS instances”, locating the DescribeSecurityGroupAttribute API (confidence 0.98).
Uses GetApiDefinition to confirm the API requires SecurityGroupId and RegionId as mandatory parameters.
Uses CallCLI to execute the query, returning the security group rule list (including direction, protocol, port range, source address, etc.).

Tools involved: SearchApis, GetApiDefinition, CallCLI

Full Call Data

Step 1 - SearchApis Input:

{
  "prompt": "Query security group rules associated with ECS instances",
  "limit": 2
}

Step 1 - SearchApis Output:

[
  {
    "apiName": "DescribeSecurityGroupAttribute",
    "code": "Ecs",
    "description": "Queries detailed information about a specified security group and its associated security group rules.",
    "weight": 0.98,
    "version": "2014-05-26"
  },
  {
    "apiName": "DescribeSecurityGroupReferences",
    "code": "Ecs",
    "description": "Queries the list of other security groups that have been authorized by one or more specified security groups.",
    "weight": 0.75,
    "version": "2014-05-26"
  }
]

Step 3 - CallCLI Input:

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

Step 3 - CallCLI Output (excerpt):

{
  "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"
}

Cross-Region Batch Inspection

User input:

Count the number of ECS instances in Hangzhou, Shanghai, and Beijing regions

Possible AI Agent tool call chain:

Uses RunScript to write a concurrent script that queries instance counts across all three regions simultaneously.
Script execution times out (exceeds 20 seconds), returning a processID.
Uses GetTask to poll the task status and retrieve the result after script execution completes.

Tools involved: RunScript, GetTask

Full Call Data

Step 1 - RunScript Input:

{
  "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 Output (timeout):

{
  "processID": "proc_1f7b02be133a41ee89135fafb833a972",
  "status": "Running",
  "nextAction": "CallGetTask",
  "result": null,
  "waitTimedOut": true,
  "message": "Task not in terminal state. Call AlibabaCloud___GetTask to wait for result."
}

Step 2 - GetTask Input:

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

Step 2 - GetTask Output:

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

Solve Problems Using Documentation

User input:

Function Compute cold start latency is high. What optimization options are available?

Possible AI Agent tool call chain:

Uses SearchDocuments to search “Function Compute cold start optimization”, finding the “Best Practices for Function Compute Cold Start Optimization” document (doc_id: 2513659).
Uses GetDocument to read the full document text and retrieve cold start definitions and optimization strategies.
Uses GetDocumentTree to browse the Function Compute document directory and identify additional performance-related documentation chapters.

Tools involved: SearchDocuments, GetDocument, GetDocumentTree

Full Call Data

Step 1 - SearchDocuments Input:

{
  "query": "Function Compute cold start optimization",
  "limit": 2
}

Step 1 - SearchDocuments Output:

{
  "results": [
    {
      "doc_id": 2513659,
      "title": "Best Practices for Function Compute Cold Start Optimization",
      "url": "https://help.aliyun.com/zh/functioncompute/fc/use-cases/best-practice-for-reducing-cold-start-latencies",
      "product": "Function Compute",
      "content": "This topic describes how to optimize cold start for elastic instances by configuring minimum instance count in Function Compute to improve function performance."
    }
  ]
}

Step 2 - GetDocument Input:

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

Step 2 - GetDocument Output (excerpt):

{
  "doc_id": 2513659,
  "title": "Best Practices for Function Compute Cold Start Optimization",
  "product": "functioncompute",
  "content": "This topic describes how to optimize cold start for elastic instances by configuring minimum instance count in Function Compute to improve function performance.\n\n## What is Cold Start\nFunction Compute uses elastic instances by default, meaning automatic scaling based on requests. When a request is received, the system automatically creates an instance to handle it. Instances are automatically recycled when no requests are pending."
}

Step 3 - GetDocumentTree Input:

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

Step 3 - GetDocumentTree Output (excerpt):

{
  "product": "Function Compute",
  "children": [
    {"title": "Cloud Sandbox (FC Agent Sandbox)", "doc_id": 3030518},
    {"title": "Cloud Functions", "doc_id": 2838600}
  ]
}
// More results returned, only 2 shown here

Prerequisites

Tool Overview

Tool Details

API Discovery

ListProducts

ListApis

GetApiDefinition

SearchApis

ListProductRegions

API Execution

GenerateCLICommand

CallCLI

Advanced Orchestration

RunScript

GetTask

Infrastructure as Code

GetPresignedUrl

RunIaC

Document Search

SearchDocuments

GetDocument

GetDocumentTree

GrepDocuments

Typical Use Cases

Query Security Group Rules

Cross-Region Batch Inspection

Solve Problems Using Documentation

Related Documentation