OpenAPI MCP Server user guide - OpenAPI Explorer - Alibaba Cloud Documentation Center

Model Context Protocol (MCP) is a standardized protocol that enables Large Language Models (LLMs) to interact with external tools and data sources, such as APIs and databases. By centralizing tool-calling logic in a server, MCP allows an LLM to invoke a wide range of functions through a single, unified protocol. This topic describes how to create and use OpenAPI MCP Server to allow LLMs to manage your Alibaba Cloud resources by calling APIs.

Create an MCP server

Note

If you perform this task as a RAM user, you must be granted the required permissions. For more information, see Grant permissions on OpenAPI MCP Server to a RAM user.

Go to the OpenAPI MCP Server page, click the Create an MCP Server tab, and configure the following parameters:

Note

Due to the context length and tool selection limitations of most LLMs, we recommend adding no more than 30 APIs to a single MCP server. If you need to use more APIs, create multiple MCP servers.

Parameter	Description
Name	The name must be 3 to 16 characters in length and can contain only lowercase letters, digits, hyphens (-), and underscores (_). Example: `mcp-demo`.
Document Language	The language for the API descriptions in the generated tools.
OAuth Configuration	Alibaba Cloud Official OAuth: Suitable for local clients, such as AI Coding Assistant Lingma, Cherry Studio, and Cursor. Note A RAM administrator must install and assign the official OpenAPI MCP Server application from the RAM console > OAuth Preview > Third-party Application page. If this is not done, OAuth authorization will fail for your MCP server. For more information, see Install and authorize a third-party application. Custom OAuth: Suitable for self-managed platforms and third-party services, such as Dify, AgentScope, and Claude.
Multi-account MCP	Specify whether to enable the centralized management of MCP servers across multiple accounts. For more information, see Use OpenAPI MCP Server in multi-account scenarios.
List of Cloud Products and APIs	Configure cloud services and their APIs for the MCP server. You can select APIs for only one cloud service at a time. To add APIs from other services, click Add Cloud Products and APIs after confirming your current selection. To add more APIs for a service you have already added, click Add APIs.
Terraform Tools	Integrate Terraform tools into the MCP server through Terraform HCL code. For more information, see Use Terraform tools in OpenAPI MCP Server. Note Terraform tools only support creating resources but not modifying resources.
System Tools	System tools are built-in official tools. If selected, they will be integrated into your MCP server.
Description	Add a description for the MCP server.

Click Create and confirm the risk warning. After the server is created, the system provides the Streamable HTTP endpoint, SSE endpoint, and client configuration details. These are required to connect a client to the MCP server.

Configure the MCP server in a client

You can use the MCP server in common clients, such as Cherry Studio, Cursor, Lingma, and Cline. Refer to the configuration method for your client.

Note

If you are using the MCP server in Dify, see Integrate an OpenAPI MCP server in Dify.

One-click configuration

Note

You must install Cherry Studio or Cursor beforehand.

If you use the MCP server in Cherry Studio or Cursor, you can use the one-click configuration feature to configure it.

Manual configuration

Cherry Studio

Note

Ensure that Cherry Studio is installed.

Configure the model server in Cherry Studio.
1. We recommend using the qwen3-235b-a22b model from Alibaba Cloud Model Studio.
  The API key is generated in the Model Studio console. The API address is https://dashscope.aliyuncs.com/compatible-mode/v1/.
2. After you add the model, edit it to configure capabilities such as networking, inference, and tools.
Configure the MCP server.
1. In the Settings > MCP Servers section, add a server.
2. Configure the MCP server. Enter a name, select Streamable HTTP as the type, and for the URL, enter the Streamable HTTP endpoint that was provided when you created the MCP server.
3. Click Save. Then, the system redirects you to the User Authorization page. Review the authorization information, and click Authorize. For a detailed introduction to OAuth, see OAuth Management.
  Note
  You must grant the required API operation permissions to the RAM user participating in the authorization beforehand. Otherwise, permission errors may occur. For more information, see Grant permissions to a RAM user.
  After authorization is complete, Cherry Studio automatically starts the MCP server.

Cursor

Note

Ensure that Cursor is installed. This example uses the Free Edition of Cursor. You can download the edition that suits your needs.

In the Cursor menu bar, choose File > Preferences > Cursor Settings > Tools & Integrations, and click Add Custom MCP to configure MCP servers.
From the MCP server's details page, copy the client configuration JSON, paste it into the mcp.json file, then press Ctrl+S to save.
Complete the authorization on the User Authorization page. For a detailed introduction to OAuth, see OAuth Management.
Note
You must grant the required API operation permissions to the RAM user participating in the authorization beforehand. Otherwise, permission errors may occur. For more information, see Grant permissions to a RAM user.
You can view the configured MCP server information in Cursor Settings.

