OpenAPI MCP Server使用指南_OpenAPI Explorer(OpenAPI)-阿里云帮助中心

MCP（Model Context Protocol）是大模型与外部工具、数据源之间的标准化接口协议。它像“USB-C”一样，让不同工具（如数据库、API）能统一接入大模型，无需重复开发适配代码。通过客户端-服务器架构，MCP将工具调用逻辑集中在服务端，大模型仅需通过统一协议请求，即可灵活调用各类功能。阿里云OpenAPI Explorer已推出OpenAPI MCP Server，支持用户在大模型中调用API操作云上资源，本文将介绍如何创建并使用该MCP服务。

前提条件

管理员账号已在RAM 控制台的OAuth 应用中安装了OpenAPI MCP Server官方应用，并分配RAM用户使用。具体操作，请参见管理第三方应用授权。

创建MCP服务

说明

在使用无管理员权限的RAM用户进行操作时，需为该RAM用户授予相应的权限。详细信息，请参见为RAM用户授予操作MCP Server的权限。

访问阿里云OpenAPI MCP服务，单击创建MCP服务页签，填入如下信息：
- 名称：3-16位，支持a-z0-9_-组合，例如mcp-demo。
- 文档语言：选择Tools中API描述所使用的语言。
- 添加云产品与API：为MCP服务配置Tools。
  - 每次只能从单个云产品选择API，若要选择多个云产品的API，需要确定之后继续单击添加云产品与API。
  - 若要为已选择的云产品添加API，单击操作列添加。
- 系统Tools：系统Tools为官方预设的Tools，选择后它们将被合并生成到当前的 MCP Tools 中。
- 备注：为MCP服务添加说明信息。
说明
由于大模型在上下文长度及其tools选择精确度方面的限制，MCP Server对可选择的API数量也受到相应的约束。建议单个MCP Server所选择的API数量不超过30个，如需使用更多API，建议创建多个MCP Server来实现。
单击创建，确认风险提示。创建完成后，将返回Streamable HTTP Endpoint、SSE Endpoint以及MCP Client配置。这些内容将在客户端连接MCP服务时使用。

配置MCP

若您希望通过程序的方式使用MCP，可以选择在阿里云百炼中配置MCP服务。如需在常见客户端中使用MCP，如Cherry Studio、Cursor、通义灵码、Cline等，请根据所使用的客户端查阅相应的配置方式。

一键配置

说明

请提前安装Cherry Studio或Cursor。

如果您在Cherry Studio或Cursor中使用MCP，可以通过官方提供的一键配置功能完成MCP配置。

手动配置

阿里云百炼

在阿里云百炼控制台-MCP管理页面，单击创建MCP服务，并选择从阿里云OpenAPI导入。
在创建MCP服务页面，选择服务名称以及访问阿里云OpenAPI角色。
访问阿里云OpenAPI角色可通过一键配置方式创建。若您希望创建多个该类型角色用于配置不同的权限策略，请在创建角色页面单击切换编辑器选择脚本编辑，然后复制以下信任策略内容：
```
{
  "Statement": [
    {
      "Action": "sts:AssumeRole",
      "Effect": "Allow",
      "Principal": {
        "Service": [
          "sfm.aliyuncs.com"
        ]
      }
    }
  ],
  "Version": "1"
}
```
为访问阿里云OpenAPI角色授予调用MCP Server工具对应OpenAPI权限。
请复制页面中的权限策略，在RAM访问控制-权限策略中创建自定义权限策略，并将该自定义权限策略授权给访问阿里云OpenAPI的角色。
重要
当在OpenAPI MCP Server中添加工具时，必须在权限策略中加入相应的OpenAPI操作权限。
导入完成之后可以在MCP管理页面查看刚导入的MCP Server以及查看MCP Server中的工具信息。

Cherry Studio

说明

请提前安装Cherry Studio，若未安装请参见CherryStudio。

在Cherry Studio中配置模型服务。
1. 建议使用阿里云百炼qwen3-235b-a22b模型。
  其中API密钥为百炼控制台创建的API Key，API地址为https://dashscope.aliyuncs.com/compatible-mode/v1/。
