阿里云 OpenAPI MCP Server 提供标准化接口协议，支持通过自然语言调用云资源 API，并可通过 OAuth、AK 静态凭证和 RAM 权限管理实现安全访问与调优。-OpenAPI Explorer(OpenAPI)-阿里云帮助中心

MCP（Model Context Protocol）是大模型与外部工具和数据源交互的标准化协议。阿里云 OpenAPI Explorer 提供 OpenAPI MCP Server，支持通过自然语言调用阿里云 API 操作云上资源。

选择使用方式

选择版本

阿里云 OpenAPI MCP Server 提供以下两种使用方式：

对比项	Core 版	自定义版
上手速度	快：登录控制台后直接获取端点（Endpoint）。	中：需创建服务并选择 API。
API 覆盖范围	覆盖全部阿里云 OpenAPI。	仅覆盖已选择的 API。
API 匹配方式	大模型通过语义搜索自动匹配并调用 API。当多个 API 功能相近时，可能需要更明确的提示词。	选定的 API 直接作为 Tool 暴露，大模型无需搜索即可调用。
调优能力	不支持	支持：可修改 API 描述和参数。
服务数量	每个账号一个。	可创建多个，按场景划分。
适用场景	快速体验、探索性操作、跨产品联动。	固定业务流程、明确 API 需求、需要调优的场景。

如需快速上手，或进行跨多个云产品的操作，建议使用 Core 版。
如已明确所需 API，希望大模型直接调用而无需搜索匹配，建议使用自定义版。

选择认证方式

选择版本后，还需选择认证方式。API MCP Server 支持以下两种认证方式：

OAuth 认证（交互认证）：通过浏览器自动跳转登录，令牌过期后需重新登录。
静态凭证认证：完成一次预检查后，通过静态凭证连接，无需浏览器。

对比项	OAuth 认证（交互认证）	AK 静态凭证认证
适用场景	有浏览器交互的桌面客户端、日常开发和探索性操作。	无图形界面服务器、CI/CD 流水线、AI Agent 无人值守集成。
授权方式	浏览器跳转，用户登录后授权。	环境变量传入 AK，无需浏览器跳转。
权限身份	触发授权的用户身份。	AK 对应的 RAM 用户身份。
安全性	令牌短期有效，安全性更高。	长期静态凭证，需注意安全风险。

前提条件

使用API MCP Server 前，请根据认证方式完成以下准备：

OAuth 认证

适用于有浏览器交互的桌面客户端场景，权限跟随用户，令牌短期有效，安全性更高。

已注册阿里云账号。如果使用 RAM 用户操作，需为其授予相应权限。具体操作，请参见为RAM用户授予操作MCP Server的权限。
使用管理员账号前往RAM 控制台 - OAuth 应用 - 第三方应用，安装 OpenAPI MCP Server 官方应用并分配，否则 MCP 服务将无法进行 OAuth 授权。具体操作，请参见安装和授权第三方应用。

静态凭证认证

适用于无浏览器交互场景（如 CI/CD 流水线、CLI 环境、AI Agent）。支持通过环境变量传递AccessKey（AK）凭据；若本地已登录阿里云CLI，MCP 代理会自动复用现有凭据，无需额外配置。

已安装 Python（>= 3.13）和 uv。
已注册阿里云账号且已创建 AK，该 AK 对应的 RAM 用户或 RAM 角色已授予系统权限策略 AliyunOpenAPIMCPServerStaticCredentialAccess。您可以前往RAM 控制台为 RAM 用户授予该策略。
首次使用前，需执行预检查（应用授权）命令，检查账号是否已完成应用授权。如未完成，命令会打开浏览器引导您完成授权；预检查针对阿里云账号生效，可在任意有浏览器的设备上执行，与使用MCP的机器无需相同：uvx alibabacloud.mcp-proxy@latest --server-url <MCP 连接地址> pre-check。

获取 MCP 服务端点（Endpoint）

Core 版和自定义版的客户端配置流程一致，区别在于获取 MCP 服务端点的方式不同。