AI Coding Assistant Lingma

Note

Ensure that Lingma is installed.

Open the Lingma plug-in and click MCP tools on the introduction page.
In the upper-right corner of the pop-up window, click the + icon and select Add manually.

In the Add MCP Server window, configure the following parameters and click Add.

Name	The name of the MCP server. We recommend that it be the same as the name you entered on the Alibaba Cloud OpenAPI MCP Server page.
Type	Select `STDIO`.
Command	Enter `npx`.
Arguments	The format is `mcp-remote-alibaba-cloud <SSE Endpoint>`. Note Only the SSE Endpoint is supported. Obtain the SSE Endpoint from the details provided after you create the MCP service.

Complete the authorization on the User Authorization page. For a detailed introduction to OAuth, see OAuth Management.
Note
You must grant the required API operation permissions to the RAM user participating in the authorization beforehand. Otherwise, permission errors may occur. For more information, see Grant permissions to a RAM user.
The following figure shows the successful configuration of the MCP server in Lingma:

Cline

Note

Ensure that the Cline plug-in is installed in your IDE. This topic uses VS Code as an example. For more information, see Cline.

Open the Cline plug-in in VS Code and enter your API key.
On the top menu bar, click MCP Servers to configure the MCP server.
Complete the authorization on the User authorization page. For a detailed introduction to OAuth, see OAuth Management.
Note
You must grant the required API operation permissions to the RAM user participating in the authorization beforehand. Otherwise, permission errors may occur. For more information, see Grant permissions to a RAM user.
After authorization is complete, the configuration is successful if the newly configured MCP server appears in the MCP Servers section at the bottom of Cline.

Inspector

Note

This section just provides a brief introduction. For more information, see Inspector.
Your Node.js version must be 22.7.5 or later.

In the terminal, run the following command to start Inspector. After it starts, you can access it at http://localhost:6274 by default.
```
npx @modelcontextprotocol/inspector
```
In the left-side navigation pane of the MCP Inspector client, select a transport type. This example uses Streamable HTTP. In the URL field, enter the Streamable HTTP endpoint that was generated when you created the MCP server, and click Connect.
Complete the authorization on the User Authorization page. For a detailed introduction to OAuth, see OAuth Management.
Note
You must grant the required API operation permissions to the RAM user participating in the authorization beforehand. Otherwise, permission errors may occur. For more information, see Grant permissions to a RAM user.
After authorization is complete, you can see the MCP server's information on the Tools tab.
You can click any tool to view its details on the right. You can also set parameters to run the tool.

Use the MCP server

After configuration, you can use the MCP server to manage your cloud resources. For more information, see the "More methods to integrate MCP servers" section in this topic.

Cherry Studio

From the text box menu, select the MCP server.
Test the MCP server. For example, you can query the ECS instances in a region:
```
Please query the ECS instances in region cn-chengdu and set x_mcp_region_id to cn-chengdu.
```
Note
The result should be accurate if the MCP server selects the correct API and configures the request parameters properly. If an error occurs, you can try changing the MCP server's configurations to resolve it.

Cursor

Select the model and API key. Because Cursor has specific requirements for LLM providers, see Supported providers for more information. This example uses the default values.
In the Cursor dialog box, click Add Context and select your MCP server.
In the dialog box, enter a natural language query to test your MCP server. For example, enter "Please query the number of ECS instances in the China (Chengdu) region and show only the instance count" and press Enter. When prompted, click Run tool to proceed.
View the execution result. The result should be accurate if the MCP server selects the correct API and configures the request parameters properly. If an error occurs, you can try changing the MCP server's configurations to resolve it.

Lingma

In Lingma, select a model from the Agent drop-down list and enter a prompt. For example, to query the ECS instances in the China (Chengdu) region, you must set x_mcp_region_id to the region ID.
Follow the prompts in Lingma to execute the task.
View the result. The result should be accurate if the MCP server selects the correct API and configures the request parameters properly. If an error occurs, you can try changing the MCP server's configurations to resolve it.

Cline

In the Cline dialog window, enter a natural language query to test your MCP server. For example, enter "Please query the number of ECS instances in the China (Chengdu) region."
The figure above shows that Cline uses the configured MCP server and selects the DescribeInstances API. The value for the RegionId parameter is also taken from the input.
Review the execution result. The result should be accurate if the MCP server selects the correct API and configures the request parameters properly. If an error occurs, you can try changing the MCP server's configurations to resolve it.