2. 模型添加完成之后编辑模型，为模型配置联网、推理、工具等能力。
配置MCP服务器。
1. 添加MCP服务器。
2. 配置MCP服务器。填入名称，类型选择可流式传输的HTTP，URL填入创建MCP服务所返回的Streamable HTTP Endpoint。
3. 单击保存会跳转到阿里云OAuth授权页面，阅读完授权信息之后，单击授权。有关OAuth的详细介绍，请参见开放授权管理（OAuth）。
  完成授权之后，Cherry Studio会自动启动MCP服务。

Cursor

说明

请提前安装Cursor，若未安装请参见Cursor。本示例中使用的是Cursor提供的免费版，请您根据实际使用情况选择对应版本下载。

在Cursor菜单栏选择File > Preferences > Cursor Settings > Tools & Integrations，单击Add Custom MCP配置MCP Servers。
复制MCP Server配置内容到mcp.json中并保存（Ctrl+S）。
在OAuth页面完成授权。有关OAuth的详细介绍，请参见开放授权管理（OAuth）。
在Cursor Settings中可以查看配置的MCP Server信息。

通义灵码

VS Code和JetBrains均支持通义灵码插件，本文以JetBrains中配置和使用MCP为例。

说明

请提前安装通义灵码或者通义灵码插件，若未安装请参见通义灵码。

打开通义灵码插件，在通义灵码介绍中单击MCP工具。
在弹出窗口右上角单击+，选择手动添加。

在添加MCP服务窗口填入如下内容：

名称	MCP服务的名称，建议与虚拟MCP服务名称保持一致。
类型	固定选择`STDIO`。
命令	固定为`npx`。
参数	格式为`mcp-remote ${SSE Endpoint}`。说明仅支持SSE Endpoint，可从创建虚拟MCP服务所返回结果获取SSE Endpoint。

参数输入完成后单击立即添加。

在OAuth页面完成授权。有关OAuth的详细介绍，请参见开放授权管理（OAuth）。
通义灵码中启用MCP效果如下：

Cline

说明

请提前安装Cline插件，本文以在VS Code中使用Cline为例，更多信息请参见Cline。

在VS Code中打开Cline插件，输入您的API Key。
在Cline顶部菜单栏单击MCP Servers配置MCP Server。
根据下图所示步骤添加MCP Server。
在OAuth页面完成授权。有关OAuth的详细介绍，请参见开放授权管理（OAuth）。
授权完成后，如果在Cline底部的MCP Servers中出现新配置的MCP Server，则表示配置已成功。

Inspector

说明

本文内容仅为简单介绍，关于Inspector的更多详细信息，请参见Inspector。
Node.js的版本不低于22.7.5。

在Terminal中运行以下命令启动Inspector，服务启动后，默认可通过http://localhost:6274访问。
```
npx @modelcontextprotocol/inspector
```
在Inspector UI界面的左侧选择Transport Type，本文以Streamable HTTP为例。在URL中输入创建MCP服务所返回的Streamable HTTP Endpoint，然后单击Connect。
在OAuth页面完成授权。有关OAuth的详细介绍，请参见开放授权管理（OAuth）。
授权完成后，在Inspector UI界面即可看到MCP Server的工具信息。
您可以单击任意一个Tool，在右侧查看该Tool的详细信息，同时也支持设置参数调用该Tool。

使用MCP

配置完成后，您可以使用MCP对云上资源进行操作。如果希望通过编程方式使用MCP，可以通过阿里云百炼提供应用调用能力实现；在其他场景下，您可直接在客户端使用MCP。

阿里云百炼

在阿里云百炼控制台-应用管理页面，选择需要添加MCP的应用。如无现有应用，请先新增应用。
在应用配置页面，添加之前步骤中创建的自定义MCP服务。
在文本对话中测试MCP的集成是否成功。例如，可以输入“查询杭州的ECS实例”。在正常情况下，若MCP选择的OpenAPI正确且请求参数设置无误，则返回结果应为正确。如果出现错误，可以尝试通过MCP调优来解决相关问题。
测试通过后发布应用，即可在程序中通过调用该应用来使用MCP服务。有关如何调用应用的详细信息，请参见应用调用。