Core 版

登录后，系统将为 Core 版自动分配 MCP 服务端点，通过内置工具组合覆盖全部阿里云 OpenAPI。

登录阿里云 OpenAPI MCP 服务控制台。
在左侧导航栏，单击Core页签。页面将显示 Streamable HTTP Endpoint 和 SSE Endpoint。
如需修改 OAuth 或高级配置，单击对应的修改按钮：
- 多账号 MCP：用于在多账号场景下统一管理 MCP Server。具体操作，请参见多账号场景下如何使用OpenAPI MCP Server。
- 公网配置：开启公网访问后，MCP 服务可通过公网访问，适用于本地开发调试、跨地域协作或外部系统集成。
- 自定义 VPC 白名单：适用于对网络安全有严格管控要求的场景。

自定义版

自定义版需先创建 MCP 服务并选择所需 API。每个选定的 API 直接作为 MCP Tool 暴露给大模型，无需经过语义搜索即可调用。

登录阿里云 OpenAPI MCP 服务控制台。
在左侧导航栏，单击自定义 > 创建，进入 MCP 配置页面。
填写以下信息：
- 名称：长度为 3~16 位，支持小写字母、数字、下划线（_）和短划线（-）。例如 mcp-demo。
- 文档语言：选择 Tools 中 API 描述所使用的语言。
- OAuth 配置：
  - 阿里云官方 OAuth：适用于本地客户端，例如通义灵码、Cherry Studio、Cursor 等。
  - 自定义 OAuth：适用于自建平台或第三方服务，例如自部署的 Dify、AgentScope，以及 Claude Web/Mobile 等。
- 多账号 MCP：用于在多账号场景下统一管理 MCP Server。具体操作，请参见多账号场景下如何使用OpenAPI MCP Server。
- 云产品与 API 列表：为 MCP 服务配置 API Tools。
- Terraform Tools：以 Terraform HCL 代码的方式定义 MCP Tools。Terraform Tools 仅支持创建资源，不支持修改资源。具体操作，请参见OpenAPI MCP Server中如何使用Terraform Tools。
- 系统 Tools：官方预设的 Tools，选择后自动集成到 MCP 服务中。
- MCP 指令：用于提示大模型如何使用该 MCP，需要客户端支持 MCP 标准协议的 Instructions 字段。
- 备注：为 MCP 服务添加说明信息。
单击创建，并确认风险提示。创建完成后，页面将显示 Streamable HTTP Endpoint 和 SSE Endpoint。

说明

建议单个 MCP Server 选择的 API 数量不超过 30 个。如需使用更多 API，建议创建多个 MCP Server。

如果在 VPC 环境中使用 MCP，请优先使用页面中显示的 VPC 端点。

配置客户端

获取服务端点后，请在客户端配置连接。此配置适用于 Core 版和自定义版。阿里云 OpenAPI MCP 服务控制台内置了Cherry Studio、通义灵码/Cursor/Windsurf/VSCode、Claude Code和Codex等常见客户端的配置模板。MCP 具有广泛的兼容性，其他支持该协议的客户端或程序也可参照实际情况自行配置。

认证支持两种方式：

OAuth 认证（交互认证）：通过浏览器自动跳转授权。
静态凭证认证：通过环境变量传入AK或使用阿里云CLI凭据。

重要

AK 是长期静态凭证，泄露后可被持续利用。使用时请务必遵守以下安全规范，详情请参见创建AccessKey：

禁止使用主账号 AK，必须使用 RAM 用户的 AK，并仅授予所需的最小权限。
禁止硬编码到 mcp.json 等纳入版本控制的文件中，建议通过环境变量或密钥管理服务注入。
建议定期轮换 AK，降低凭证泄露风险。

OAuth认证（默认）

OAuth 认证为默认认证方式。该流程通过调用本地浏览器引导用户完成授权，适用于具备图形界面交互能力的桌面客户端，以及日常开发和探索性操作场景。