Modify the MCP server's configurations to enhance output accuracy

If an LLM provides inaccurate responses based on the MCP server, you can modify the API overview, description, or request parameter descriptions on the MCP server's details page to improve its understanding of API features. The following examples show how to modify the MCP server's configurations.

Example 1: Errors or inaccurate data when operating on resources outside the China (Hangzhou) region

MCP servers use x_mcp_region_id to switch endpoints. If an LLM fails to understand from your input that it must pass x_mcp_region_id, it operates on resources in the China (Hangzhou) region by default.

You can resolve this issue in one of two ways:

Explicitly tell the LLM the desired value of x_mcp_region_id in your prompt.

Query the ECS instances in the China (Qingdao) region and set x_mcp_region_id to cn-qingdao.

Adjust the API overview or the RegionId parameter's description on the MCP server's details page.
For example, you can add "Pass the user-specified region to x_mcp_region_id" to the API overview. Alternatively, you can add "If the RegionId parameter is specified, it must be passed along with x_mcp_region_id" to the RegionId description.
Procedure
1. Go to the View MCP Servers page, find the desired MCP server and click Edit in the Actions column.
2. Select the desired API and click Edit in the Actions column.
3. Modify the API overview, request description, and parameter descriptions.
4. After you save the changes, disconnect from the MCP server on the client and then reconnect for the changes to take effect.

Example 2: Delete optional parameters from an API

API documents include parameters for all possible use cases, but some optional parameters might not be necessary in most use cases. You can delete these optional parameters on the MCP server. When passing parameters, the LLM will not access the deleted parameters. This reduces the model's error rate and decreases token usage.

Access control for MCP servers

An AI agent that integrates with the OpenAPI MCP Server has no inherent identity or permissions to access Alibaba Cloud. It acts as a proxy, performing operations on behalf of a user. The workflow is initiated by a client through an OAuth flow. After the user grants consent, the AI agent receives temporary credentials. All subsequent operations are performed under the user's identity and are constrained by the user's permissions. This ensures adherence to the principle of least privilege and provides clear auditability, as all actions are logged in ActionTrail under the authorizing user's identity.

Applicable agents : Cherry Studio, Lingma, Qwen Code, Cursor, Claude Code, Dify, AgentScope, and LangGraph.

FAQ

1. Can the MCP client call all APIs defined in the toolset?

Not necessarily. The success of an API call depends on the permissions of the RAM user who authorized the client. If the user lacks permission to call a specific API, the LLM's attempt to call it will also fail.

To resolve this, a RAM administrator must grant the necessary permissions to the RAM user. For more information, see Grant permissions to a RAM user.

Important

To prevent accidental data loss, avoid granting RAM users permissions for destructive actions, such as deleting resources. An LLM could misunderstand a prompt and invoke a deletion API, which could negatively impact your business.

2. When I logged as a RAM user, why did I receive a "permission denied" error when creating an MCP server?

Ask a RAM administrator to attach the AliyunOpenAPIMCPServerFullAccess policy to your RAM user account. For more information, see Grant permissions to a RAM user.
Alternatively, ask a RAM administrator to attach a custom policy to your RAM user account:
1. The RAM administrator can create a custom policy in the RAM console. For more information, see Create a custom policy.
  The policy document is as follows:
  Access policy for an MCP server
  This policy grants permissions to create, update, query, and delete an MCP server. It also grants permissions to query the MCP server's system tools.
```
{
  "Version": "1",
  "Statement": [
    {
      "Action": [
        "openapiexplorer:*Mcp*",
        "ram:*Application*"
      ],
      "Resource": "*",
      "Effect": "Allow"
    }
  ]
}
```
2. Ask a RAM administrator to attach the custom policy to your RAM user account. For more information, see Grant permissions to a RAM user.

3. If an MCP server's endpoint is exposed, can anyone use it?

No. Even if an endpoint is exposed, it cannot be used by unauthorized parties. When a client connects to the endpoint, it initiates an OAuth flow that requires the user to authenticate and grant consent. The system then validates that the user's account matches the account that owns the MCP server. Access is granted only if the accounts match.

More ways to integrate MCP

Integrate with Dify by using a custom OAuth application configuration. This is supported in Dify 1.8.0 and later. For more information, see Integrate an OpenAPI MCP server in Dify.
Integrate with agents by using the official MCP SDK to handle the OAuth flow. For more information, see Integrate an OpenAPI MCP server with an AI agent.