Cherry Studio

选择MCP服务器。
测试MCP功能。例如查询某个地域下ECS实例数量：
```
请帮我查询regionId为cn-chengdu的ECS实例列表，并设置x_mcp_region_id。
```
说明
在正常情况下，若MCP选择的API正确且API的请求参数设置无误，则返回结果应为准确。如果出现错误，可以尝试通过MCP调优来解决相关问题。

Cursor

选择Model和API Key，由于Cursor对LLM provider存在要求，具体请参见Supported providers，所以在选择Model和API Key时，您需参考该介绍。本示例使用的是默认值。
在Cursor对话框中单击Add Context，选择MCP Server。
在对话框输入自然语言测试MCP功能，例如“请帮我查询成都地域的ECS实例数量，仅显示实例个数。”。按回车键发送内容后，根据提示信息单击Run tool继续执行。
查看MCP执行结果。在正常情况下，若MCP选择的API正确且API的请求参数设置无误，则返回结果应为准确。如果出现错误，可以尝试通过MCP调优来解决相关问题。

通义灵码

在通义灵码中选择智能体并输入提示内容，例如查询成都地域的ECS实例列表，需设置x_mcp_region_id。
根据通义灵码的提示执行MCP工具。
查看结果。在正常情况下，若MCP工具选择正确且API的请求参数设置无误，则返回结果应为准确。如果出现错误，可以尝试通过MCP调优来解决相关错误。

Cline

在Cline对话窗口中输入自然语言测试MCP功能，例如“请帮我查询成都地域的ECS实例数量”。
从上图中可以看出，Cline使用了我们配置的MCP Server，并选择了其中一个工具DescribeInstances，其参数RegionId的值同样是从输入中获取的。
MCP执行结果。在正常情况下，若MCP选择的API正确且API的请求参数设置无误，则返回结果应为准确。如果出现错误，可以尝试通过MCP调优来解决相关问题。

MCP调优

当大模型依赖MCP的回答不准确时，您可以通过在服务端修改API的概述、说明以及请求参数描述等方式，提高大模型对每个API功能的理解。下面将列举几个例子帮助您更好地理解MCP调优。

示例一：操作非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. 访问我的MCP服务，单击MCP服务操作栏的编辑按钮。
2. 选中待调优的API，单击操作栏的编辑按钮。
3. 修改概述、API请求说明或API参数描述等。
4. 保存修改内容后，在客户端需断开MCP服务并重新连接，以使修改内容生效。

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

由于API文档中的参数是包括了所有场景，其中部分非必填参数可能在您的绝大多数的场景下并不需要使用，因此您可以在MCP服务端中删除这些非必填参数。大模型在传参时将不会“看到”这些被删除的参数，这不仅可以降低大模型的错误率，还可以减少tokens的使用。

常见问题

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

问题原因：不一定都能调用成功，具体情况取决于RAM用户的权限，如果RAM用户没有某个API的调用权限，则大模型也将无法调用该API。

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

重要

建议不要为RAM用户授予删除资源的权限，以防止大模型因理解错误而调用删除资源的API，从而释放资源，对您的业务产生负面影响。

2. 使用RAM用户创建MCP Server时，提示无权限进行MCP操作，请联系具有管理员权限的账号授权。

解决方案：

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

3. 如果MCP Server连接端点（Endpoint）暴露了，是不是谁都可以用了？

MCP Server连接端点暴露后，其他人也不能用。当在客户端中填入MCP Server连接端点保存之后，会由客户端实现OAuth的发现。首先，会弹出阿里云控制台的授权登录页面。完成授权后，将验证MCP Server所属的阿里云主账号与授权OAuth的RAM用户所属主账号是否一致，只有在两者一致的情况下，才能访问MCP Server。