登录阿里云 OpenAPI MCP 服务控制台，进入Core版或自定义版的MCP 服务端点页面，单击一键配置，选择 OAuth 认证（默认），然后选择对应的客户端页签，按照配置模板完成配置。配置过程中，浏览器如果弹出用户授权页面，单击授权即可。

Cherry Studio

前提条件：已安装 Cherry Studio。

可通过以下方式完成配置：

一键配置：在控制台配置模板页面，单击一键配置至 Cherry Studio，按提示完成操作。
手动配置：进入 Cherry Studio 的设置 > MCP 服务器，选择添加 > 快速创建，填入名称，类型选择可流式传输的 HTTP，URL 填入 Streamable HTTP Endpoint 地址。也可选择从JSON导入，粘贴页面中的配置 JSON：

保存后，浏览器将自动跳转至阿里云 OAuth 授权页面，完成授权后即可启动 MCP 服务。

通义灵码/Cursor/Windsurf/VSCode

前提条件：已安装 Node.js 和 npm。

可通过以下方式完成配置：

一键配置（仅 Cursor 支持）：在控制台配置模板页面，单击一键配置至 Cursor，按提示完成操作。
手动配置：将控制台页面中的配置 JSON 粘贴到客户端的 MCP 配置文件中。

各客户端的配置方式：

通义灵码：打开通义灵码插件，在介绍页面中单击MCP 工具，在弹出窗口右上角单击 + 选择手动添加。名称自定义，类型选择 STDIO，命令填 npx，参数填 mcp-remote-alibaba-cloud <Streamable HTTP Endpoint>。
Cursor：在菜单栏依次选择 File > Preferences > Cursor Settings > Tools & Integrations，单击 Add Custom MCP，将 JSON 粘贴到 mcp.json 文件中保存。配置文件通常位于 ~/.cursor/mcp.json 或项目根目录 .cursor/mcp.json。
Windsurf：将 JSON 粘贴到 ~/.windsurf/mcp.json 或项目根目录 .windsurf/mcp.json。
VSCode：在设置中搜索 MCP，按提示添加配置。

配置保存后，首次使用需通过浏览器完成 OAuth 授权。如未自动跳转，请重启应用。

Claude Code

前提条件：已安装 Claude Code。

请在终端执行以下命令添加 MCP 服务器。注意将 <Streamable HTTP Endpoint> 替换为控制台中获取的实际地址：

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

执行以下命令查询已添加的MCP：

claude mcp list

配置或者使用过程中，浏览器如果弹出用户授权页面，单击授权即可。

Codex

前提条件：已安装 Codex CLI。

请在终端执行以下命令添加 MCP 服务器。注意将 <Streamable HTTP Endpoint> 替换为控制台中获取的实际地址：

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

执行以下命令查询已添加的MCP：

codex mcp list

配置或者使用过程中，浏览器如果弹出用户授权页面，单击授权即可。

静态凭证认证

静态凭证认证通过本地代理 alibabacloud.mcp-proxy 完成认证，无需浏览器跳转。适用于自动化流水线、纯命令行环境、AI Agent 无人值守等场景。

登录阿里云 OpenAPI MCP 服务控制台，进入Core版或自定义版的MCP 服务端点页面，单击一键配置，选择静态凭证认证，然后选择对应的客户端页签，按照配置模板完成配置。

说明

如果本地已完成阿里云CLI登录（aliyun configure），代理会自动读取 CLI 凭据，无需在配置中设置 env 环境变量。

Cherry Studio

前提条件：

已安装Cherry Studio、Python（>= 3.13）和 uv。
AccessKey 具有 AliyunOpenAPIMCPServerStaticCredentialAccess 系统权限。
首次使用前，需务必执行控制台上的预检查命令检查账号授权状态。该命令可在任意有浏览器的设备上执行，与运行代理的机器无需相同。

可通过以下方式完成配置：

在 Cherry Studio 中通过设置 > MCP 服务器 > 添加 > 从 JSON 导入粘贴配置。务必将 Access Key ID/Secret 替换为您的真实密钥；若已配置阿里云CLI，可直接移除 env 字段以复用本地凭据。

