All Products
Search
Document Center

OpenAPI Explorer:OpenAPI MCP Server User Guide

Last Updated:Sep 25, 2025

Model Context Protocol (MCP) is a standardized interface protocol that connects large models with external tools or data sources. Similar to a USB-C port, it allows various tools, such as databases and APIs, to connect to large models uniformly without requiring separate adapter code. MCP uses a client-server architecture to centralize tool-calling logic on the server. The large model only needs to make requests through a unified protocol to call various functions flexibly. Alibaba Cloud OpenAPI Explorer has launched the OpenAPI MCP Server, which supports calling APIs to manage cloud resources within large models. This topic describes how to create and use an MCP service.

Create an MCP service

Note

If you are using a Resource Access Management (RAM) user that does not have administrator permissions, you must grant the necessary permissions to the RAM user. For more information, see Granting permissions to a RAM user to operate an MCP Server.

  1. Go to the Alibaba Cloud OpenAPI MCP service page, click the Create MCP Service tab, and enter the following information:

    Note

    Because of limitations in the context length and tool selection precision of large models, the number of APIs that you can select for an MCP Server is also constrained. You can select a maximum of 30 APIs for a single MCP Server. To use more APIs, you can create multiple MCP Servers.

    Configuration Item

    Description

    Name

    3-16 characters, containing only a-z0-9_- characters. For example, mcp-demo.

    Document Language

    Select the language for the API descriptions in the Tools.

    OAuth Configuration

    Official Alibaba Cloud OAuth: Suitable for local clients, such as Tongyi Lingma, Cherry Studio, and Cursor.

    Note

    Using an administrator account, go to RAM console > OAuth Applications > Third-party Applications to install and assign the official OpenAPI MCP Server application. Otherwise, you cannot perform OAuth authorization for the MCP services that you create. For more information, see Install and authorize third-party applications.

    Custom OAuth: Suitable for self-built platforms and third-party services, such as self-deployed Dify, AgentScope, and Claude Web/Mobile.

    Multi-account MCP

    Centrally manage MCP Servers in a multi-account scenario. For more information, see How to use OpenAPI MCP Server in a multi-account scenario.

    Alibaba Cloud Services and API List

    Configure API Tools for the MCP service.

    • You can select APIs for only one Alibaba Cloud service at a time. To select APIs for multiple Alibaba Cloud services, click Add Alibaba Cloud Service and API after confirming your selection.

    • To add more APIs for a selected Alibaba Cloud service, click Add API.

    Terraform Tools

    Define MCP Tools using Terraform HCL code. For more information, see How to use Terraform Tools in OpenAPI MCP Server.

    Note

    Terraform Tools only support resource creation, not resource modification.

    System Tools

    System Tools are official, preset tools. After you select them, System Tools are integrated into the MCP service.

    Remarks

    Add a description for the MCP service.

    image

  2. Click Create and confirm the Risk Prompt. After creation, you will receive the Streamable HTTP Endpoint, SSE Endpoint, and MCP client configuration, which are required to connect the client to the MCP service.

Configure the MCP

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

Note

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

One-click configuration

Note

You must install Cherry Studio or Cursor beforehand.

If you use the MCP in Cherry Studio or Cursor, you can use the official One-click configuration feature to configure the MCP.

Manual configuration

Cherry Studio

Note

Ensure that Cherry Studio is installed.

  1. Configure the model service in Cherry Studio.

    1. Use the `qwen3-235b-a22b` model from Alibaba Cloud Model Studio.

      The API key is created 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.

  2. Configure the MCP server.

    1. Add a server in Settings > MCP 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 service.

    3. Clicking Save redirects you to the Alibaba Cloud OAuth authorization page. Review the authorization information, and then click Authorize. For more information about 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.

      image

      After authorization is complete, Cherry Studio automatically starts the MCP service.

Cursor

Note

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

  1. In the Cursor menu bar, go to File > Preferences > Cursor Settings > Tools & Integrations, and then click Add Custom MCP to configure MCP Servers.

    image

  2. Copy the content from the MCP Server configuration method, paste it into the `mcp.json` file, and press `Ctrl+S` to save.

    image

  3. Complete the authorization on the OAuth page. For more information about 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.

    image

  4. You can view the configured MCP Server information in Cursor Settings.

    image

