OpenAPI MCP Server - Call Alibaba Cloud APIs with natural language via MCP - OpenAPI Explorer

Choose a usage method

Choose an edition

Two editions are available:

Comparison	Core Edition	Custom Edition
Onboarding speed	Fast: Get the endpoint directly after logging on to the console.	Medium: Create a service and select APIs.
API coverage	Covers all Alibaba Cloud OpenAPI.	Covers only selected APIs.
API matching method	The LLM matches and calls APIs through semantic search. Ambiguous prompts may match unintended APIs.	Selected APIs are directly exposed as Tools, which the LLM can call without searching.
Tuning capability	Not supported	Supported: Modify API descriptions and parameters.
Number of services	One per account.	Create multiple services based on different scenarios.
Use cases	Quick start, exploratory operations, and cross-product integration.	Fixed business processes, clear API requirements, and scenarios that require tuning.

Use the Core Edition for a quick start or for operations that span multiple cloud products.
Use the Custom Edition if you have already identified the required APIs and want the LLM to call them directly without semantic matching.

Choose an authentication method

MCP Server supports two authentication methods:

OAuth authentication (interactive authentication): Automatically redirects to a browser for logon. You need to log on again after the token expires.
Static credential authentication: Connects using a static credential after a one-time pre-check. No browser is required.

Comparison	OAuth authentication (interactive authentication)	AK static credential authentication
Use cases	Desktop clients with browser interaction, daily development, and exploratory operations.	Servers without a graphical user interface (GUI), CI/CD pipelines, and unattended AI Agent integration.
Authorization method	Browser redirection for user logon and authorization.	Pass the AccessKey (AK) through an environment variable. No browser redirection is required.
Permission identity	The identity of the user who triggers the authorization.	The identity of the RAM user corresponding to the AK.
Security	Tokens are valid for a short period, providing higher security.	Long-term static credentials pose security risks that require attention.

Prerequisites

Complete these preparations based on your chosen authentication method:

OAuth authentication

Suitable for desktop clients with browser interaction. Short-term tokens provide higher security.

You have an Alibaba Cloud account. If you use a RAM user, grant the required permissions. Grant permissions to a RAM user to operate MCP Server.
Use an administrator account to go to the RAM console - OAuth Applications - Third-party Applications page. Install and assign the official OpenAPI MCP Server application. Otherwise, OAuth authorization fails. Install and authorize a third-party application.

Static credential authentication

Suitable for CI/CD pipelines, CLI environments, and AI Agents without browser access. Supports passing AccessKey (AK) credentials through environment variables. If you are logged on to Alibaba Cloud CLI, the proxy automatically reuses the existing credentials.

You have installed Python (3.13 or later) and uv.
You have registered an Alibaba Cloud account and created an AK. The RAM user or RAM role corresponding to the AK has been granted the AliyunOpenAPIMCPServerStaticCredentialAccess system policy. You can go to the RAM console to grant this policy to the RAM user.
Before the first use, run the pre-check (application authorization) command to check if the account has completed application authorization. If not, the command opens a browser to guide you through the authorization. The pre-check is effective for the Alibaba Cloud account and can be run on any device with a browser. It does not need to be the same machine where you use MCP: .uvx alibabacloud.mcp-proxy@latest --server-url <MCP connection address> pre-check --site-type INTL.

Get the MCP service endpoint

Client configuration is the same for both editions. Only the endpoint source differs.

Core Edition

After you log on, the system assigns an endpoint for the Core Edition that covers all Alibaba Cloud OpenAPIs.

Log on to the Alibaba Cloud OpenAPI MCP Service console.
In the navigation pane on the left, click the Core tab. The page displays the Streamable HTTP Endpoint and SSE Endpoint.
To modify OAuth or advanced settings, click the corresponding Modify button:
- Multi-account MCP: Manage MCP Server across multiple accounts. Use OpenAPI MCP Server in a multi-account scenario.
- Public network configuration: Enable public network access for local development, cross-region collaboration, or external system integration.
- Custom VPC whitelist: Suitable for scenarios with strict network security requirements.

Custom Edition