配置完成后，重启 Cherry Studio 并发送测试请求（如查询某地域的 ECS 实例列表），确认 API 正常调用即表示静态凭证认证成功。

通义灵码/Cursor/Windsurf/VSCode

前提条件：

已安装通义灵码/Cursor/Windsurf/VSCode、Python（>= 3.13）和 uv。
AccessKey 具有 AliyunOpenAPIMCPServerStaticCredentialAccess 系统权限。
首次使用前，需务必执行控制台上的预检查命令检查账号授权状态。该命令可在任意有浏览器的设备上执行，与运行代理的机器无需相同。

各客户端的配置方式：

通义灵码：在插件的 MCP 工具页面中手动添加，类型固定选择STDIO，命令填 uvx，参数填 alibabacloud.mcp-proxy@latest --server-url <Streamable HTTP Endpoint> ，并在环境变量中添加 ALIBABA_CLOUD_ACCESS_KEY_ID 和 ALIBABA_CLOUD_ACCESS_KEY_SECRET。
Cursor：将 JSON 粘贴到 ~/.cursor/mcp.json 或项目根目录 .cursor/mcp.json。并替换AK ID与Secret。
Windsurf：将 JSON 粘贴到 ~/.windsurf/mcp.json 或项目根目录 .windsurf/mcp.json。并替换AK ID与Secret。
VSCode：在设置中搜索 MCP，按提示添加配置。

若已配置阿里云CLI，可直接移除环境变量的配置以复用本地凭据。

配置完成后，保存并重启客户端，发送测试请求确认 API 正常调用即表示静态凭证认证成功。

Claude Code

前提条件：

已安装 Claude Code、Python（>= 3.13）和 uv。
AccessKey 具有 AliyunOpenAPIMCPServerStaticCredentialAccess 系统权限。
首次使用前，需务必执行控制台上的预检查命令检查账号授权状态。该命令可在任意有浏览器的设备上执行，与运行代理的机器无需相同。

可通过以下方式完成配置：

请在终端执行以下命令添加 MCP 服务器。注意将<Access Key ID>、<Access Key Secret> 和 <Streamable HTTP Endpoint> 替换为真实值。

若已配置阿里云CLI，可直接移除环境变量的配置以复用本地凭据。

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

执行以下命令查询已添加的MCP：

claude mcp list

Codex

前提条件：

已安装 Codex、Python（>= 3.13）和 uv。
AccessKey 具有 AliyunOpenAPIMCPServerStaticCredentialAccess 系统权限。
首次使用前，需务必执行控制台上的预检查命令检查账号授权状态。该命令可在任意有浏览器的设备上执行，与运行代理的机器无需相同。

可通过以下方式完成配置：

请在终端执行以下命令添加 MCP 服务器。注意将<Access Key ID>、<Access Key Secret> 和 <Streamable HTTP Endpoint> 替换为真实值。

若已配置阿里云CLI，可直接移除环境变量的配置以复用本地凭据。

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

执行以下命令查询已添加的MCP：

codex mcp list

使用 MCP

配置完成后，在客户端中使用自然语言即可操作云资源。更多集成方式，请参见更多集成 MCP 方式。

Core 版：直接用自然语言描述需求。大模型自动搜索匹配的 API、获取参数定义并执行调用，无需指定 API 名称和参数。例如，输入"帮我查询杭州地域的 ECS 实例"，大模型自动找到 DescribeInstances API 并完成调用。
自定义版：配置的 API 直接作为 Tool 暴露给大模型，无需搜索匹配，调用路径更短。当存在多个功能相近的 API 时，自定义版能确保大模型调用指定的 API。

Cherry Studio

在文本输入框的菜单中选择 MCP 服务器。
测试 MCP 功能。例如，查询某个地域下的 ECS 实例数量：
```
请帮我查询regionId 为 cn-chengdu 的 ECS 实例列表，并设置 x_mcp_region_id。
```
说明
如果 API 选择或参数设置出现偏差，可尝试优化提示词。自定义版还可通过 MCP 调优进一步解决。

