OpenAPI MCP Server User Guide

• Use the Core Edition for a quick start or for operations that span multiple cloud products.

• Use the Custom Edition if you have specific APIs in mind and want the LLM to call them directly without searching.

Select an authentication method

After selecting an edition, you must also choose an authentication method. OpenAPI MCP Server supports the following two authentication methods:

• OAuth authentication (interactive authentication): Automatically redirects to a browser to sign in. You must sign in again after the token expires.

• Static credential authentication: Connects by using static credentials after a one-time pre-check, with no browser required.

OAuth authentication (default)

This method opens the local browser to guide the user through authorization, making it ideal for desktop clients with a GUI and for daily development or exploratory tasks.

Log on to the Alibaba Cloud OpenAPI MCP service console and go to the MCP service endpoint page for the Core or Custom Edition. Click One-click Configuration and select OAuth authentication (default). Then, select the corresponding client tab and follow the configuration template to complete the configuration. If a user authorization page is displayed in the browser during the process, click Authorize.

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

claude mcp list

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

codex mcp list

Static credential authentication

Static credential authentication is completed through the local proxy alibabacloud.mcp-proxy without browser redirection. This method is suitable for scenarios such as automated pipelines, pure command-line environments, and unattended AI Agents.

Log on to the Alibaba Cloud OpenAPI MCP service console, go to the MCP service endpoint page of the Core or Custom Edition, click One-click Configuration, and select Static Credential Authentication. Then, select the corresponding client tab and complete the configuration according to the configuration template.

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

claude mcp list

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

codex mcp list

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

Internally, MCP uses x_mcp_region_id to switch Endpoint. If the LLM fails to understand from the input that it needs to pass x_mcp_region_id, it operates on resources in the cn-hangzhou region by default.

Resolve this issue using one of the following two methods:

• Explicitly instruct the LLM to set x_mcp_region_id in the query.

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

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

  For example, add "Pass the user-specified region to x_mcp_region_id" to the API overview. Or, add "If the RegionId parameter exists, pass it along with x_mcp_region_id" to the description of RegionId.

  Steps:

  1. Go to Custom API MCP SERVER, and click Edit in the Actions column for the target MCP service.

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

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

  4. Save the changes. Then, disconnect from and reconnect to the MCP service on the client to apply the changes.

Example 2: Deleting optional API parameters

Some optional parameters are not used in specific scenarios. Delete these parameters on the MCP server. After they are deleted, the LLM ignores them when generating parameters. This reduces the error rate and lowers Token consumption.

Programmatic identity access

The agent accesses cloud resources using its own identity and permissions. For example, after configuring a RAM role for a custom MCP in Model Studio, the agent automatically obtains the permissions of that role. When a user performs an operation through the agent, the operation uses the agent's permissions, not the user's.

Alternatively, use static credential authentication for programmatic identity access. Pass the AccessKey (AK) ID and secret through environment variables in the client or agent configuration. The alibabacloud.mcp-proxy agent then completes the authentication. This method is suitable for unattended scenarios, such as self-built agents and CI/CD integrations. The agent performs operations using the RAM identity associated with the AK. The scope of access must also be controlled at the agent or AK level.

Note:

• The agent must obtain a union of permissions for all potential operations. Therefore, control the scope of access at the agent level.

• ActionTrail records the agent's identity, which is a RAM user or RAM role. For end-to-end auditing, record caller information at the agent level and associate it with ActionTrail.

• In static credential authentication scenarios, follow the principle of least privilege. Grant the RAM user associated with the AK only the AliyunOpenAPIMCPServerStaticCredentialAccess policy and the API permissions required for your business. Avoid using an Alibaba Cloud account AK or granting broad permissions.

Applicable scenarios: Server-side agents, such as those in Model Studio, and automation scenarios, such as self-built agents and CI/CD integrations that use static credential authentication.

User identity access

The agent itself does not have permission to access cloud resources. It can perform operations on behalf of a user only after the user initiates an OAuth authorization flow. The tasks that the agent can perform are limited by the user's own permissions, following the principle of least privilege. ActionTrail records the identity of the user who performs the operation.

Applicable scenarios: Client-side agents, such as Cherry Studio, TONGYI Lingma, Qwen Code, Cursor, Claude Code, Dify, AgentScope, and LangGraph, or scenarios that require user identity proxying.

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

Not necessarily. The success of an API call depends on the permissions of the RAM user. This can be the user who initiates OAuth authentication or the user associated with the AccessKey (AK) for authentication. If a RAM user lacks permission to call an API, the large language model (LLM) also cannot call it.

Solution: Grant the required API permissions to the RAM user. For more information, see Manage RAM user permissions.

Permission denied when creating an MCP Server as a RAM user

Solution:

• Grant the system policy AliyunOpenAPIMCPServerFullAccess to the RAM user. For more information, see 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. For more information, see Create a custom policy.

     The following is the content of the policy:

     Click to view the policy for MCP Server operations

     This policy includes permissions to create, update, query, and delete MCP Servers, and to query MCP system tools.

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

  2. Use an administrator account to grant the custom permission to the target RAM user. For more information, see Manage RAM user permissions.

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

No. When a client uses the endpoint, OAuth authentication starts an authorization process. This process requires the user to log in and grant access. The system checks if the RAM user's Alibaba Cloud account matches the MCP Server's Alibaba Cloud account. Access is granted only if they match. For static credential authentication, access is restricted by the permissions of the RAM user associated with the AK. An unauthorized party cannot exceed this scope of permissions.

How to choose between static credential authentication and OAuth authentication?

Choose the authentication method that suits your use case:

• OAuth authentication: Suitable for desktop client scenarios that involve browser interaction. Permissions are tied to the user, and the token is short-lived for higher security. Use OAuth for daily development and exploratory operations.

• Static credential authentication (AK): Suitable for scenarios where browser redirection is inconvenient, such as automated pipelines, command-line-only environments (servers without a graphical user interface (GUI)), and unattended AI Agent integrations. Permissions are tied to the RAM identity associated with the AK. You must manage the security of the credentials yourself.

What should I do if an AccessKey Secret is leaked?

1. Immediately disable or delete the AccessKey in the RAM console.

2. Create a new AccessKey and update your client configuration.

3. Check the ActionTrail logs for the period of the leak to identify any unauthorized calls.