Tongyi Lingma

Note

Ensure that Tongyi Lingma is installed.

  1. Open the Tongyi Lingma plug-in and click MCP Tools on the introduction page.

  2. In the upper-right corner of the pop-up window, click the + icon and select Manual Add.

    image

  3. In the Add MCP Service window, enter the following information. After you enter the parameters, click Add Now.

    Name

    The name of the MCP service. We recommend that it be the same as the virtual MCP service name.

    Type

    Fixed to STDIO.

    Command

    Fixed to npx.

    Parameters

    The format is mcp-remote-alibaba-cloud <SSE Endpoint>.

    Note

    Only the SSE Endpoint is supported. You can obtain the SSE Endpoint from the results returned when you created the virtual MCP service.

  4. Complete the authorization on the OAuth page. For more information about 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.

    image

    The following figure shows the result of enabling the MCP in Tongyi Lingma:

    image

Cline

Note

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

  1. Open the Cline plug-in in VS Code and enter your API key.

  2. On the Cline top menu bar, click MCP Servers to configure the MCP Server.

    image

    image

  3. Complete the authorization on the OAuth page. For more information about 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.

    image

  4. 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.

    image

Inspector

Note

  • This section provides a brief introduction. For more information about Inspector, see Inspector.

  • Your Node.js version must be 22.7.5 or later.

  1. In the terminal, run the following command to start Inspector. After the service starts, you can access it at http://localhost:6274 by default.

    npx @modelcontextprotocol/inspector

  2. On the left side of the Inspector UI, select a Transport Type. This example uses Streamable HTTP. In the URL field, enter the Streamable HTTP Endpoint that was provided when you created the MCP service, and then click Connect.

    image

  3. Complete the authorization on the OAuth page. For more information about 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.

    image

  4. After authorization is complete, you can see the tool information for the MCP Server on the Inspector UI.

  5. You can click any tool to view its details on the right. You can also set parameters to call the tool.

Use MCP

After configuration, you can use the MCP to manage your cloud resources. For more information, see More ways to integrate the MCP.

Cherry Studio

  1. From the text input box menu, select the MCP server.

  2. Test the MCP feature. For example, you can query the number of ECS instances in a region:

    Please query the list of ECS instances in region cn-chengdu and set x_mcp_region_id.

    Note

    The result is accurate if the MCP selects the correct API and the request parameters are configured correctly. If an error occurs, you can try tuning the MCP to resolve the issue.

Cursor

  1. Select the model and API key. Because Cursor has specific requirements for Large Language Model (LLM) providers, see Supported providers for more information. This example uses the default values.

  2. In the Cursor dialog box, click Add Context and select MCP Server.

    image

  3. In the dialog box, enter a natural language query to test the MCP feature. For example, enter "Please query the number of ECS instances in the Chengdu region and show only the instance count." and press Enter. When prompted, click Run tool to proceed.

    image

  4. View the MCP execution result. The result is accurate if the MCP selects the correct API and the request parameters are configured correctly. If an error occurs, you can try tuning the MCP to resolve the issue.

    image

Tongyi Lingma

  1. In Tongyi Lingma, select Agent and enter a prompt. For example, to query the list of ECS instances in the Chengdu region, you must set `x_mcp_region_id`.

    image

  2. Follow the prompts in Tongyi Lingma to execute the MCP tool.

    image

  3. View the result. The result is accurate if the correct MCP tool is selected and the API request parameters are configured correctly. If an error occurs, you can try tuning the MCP to resolve the error.

    image

Cline

  1. In the Cline dialog window, enter a natural language query to test the MCP feature. For example, enter "Please query the number of ECS instances in the Chengdu region."

    image

    The figure shows that Cline uses the configured MCP Server and selects the `DescribeInstances` tool. The value for the `RegionId` parameter is also taken from the input.

  2. Review the MCP execution result. The result is accurate if the MCP selects the correct API and the request parameters are configured correctly. If an error occurs, you can try tuning the MCP to resolve the issue.

    image