Create an MCP service and select the required APIs. Each selected API is exposed as an MCP Tool that the LLM can call without semantic search.

Log on to the Alibaba Cloud OpenAPI MCP Service console.
In the navigation pane on the left, click Custom > Create to go to the MCP configuration page.

Fill in the following information:
- Name: 3 to 16 characters long. Supports lowercase letters, digits, underscores (_), and hyphens (-). For example, mcp-demo.
- Document language: Select the language for the API descriptions in the Tools.
- OAuth configuration:
  - Alibaba Cloud official OAuth: Suitable for local clients, such as Lingma, Cherry Studio, and Cursor.
  - Custom OAuth: Suitable for self-built platforms or third-party services, such as self-deployed Dify, AgentScope, and Claude Web/Mobile.
- Multi-account MCP: Manage MCP Server across multiple accounts. Use OpenAPI MCP Server in a multi-account scenario.
- Cloud products and API list: Configure API Tools for the MCP service.
- Terraform Tools: Define MCP Tools using Terraform HCL code. Supports resource creation only. Use Terraform Tools in OpenAPI MCP Server.
- System Tools: Official preset Tools that are automatically integrated into the MCP service when selected.
- MCP instructions: Used to prompt the LLM on how to use this MCP. The client must support the Instructions field of the MCP standard protocol.
- Remarks: Add a description for the MCP service.
Click Create and confirm the risk warning. After the service is created, the page displays the Streamable HTTP Endpoint and SSE Endpoint.

Note

Select no more than 30 APIs per MCP Server. Create multiple servers if you need more.

If you use MCP in a VPC environment, prioritize using the VPC endpoint displayed on the page.

Configure the client

After getting the service endpoint, configure the connection in your client. This configuration applies to both the Core and Custom editions. The Alibaba Cloud OpenAPI MCP Service console provides configuration templates for common clients such as Cherry Studio, Lingma/Cursor/Windsurf/VSCode, Claude Code, and Codex. MCP has broad compatibility. Other clients or programs that support the protocol can also be configured as needed.

Two authentication methods are supported:

OAuth authentication (interactive authentication): Authorizes automatically through browser redirection.
Static credential authentication: Passes the AK through an environment variable or uses Alibaba Cloud CLI credentials.

Important

An AK is a long-term static credential. If leaked, it can be exploited continuously. Follow these security practices (Create an AccessKey):

Do not use the AK of a root account. Use the AK of a RAM user and grant only the minimum required permissions.
Do not hard-code the AK into version-controlled files such as mcp.json. Inject it through environment variables or a key management service.
Rotate your AKs regularly to reduce the risk of credential leakage.

OAuth authentication (default)

OAuth is the default method. The client opens a local browser for user authorization. Suitable for desktop clients and daily development.

Log on to the Alibaba Cloud OpenAPI MCP Service console. Go to the MCP service endpoint page for the Core or Custom edition. Click One-click Configuration. Select OAuth authentication (default). Then, select the tab for your client and follow the configuration template. If a user authorization page appears in the browser during configuration, click Authorize.

Cherry Studio

Prerequisites: You have installed Cherry Studio.

Complete the configuration in one of the following ways:

One-click configuration: On the console's configuration template page, click One-click configuration for Cherry Studio and follow the prompts.
Manual configuration: Go to Settings > MCP Server in Cherry Studio. Select Add > Quick Create. Enter a name, set Type to Streamable HTTP, and enter the Streamable HTTP Endpoint address for the URL. Alternatively, select Import from JSON and paste the configuration JSON from the page:

After saving, the browser automatically redirects to the Alibaba Cloud OAuth authorization page. The MCP service starts after you complete the authorization.

Lingma/Cursor/Windsurf/VSCode

Prerequisites: You have installed Node.js and npm.

Complete the configuration in one of the following ways:

One-click configuration (Cursor only): On the console's configuration template page, click One-click configuration for Cursor and follow the prompts.
Manual configuration: Paste the configuration JSON from the console page into the client's MCP configuration file.

Configuration methods for each client:

Lingma: Open the Lingma plug-in. On the introduction page, click MCP Tool. In the pop-up window, click + in the upper-right corner and select manual addition. Enter a custom name, set Type to STDIO, set Command to npx, and set Parameters to mcp-remote-alibaba-cloud <Streamable HTTP Endpoint>.
Cursor: Go to File > Preferences > Cursor Settings > Tools & Integrations. Click Add Custom MCP. Paste the JSON into the mcp.json file and save it. The configuration file is usually located at ~/.cursor/mcp.json or .cursor/mcp.json in the project root directory.
Windsurf: Paste the JSON into ~/.windsurf/mcp.json or .windsurf/mcp.json in the project root directory.
VSCode: Search for MCP in the settings and add the configuration as prompted.

After saving the configuration, you must complete OAuth authorization through a browser on the first use. If the browser does not open automatically, restart the application.

Claude Code

Prerequisites: You have installed Claude Code.

Run the following command in your terminal to add the MCP server. Replace <Streamable HTTP Endpoint> with the actual address from the console:

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

Run the following command to query the added MCPs:

claude mcp list

During configuration or use, if a user authorization page appears in the browser, click Authorize.

Codex

Prerequisites: You have installed the Codex CLI.

Run the following command in your terminal to add the MCP server. Replace <Streamable HTTP Endpoint> with the actual address from the console:

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

Run the following command to query the added MCPs:

codex mcp list

During configuration or use, if a user authorization page appears in the browser, click Authorize.

Static credential authentication

Static credential authentication uses the local proxy alibabacloud.mcp-proxy without browser redirection. Suitable for automated pipelines, CLI-only environments, and unattended AI Agent integrations.

Log on to the Alibaba Cloud OpenAPI MCP Service console. Go to the MCP service endpoint page for the Core or Custom edition. Click One-click Configuration. Select Static credential authentication. Then, select the tab for your client and follow the configuration template.

Note

If you are already logged on to Alibaba Cloud CLI (aliyun configure), the proxy automatically reads the CLI credentials. You do not need to set the env environment variable in the configuration.

Cherry Studio

Prerequisites:

You have installed Cherry Studio, Python (3.13 or later), and uv.
The AccessKey has the AliyunOpenAPIMCPServerStaticCredentialAccess system permission.
Before the first use, you must run the pre-check command from the console to check the account's authorization status. This command can be run on any device with a browser and does not need to be the same machine where the proxy is running.

Complete the configuration in one of the following ways:

In Cherry Studio, paste the configuration by going to Settings > MCP Server > Add > Import from JSON. Be sure to replace Access Key ID/Secret with your actual keys. If you have configured Alibaba Cloud CLI, you can remove the env field to reuse the local credentials.

After configuration, restart Cherry Studio and send a test request (such as querying the list of ECS instances in a region) to confirm that the API is called correctly. This indicates that static credential authentication is successful.

Lingma/Cursor/Windsurf/VSCode

Prerequisites:

You have installed Lingma/Cursor/Windsurf/VSCode, Python (3.13 or later), and uv.
The AccessKey has the AliyunOpenAPIMCPServerStaticCredentialAccess system permission.
Before the first use, you must run the pre-check command from the console to check the account's authorization status. This command can be run on any device with a browser and does not need to be the same machine where the proxy is running.

Configuration methods for each client:

Lingma: Manually add in the plug-in's MCP tool page. Set Type to STDIO, set Command to uvx, and set Parameters to alibabacloud.mcp-proxy@latest --server-url <Streamable HTTP Endpoint> --site-type INTL. Add ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET to the environment variables.
Cursor: Paste the JSON into ~/.cursor/mcp.json or .cursor/mcp.json in the project root directory. Replace the AK ID and Secret.
Windsurf: Paste the JSON into ~/.windsurf/mcp.json or .windsurf/mcp.json in the project root directory. Replace the AK ID and Secret.
VSCode: Search for MCP in the settings and add the configuration as prompted.

If you have configured Alibaba Cloud CLI, you can remove the environment variable configuration to reuse the local credentials.

After configuration, save and restart the client. Send a test request to confirm that the API is called correctly. This indicates that static credential authentication is successful.

Claude Code

Prerequisites:

You have installed Claude Code, Python (3.13 or later), and uv.
The AccessKey has the AliyunOpenAPIMCPServerStaticCredentialAccess system permission.
Before the first use, you must run the pre-check command from the console to check the account's authorization status. This command can be run on any device with a browser and does not need to be the same machine where the proxy is running.

Complete the configuration in one of the following ways:

Run the following command in your terminal to add the MCP server. Replace <Access Key ID>, <Access Key Secret>, and <Streamable HTTP Endpoint> with the actual values.

If you have configured Alibaba Cloud CLI, you can remove the environment variable configuration to reuse the local credentials.

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

Run the following command to query the added MCPs:

claude mcp list

Codex

Prerequisites:

You have installed Codex, Python (3.13 or later), and uv.
The AccessKey has the AliyunOpenAPIMCPServerStaticCredentialAccess system permission.
Before the first use, you must run the pre-check command from the console to check the account's authorization status. This command can be run on any device with a browser and does not need to be the same machine where the proxy is running.

Complete the configuration in one of the following ways:

Run the following command in your terminal to add the MCP server. Replace <Access Key ID>, <Access Key Secret>, and <Streamable HTTP Endpoint> with the actual values.

If you have configured Alibaba Cloud CLI, you can remove the environment variable configuration to reuse the local credentials.

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

Run the following command to query the added MCPs:

codex mcp list

Use MCP

After configuration, use natural language in the client to operate cloud resources. More ways to integrate MCP.

Core Edition: Describe your needs in natural language. The LLM searches for matching APIs, retrieves parameter definitions, and executes calls automatically. For example, "Help me query ECS instances in the Hangzhou region" triggers the DescribeInstances API.
Custom Edition: Configured APIs are exposed directly as Tools, eliminating search and shortening the call path. This ensures the LLM calls the intended API when multiple APIs have similar functions.

Cherry Studio

Select the MCP server from the menu in the text input box.
Test the MCP function. For example, to query the number of ECS instances in a specific region:
```
Please help me query the list of ECS instances with regionId cn-chengdu and set x_mcp_region_id.
```
Note
If the API selection or parameter settings are incorrect, try optimizing the prompt. For the Custom Edition, you can also use MCP tuning to resolve the issue.

Cursor

Select the Model and API Key. Because Cursor has requirements for LLM providers (see Supported providers), refer to its documentation when selecting the Model and API Key. This example uses the default values.
In the Cursor dialog box, click Add Context and select the MCP Server.
In the dialog box, enter a natural language query to test the MCP function, for example, "Please help me query the number of ECS instances in the Chengdu region, and only show the instance count." Press Enter to send. Follow the prompt and click Run tool to continue.
View the MCP execution result. If the API selection or parameter settings are incorrect, try optimizing the prompt. For the Custom Edition, you can also use MCP tuning to resolve the issue.

Lingma

In Lingma, select AI Agent and enter your prompt, for example, to query the list of ECS instances in the Chengdu region and set x_mcp_region_id.
Follow the prompts from Lingma to execute the MCP tool.
View the result. If the API selection or parameter settings are incorrect, try optimizing the prompt. For the Custom Edition, you can also use MCP tuning to resolve the issue.

Cline

In the Cline dialog box, enter a natural language query to test the MCP function, for example, "Please help me query the number of ECS instances in the Chengdu region."

Cline automatically selects the DescribeInstances tool from the configured MCP Server and extracts the RegionId parameter value from the input.
View the MCP execution result. If the API selection or parameter settings are incorrect, try optimizing the prompt. For the Custom Edition, you can also use MCP tuning to resolve the issue.

MCP tuning (Custom Edition only)

The Core Edition handles API search and calls automatically through built-in tools and does not support tuning.

When the LLM selects the wrong API or passes incorrect parameters, modify the API summary, description, or request parameter descriptions on the server side to improve accuracy.

Example 1: Errors or inaccurate data may occur when operating on resources in regions other than cn-hangzhou

MCP switches the Endpoint using x_mcp_region_id. If the LLM fails to understand from the input that it needs to pass x_mcp_region_id, it will operate on resources in the cn-hangzhou region by default.