Cursor

选择 Model 和 API Key。由于 Cursor 对 LLM provider 有要求（具体请参见Supported providers），因此在选择 Model 和 API Key 时就参考其说明。本示例使用默认值。
在 Cursor 对话框中单击Add Context，选择 MCP Server。
在对话框中输入自然语言测试 MCP 功能，例如"请帮我查询成都地域的 ECS 实例数量，仅显示实例个数。"。按回车键发送后，根据提示信息单击Run tool继续执行。
查看 MCP 执行结果。如果 API 选择或参数设置出现偏差，可尝试优化提示词。自定义版还可通过 MCP 调优进一步解决。

通义灵码

在通义灵码中选择智能体并输入提示内容，例如查询成都地域的 ECS 实例列表，并设置 x_mcp_region_id。
根据通义灵码的提示执行 MCP 工具。
查看结果。如果 API 选择或参数设置出现偏差，可尝试优化提示词。自定义版还可通过 MCP 调优进一步解决。

Cline

在 Cline 对话窗口中输入自然语言测试 MCP 功能，例如"请帮我查询成都地域的 ECS 实例数量"。
Cline 自动选择已配置的 MCP Server 中的 DescribeInstances 工具，并从输入中提取 RegionId 参数值。
查看 MCP 执行结果。如果 API 选择或参数设置出现偏差，可尝试优化提示词。自定义版还可通过 MCP 调优进一步解决。

MCP 调优（仅适用于自定义版）

Core 版通过内置工具自动处理 API 搜索和调用，不支持调优。

当大模型选择了错误的 API 或传递了不正确的参数时，可在服务端修改 API 的概述、说明和请求参数描述，帮助大模型更准确地理解和调用 API。

示例一：操作非 cn-hangzhou 地域的资源时，可能会出现报错或数据不准确

MCP 底层通过 x_mcp_region_id 切换 Endpoint。如果大模型未能根据输入理解需要传递 x_mcp_region_id，将默认操作 cn-hangzhou 地域的资源。

可以通过以下两种方式解决：

在提问时明确指示大模型设置 x_mcp_region_id。

请帮我查询regionId 为 cn-qingdao 的 ECS 实例列表，并设置 x_mcp_region_id。

在 MCP 服务端调整 API 的概述或请求参数 RegionId 的描述。
例如，在 API 概述中补充"将用户描述的地域传递给 x_mcp_region_id"，或在 RegionId 的描述中添加"如果参数 RegionId 存在，必须将其与 x_mcp_region_id 一起传递"。
操作步骤：
1. 访问自定义 API MCP SERVER，单击目标 MCP 服务操作列的编辑。
2. 选中待调优的 API，单击其操作列的编辑。
3. 修改概述、API 请求说明或 API 参数描述等。
4. 保存修改后，在客户端断开并重新连接 MCP 服务，使修改生效。

示例二：删除 API 中部分非必填参数

部分非必填参数在特定场景下无需使用，可在 MCP 服务端删除。删除后，大模型在生成参数时会忽略这些参数，降低错误率并减少 Token 消耗。

MCP 访问控制

AI Agent 集成 OpenAPI MCP Server 后，支持程序身份访问和用户身份访问两种模式。

程序身份访问

Agent 以自身的身份权限访问云资源。例如，在阿里云百炼中为自定义 MCP 配置 RAM 角色后，Agent 自动获取该角色的权限。用户通过 Agent 执行操作时，使用的是 Agent 的权限，与用户自身权限无关。

此外，也可以通过 AK 静态凭证认证实现程序身份访问：在客户端或 Agent 配置中通过环境变量传入 AK ID&Secret，由 alibabacloud.mcp-proxy 代理完成认证。该方式适用于自建 Agent、CI/CD 集成等无人值守场景。Agent 以 AK 对应的 RAM 身份执行操作，同样需在 Agent 或 AK 层面控制访问者范围。