MCP tuning

If a large model provides inaccurate responses based on the MCP, you can improve its understanding of API features. You can modify the API overview, description, or request parameter descriptions on the server. The following examples show how to tune the MCP.

Example 1: Errors or inaccurate data when operating on resources outside the cn-hangzhou region

The MCP uses `x_mcp_region_id` to switch endpoints. If the large model fails to understand from your input that it must pass `x_mcp_region_id`, it operates on resources in the `cn-hangzhou` region by default.

You can resolve this issue in one of two ways:

  • Explicitly tell the large model to set `x_mcp_region_id` in your prompt.

    Query the list of ECS instances for regionId cn-qingdao, and set x_mcp_region_id.

  • Adjust the API overview or the `RegionId` parameter description on the MCP server.

    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 present, it must be passed along with `x_mcp_region_id`" to the `RegionId` description.

    Procedure:

    1. Go to My MCP Services. In the Actions column, click the Edit button.

    2. Select the API to tune and click the Edit button in the Actions column.

    3. Modify the overview, API request description, or API parameter descriptions.

    4. After you save the changes, disconnect from the MCP service 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 scenarios, 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 large model will not "see" the deleted parameters. This reduces the model's error rate and decreases token usage.

MCP access control

image

An AI agent that integrates with the OpenAPI MCP Server does not have its own identity or permissions to access Alibaba Cloud. The agent must be triggered by a user and acts as a proxy to perform cloud operations on the user's behalf. For example, a client initiates an OAuth flow. After the user provides authorization, the agent obtains temporary access permissions. Because all operations require user authorization, the agent's actions are limited by the user's permissions. This method achieves the principle of least privilege. In addition, ActionTrail records which user performs each operation because the operations are executed under the user's identity.

Applicable agents: CherryStudio, Tongyi Lingma, Qwen Code, Cursor, Claude Code, Dify, AgentScope, LangGraph, and others.

FAQ

1. Can the MCP client call all APIs in Tools?

Calls may not always succeed. Success depends on the permissions of the Resource Access Management (RAM) user. If a RAM user does not have permission to call an API, the large model cannot call that API either.

To resolve this, grant the required API permissions to the RAM user. For more information, see Grant permissions to a RAM user.

Important

Do not grant RAM users permission to delete resources. This prevents the large model from misunderstanding a request and calling a delete API, which could release resources and adversely affect your business.

2. A RAM user receives a 'permission denied for MCP operations' error when creating an MCP Server.

Solution:

  • Grant the `AliyunOpenAPIMCPServerFullAccess` system policy to the RAM user. For more information, see Grant permissions to a RAM user.

  • Grant a custom policy to the RAM user:

    1. Contact an administrator to 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 MCP Server operations

      This policy grants permissions to create, update, query, and delete MCP Servers. It also grants permissions to query MCP system tools.

      { "Version": "1", "Statement": [ { "Action": [ "openapiexplorer:*Mcp*", "ram:*Application*" ], "Resource": "*", "Effect": "Allow" } ] }

    2. Contact an administrator to grant the custom policy to the RAM user. For more information, see Grant permissions to a RAM user.

3. If an MCP Server endpoint is exposed, can anyone use it?

No, others cannot use an exposed MCP Server endpoint. When the endpoint is entered and saved in the client, the client performs an OAuth discovery. The authorization logon page for the Alibaba Cloud Management Console is displayed. After authorization is complete, the system verifies that the Alibaba Cloud account that owns the MCP Server is the same as the Alibaba Cloud account that owns the authorized RAM user. The MCP Server can be accessed only if the accounts match.

More ways to integrate MCP

  • OpenAPI MCP Server uses a custom OAuth application configuration to grant authorization. This feature is supported in Dify 1.8.0 and later. For more information, see Integrate OpenAPI MCP Server in Dify.

  • You can complete the custom OAuth authorization flow using the official MCP software development kit (SDK) and build a conversational assistant using mainstream agent frameworks. For more information, see Integrate OpenAPI MCP Server in an agent.