You can resolve this in one of two ways:

Explicitly instruct the LLM to set x_mcp_region_id in your query.

Please help me query the list of ECS instances with regionId cn-qingdao and set x_mcp_region_id.

Adjust the API summary or the description of the RegionId request parameter on the MCP server.

For example, add "Pass the region described by the user to x_mcp_region_id" to the API summary, or add "If the RegionId parameter exists, it must be passed along with x_mcp_region_id" to the RegionId description.

Steps:
1. Go to the Custom API MCP SERVER page. In the Actions column of the target MCP service, click Edit.
2. Select the API to be tuned and click Edit in its Actions column.
3. Modify the summary, API request description, or API parameter descriptions.
4. After saving the changes, disconnect and reconnect the MCP service in the client for the changes to take effect.

Example 2: Remove some optional parameters from the API

Some optional parameters are unnecessary in certain scenarios. Remove them from the MCP server to reduce errors and token consumption.

MCP access control

After an AI Agent is integrated with OpenAPI MCP Server, the Agent itself does not have permission to access cloud resources. It must trigger an authorization flow initiated by the user to operate as a proxy for the user's identity. For example, a client can initiate an OAuth flow. After the user grants authorization, the Agent obtains temporary access permissions. All operations require user authorization. The tasks the Agent can perform are limited by the user's own permissions, which implements the principle of least privilege. In addition, audit logs record the identity of the user who actually performed the operation.

Use cases: Client-side Agents such as CherryStudio, Lingma, Qwen Code, Cursor, Claude Code, Dify, AgentScope, and LangGraph, or scenarios that require proxying a user's identity.

More ways to integrate MCP

Integrate with OpenAPI MCP Server in Dify by configuring a custom OAuth application. Integrate OpenAPI MCP Server in Dify.
In a custom Agent, complete the OAuth authorization flow and integrate with Agent frameworks using the official MCP SDK. Integrate OpenAPI MCP Server in an Agent.

FAQ

Can all APIs in Tools be called from the MCP client?

Not necessarily. Whether a call succeeds depends on the permissions of the RAM user who initiated the OAuth authorization or the RAM user corresponding to the AK. If the RAM user lacks permission for a specific API, the LLM cannot call it either.

Grant the necessary API permissions to the RAM user. Manage RAM user permissions.

Important

To prevent the LLM from mistakenly calling resource-deletion APIs, do not grant delete permissions to the RAM user.

Permission denied error when creating an MCP Server with a RAM user

Solution:

Grant the AliyunOpenAPIMCPServerFullAccess system policy to the RAM user. Manage RAM user permissions.
Grant a custom policy to the RAM user:
1. Use an administrator account to create a custom policy in the RAM console. Create a custom policy.
  
  Policy content:
  Click to view the policy for MCP Server operations
  This policy includes permissions to create, update, query, and delete MCP Servers, as well as query MCP system tools.
```
{
  "Version": "1",
  "Statement": [
    {
      "Action": [
        "openapiexplorer:*Mcp*",
        "ram:*Application*"
      ],
      "Resource": "*",
      "Effect": "Allow"
    }
  ]
}
```
2. Grant this custom policy to the target RAM user. Manage RAM user permissions.

If an MCP Server connection endpoint is exposed, can it be used by others?

No. OAuth authentication triggers an authorization flow requiring user logon — the system verifies that the authorizing user's root account matches the MCP Server's root account. Static credential authentication is scoped to the RAM user's permissions, preventing unauthorized access.

How to choose between static credential authentication and OAuth authentication?

Choose based on your environment:

OAuth authentication: Desktop clients with browser interaction. Short-term tokens provide higher security. Recommended for daily development and exploratory operations.
AK static credential authentication: Automated pipelines, CLI-only servers, and unattended AI Agent integration. Permissions are tied to the RAM identity of the AK — you are responsible for credential security.

What should I do if an AK Secret is accidentally leaked?

Immediately disable or delete the AccessKey in the RAM console.
Create a new AccessKey and update the client configuration.
Check the ActionTrail audit logs for the period of the leak to see if there were any abnormal calls.