此模式下需注意：

Agent 需获取所有潜在操作的权限并集，因此需在 Agent 层面控制访问者范围。
操作审计记录的是 Agent 身份（RAM 用户或 RAM 角色）。如需端到端审计，需在 Agent 层面记录调用者信息并与操作审计关联。
静态凭证认证场景下，应遵循最小权限原则，为 AK 对应的 RAM 用户仅授予 AliyunOpenAPIMCPServerStaticCredentialAccess 及业务必需的 API 权限，避免使用主账号 AK 或授予宽泛权限。

适用场景：阿里云百炼等服务端 Agent，以及通过静态凭证认证的自建 Agent、CI/CD 集成等自动化场景。

用户身份访问

Agent 本身不具备访问云资源的权限，必须由用户触发 OAuth 授权流程后，才能以用户身份执行操作。Agent 能执行的任务受限于用户自身的权限，遵循最小权限原则。操作审计记录的是实际执行操作的用户身份。

适用场景：Cherry Studio、通义灵码、Qwen Code、Cursor、Claude Code、Dify、AgentScope、LangGraph 等客户端 Agent 或需要代理用户身份的场景。

常见问题

Tools 中的 API，在 MCP 客户端是否都可以调用？

不一定。调用是否成功取决于发起 OAuth 授权的 RAM 用户的权限，或 AK 认证对应的 RAM 用户的权限。如果该 RAM 用户没有某个 API 的调用权限，则大模型也无法调用该 API。

解决方案：为 RAM 用户授予相应 API 的权限。具体操作，请参见授予 RAM 用户 API 权限。

重要

为防止大模型因理解错误而调用删除资源的 API，导致业务受到影响，建议不要为 RAM 用户授予删除资源的权限。

使用 RAM 用户创建 MCP Server 时，提示无权限操作

解决方案：

为 RAM 用户授予系统权限策略 AliyunOpenAPIMCPServerFullAccess。具体操作，请参见授予系统权限策略。
为 RAM 用户授予自定义权限策略：
1. 使用管理员账号在RAM 控制台创建自定义权限策略。具体操作，请参见创建自定义权限策略。
  权限策略内容如下：
  点击查看 MCP Server 操作相关权限策略
  该权限策略包括创建、更新、查询及删除 MCP Server 的权限，以及查询 MCP 系统工具的权限。
```
{
  "Version": "1",
  "Statement": [
    {
      "Action": [
        "openapiexplorer:*Mcp*",
        "ram:*Application*"
      ],
      "Resource": "*",
      "Effect": "Allow"
    }
  ]
}
```
2. 使用管理员账号为目标 RAM 用户授予该自定义权限。具体操作，请参见为 RAM 用户授予权限。

MCP Server 连接端点（Endpoint）暴露后，是否会被他人盗用？

不会。客户端配置端点后，OAuth 认证会触发 OAuth 授权流程，用户需登录并授权。系统验证发起授权的 RAM 用户所属主账号与 MCP Server 所属主账号是否一致，只有两者一致时才能访问。静态凭证认证下，访问权限受限于 AK 对应的 RAM 用户权限，盗用者无法超越该权限范围。

静态凭证认证和 OAuth 认证如何选择？

根据使用场景选择合适的认证方式：

OAuth 认证：适用于有浏览器交互的桌面客户端场景。权限跟随用户，令牌短期有效，安全性更高。推荐日常开发和探索性操作优先使用 OAuth。
AK 静态凭证认证：适用于自动化流水线、纯命令行环境（无图形界面的服务器）、AI Agent 无人值守集成等不便进行浏览器跳转的场景。权限跟随 AK 对应的 RAM 身份，需自行管理凭证安全。

AK Secret 不慎泄露怎么办？

立即在 RAM 控制台禁用或删除该 AccessKey。
创建新的 AccessKey 并更新客户端配置。
检查泄露期间的操作审计日志（ActionTrail），确认是否有异常调用。