OpenAPI Explorer：使用 aliyun utils mcp-proxy 代理 OpenAPI MCP Server

步骤一：配置阿里云 CLI

1. 安装或升级阿里云 CLI，确保版本不低于 3.5.0。安装方法，请参见安装/更新 CLI。

2. 使用阿里云账号或 RAM 用户的 AccessKey 配置 CLI。

   aliyun configure
   # 根据提示输入 AccessKey ID、AccessKey Secret 和默认地域。

   如果使用 RAM 用户，请为其授予下表中的权限。

   权限	作用	适用场景
   ram:ListApplications	按名称查询 OAuth 应用。	必需。代理首次启动，或本地保存的授权信息不可用时需要该权限。使用 --oauth-app-name 指定已有应用时同样需要。
   ram:CreateApplication	创建默认 OAuth 应用 aliyun-cli-mcp-proxy。	未使用 --oauth-app-name 指定应用，且默认应用尚不存在时需要该权限。
   ram:GetApplication	按 ID 查询 OAuth 应用。	建议授予。代理凭该权限复用本地已保存的授权信息；未授予时，代理每次启动均需重新完成一次 OAuth 授权。

步骤二：首次运行代理并完成 OAuth 授权

首次运行 mcp-proxy 时，需完成一次性 OAuth 授权以获取刷新 Token 的权限。

1. 在前台启动。

   • 在有图形界面的环境中，不带 --no-browser 参数时，CLI 会自动拉起浏览器执行 OAuth 授权登录流程，无需手动输入授权码。授权完成后可直接跳至第 5 步。

     aliyun utils mcp-proxy --host 127.0.0.1 --port 8088

   • 在无图形界面的服务器环境中操作时，请添加 --no-browser 参数，后续步骤将引导手动获取授权码。

     aliyun utils mcp-proxy --host 127.0.0.1 --port 8088 --no-browser

   说明

   使用 --oauth-app-name 参数可指定自定义 OAuth 应用，该应用必须满足以下条件：

   • OAuth 范围（Scope）：必须包含 --scope 参数指定的授权范围，默认为 /acs/mcp-server。

   • 回调地址（Redirect URI）：必须包含 http://<host>:<port>/callback，其中 host 和 port 为启动代理时 --host 和 --port 参数的值。

   • 应用类型：必须为 NativeApp 类型的应用。

2. 终端将输出授权 URL。

   Setting up MCPOAuth profile 'default-mcp'...
   Opening browser for OAuth login...
   URL: https://signin.alibabacloud.com/oauth2/v1/auth?client_id=XXXX&response_type=code&scope=%2Facs%2Fmcp-server&redirect_uri=http://127.0.0.1:8088/callback&code_challenge=XXX&code_challenge_method=S256
   Please open the authorization URL on a machine with a browser and complete the sign-in.
   After authorization, the browser will redirect to a callback URL.
   Even if the page fails to load (connection error), the authorization code is in the URL.
   Please copy the value of the `code` parameter from the browser's address bar.
   Example: If the URL is:
     http://127.0.0.1:8088/callback?code=abc123xyz&state=...
     Then copy only: abc123xyz
   Enter authorization code: <YOUR CODE>

3. 在浏览器中打开该 URL，登录并完成授权。

4. 授权成功后，页面会跳转至包含 code 参数的地址或直接显示授权码。将 code 值复制并粘贴至终端，按回车键确认。

5. 当终端显示 OAuth login successful!信息时，表示授权登录成功。

   2025/12/04 19:11:49 OAuth authorization code received successfully
   2025/12/04 19:11:49 Start to exchange code for token with PKCE
   2025/12/04 19:11:49 Exchange code for token with PKCE successfully
   OAuth login successful!

6. 当终端显示 MCP Proxy Server Started 信息时，表示代理启动成功。

   MCP Profile 'default-mcp' configured for oauth app 'aliyun-cli-mcp-proxy' successfully!
   
   MCP Proxy Server Started
   Listen: 127.0.0.1:8088
   Region: CN

步骤三：配置为 systemd 后台服务（以 CentOS 为例）

为确保代理稳定运行，建议将其配置为开机自启的 systemd 服务。

1. 创建 systemd 服务文件：aliyun-mcp-proxy。

   替换以下内容：

   • 将命令中的 your-user 替换为实际运行此命令的非 root 用户名。该用户必须已通过 aliyun configure 配置凭据，并已在该用户下完成上述 OAuth 授权。服务启动时会复用该用户主目录中已保存的授权凭据，不会再次触发浏览器授权。

   • ExecStart 必须填写 aliyun 命令的绝对路径。执行 which aliyun 获取实际路径，并替换示例中的 /usr/local/bin/aliyun。systemd 不通过 shell 解析该字段，因此 $(which aliyun) 这类命令替换写法不会生效。

   sudo tee /etc/systemd/system/aliyun-mcp-proxy.service << 'EOF'
   [Unit]
   Description=Aliyun CLI MCP Proxy
   After=network.target
   [Service]
   Type=simple
   User=your-user
   ExecStart=/usr/local/bin/aliyun utils mcp-proxy --host 127.0.0.1 --port 8088 --no-browser
   Restart=always
   RestartSec=10
   Environment=HOME=/home/your-user
   [Install]
   WantedBy=multi-user.target
   EOF

2. 重新加载 systemd 配置并启动服务。

   # 重新加载配置
   sudo systemctl daemon-reload
   # 启动服务
   sudo systemctl start aliyun-mcp-proxy
   # 设置开机自启
   sudo systemctl enable aliyun-mcp-proxy

步骤四：验证代理服务

通过以下任一方式验证服务是否正常运行。

• 查看服务状态

  执行以下命令查看服务状态。

  sudo systemctl status aliyun-mcp-proxy

  若输出中包含 active (running)，则表示服务已成功启动。

• 请求代理端口

  执行以下命令，直接请求代理端口。

  curl http://127.0.0.1:8088/

  如果代理工作正常，将收到来自 MCP Server 的 XML 格式错误响应，表明代理与服务之间的链路已连通。

  <?xml version='1.0' encoding='UTF-8'?><Error><RequestId>B3311876-XXXXX</RequestId><HostId>openapi-mcp.cn-hangzhou.aliyuncs.com</HostId><Code>InvalidAction.NotFound</Code><Message>Specified api is not found, please check your url and method.</Message><Recommend><![CDATA[https://api.alibabacloud.com/troubleshoot?q=InvalidAction.NotFound&product=OpenAPIExplorer&requestId=B3311876-XXX]]></Recommend></Error>

步骤一：获取宿主机 Docker 网桥 IP 并启动 mcp-proxy 代理服务

Dify 容器需通过宿主机的 Docker 网桥 IP 地址访问 mcp-proxy 服务。

1. 执行以下命令，获取并记录该 IP 地址。

   ip addr show docker0 | grep "inet\b" | awk '{print $2}' | cut -d/ -f1

   执行后会得到类似 172.17.0.1 的 IP 地址。

2. 在前台启动 mcp-proxy 代理服务。或者，在 systemd 中修改启动命令然后通过服务启动。

   aliyun utils mcp-proxy --host 172.17.0.1 --port 8088 --no-browser

   说明

   回调地址由 --host 和 --port 参数共同决定。将监听地址从 127.0.0.1 改为 Docker 网桥 IP 后，需在 RAM 控制台的集成管理 > OAuth 应用（公测）中，为对应的 OAuth 应用补充新的回调地址（例如 http://172.17.0.1:8088/callback），否则启动时将因回调地址校验不通过而失败。

步骤二：在 Dify 中配置 MCP Server

1. 进入 Dify 的 工具 > MCP 配置页面。

2. 点击 添加 MCP 服务（HTTP）。

3. 在 服务端点 URL 字段中，填入 MCP 代理地址。

   在阿里云 OpenAPI MCP 服务控制台获取原始的 Streamable HTTP Endpoint 地址，并将该地址中的域名部分（host）替换为本地或内网代理地址。

   示例转换：

   • 原始 Endpoint：https://openapi-mcp.cn-hangzhou.aliyuncs.com/accounts/1234/custom/cli-proxy-test/id/1234/mcp

   • 替换为代理地址（假设代理运行在 172.17.0.1:8088）：http://172.17.0.1:8088/accounts/1234/custom/cli-proxy-test/id/1234/mcp

4. 按需填入其他信息后点击添加并授权。Dify 将通过该代理地址与 MCP 服务通信。

防护措施

• 环境隔离：仅在受信任的单用户环境中运行代理，避免在多用户共享服务器上使用。

• 网络访问控制：将代理监听地址（--host）绑定到 127.0.0.1（默认）或特定内网 IP。使用防火墙或安全组规则限制代理端口访问范围（例如仅允许特定应用服务器 IP 访问），严禁对公网暴露。

• 访问控制：通过 --allowed-servers 或 --blocked-servers 参数限制可访问的 MCP Server 范围，避免代理被用于访问非预期的服务。配置方法，请参见配置服务器访问控制。

• 最小权限原则：为代理使用的 CLI 用户及其关联的 MCP Server 配置最小必要权限，优先授予只读权限。

• 审计与监控：定期审查代理服务的访问日志，监控异常请求。被访问控制拦截的请求会记录在代理日志中。

配置服务器访问控制

aliyun utils mcp-proxy 支持白名单和黑名单机制，限制可通过代理访问的 MCP Server 范围。

Available Servers:
  - cloudphone
    MCP: http://127.0.0.1:8088/accounts/0000000000000000/system/eds-aic/cloudphone/id/XSkb9v4dXx000000/mcp
    SSE: http://127.0.0.1:8088/accounts/0000000000000000/system/eds-aic/cloudphone/id/XSkb9v4dXx000000/sse
  - multi_account
    MCP: http://127.0.0.1:8088/accounts/0000000000000000/custom/multi_account/id/OV0Qkpxh0Uodx000/mcp
    SSE: http://127.0.0.1:8088/accounts/0000000000000000/custom/multi_account/id/OV0Qkpxh0Uodx000/sse

......./system/eds-aic/$server_name/id/$server_id/mcp
......./custom/$server_name/id/$server_id/mcp

aliyun utils mcp-proxy --allowed-servers "ecs-basic,oss-basic" --blocked-servers "oss-basic"

MCP Proxy Server Started
Listen: 127.0.0.1:8088
Region: CN

Access Control:
  Blacklist (blocked servers):
    - oss-basic
  Whitelist (allowed servers):
    - ecs-basic
    - oss-basic

Available Servers:
  - ecs-basic
    MCP: http://127.0.0.1:8088/accounts/0000000000000000/system/Ecs/ecs-basic/id/daRi22dx71iX0000/mcp
    SSE: http://127.0.0.1:8088/accounts/0000000000000000/system/Ecs/ecs-basic/id/daRi22dx71iX0000/sse
  - oss-basic (blocked)
    MCP: http://127.0.0.1:8088/accounts/0000000000000000/system/Oss/oss-basic/id/vP5TovGrt2jm0000/mcp
    SSE: http://127.0.0.1:8088/accounts/0000000000000000/system/Oss/oss-basic/id/vP5TovGrt2jm0000/sse
  - cms-basic (not in whitelist)
    MCP: http://127.0.0.1:8088/accounts/0000000000000000/system/Cms/cms-basic/id/6PHbBzr8Bg6b0000/mcp
    SSE: http://127.0.0.1:8088/accounts/0000000000000000/system/Cms/cms-basic/id/6PHbBzr8Bg6b0000/sse

Press Ctrl+C to stop

MCP Proxy access denied: path /accounts/0000000000000000/system/Oss/oss-basic/id/vP5TovGrt2jm0000/mcp is in blocked servers list
MCP Proxy access denied: path /accounts/0000000000000000/system/Cms/cms-basic/id/6PHbBzr8Bg6b0000/mcp is not in allowed servers list

安全事件处理

如果怀疑代理认证 Token 泄露或被滥用，立即执行以下操作：

• 停止 mcp-proxy 服务。

• 删除本地配置文件：rm ~/.aliyun/.mcpproxy_config。

• 删除该 OAuth 应用，使已泄露的 Refresh Token 永久失效。使用 RAM 管理员身份登录 RAM 控制台，在左侧导航栏选择集成管理 > OAuth 应用（公测），在企业应用页签单击目标应用操作列的删除应用；也可使用 CLI 删除。删除后重新完成 OAuth 授权时，CLI 会自动创建新的应用。

  aliyun ims list-applications --cli-query "Applications.Application[?AppName=='aliyun-cli-mcp-proxy'].AppId"
  aliyun ims delete-application --app-id <应用 ID>

• 检查 API 调用日志，确认是否存在异常操作。

• 重新启动代理并完成 OAuth 授权，获取新的 Token。

执行 aliyun utils mcp-proxy 进行 OAuth 认证后，出现 “ERROR: OAuth flow returned empty RefreshToken” 错误且代理启动失败，是什么原因？

该错误表示当前使用的 OAuth 应用不是 NativeApp 类型，无法在授权流程中返回 Refresh Token。任选以下一种方式处理：

• 删除该 OAuth 应用后重新启动代理，由 CLI 自动创建 NativeApp 类型的应用。

• 手动创建 NativeApp 类型的应用，并在启动代理时通过 --oauth-app-name 指定。

启动代理时提示 failed to find OAuth application，且错误码为 NoPermission，如何处理？

报错示例：

ERROR: failed to find OAuth application 'aliyun-cli-mcp-proxy': SDKError:
   StatusCode: 401
   Code: NoPermission
   Message: code: 401, The user has no permission
   Data: {"AccessDeniedDetail":{"AuthAction":"ram:ListApplications","AuthPrincipalType":"SubUser", ...}}

代理在启动阶段需要查询或创建 OAuth 应用，此操作使用阿里云 CLI 凭据完成。上述报错表示当前 CLI 凭据对应的 RAM 用户尚未获得 AuthAction 字段所指出的权限（示例中为 ram:ListApplications）。

任选以下一种方式处理：

• 为该 RAM 用户授予所需权限，请参见步骤一：配置阿里云 CLI。

• 改用具备所需权限的凭据运行代理，例如阿里云账号或已完成授权的其他 RAM 用户。

修改 --host 或 --port 后启动失败，提示 does not have required redirect URI，如何处理？

OAuth 应用需包含本次启动所对应的回调地址，修改 --host 或 --port 会改变该地址。报错示例：

ERROR: OAuth application validation failed: OAuth application 'aliyun-cli-mcp-proxy' does not have required redirect URI 'http://172.17.0.1:8088/callback'. Available redirect URIs: [http://127.0.0.1:8088/callback]

使用 RAM 管理员身份登录 RAM 控制台，在左侧导航栏选择集成管理 > OAuth 应用（公测），在企业应用页签单击目标应用名称，然后在基本信息区域单击编辑，将报错信息中 required redirect URI 指出的地址添加到回调地址中。同一应用可保留多个回调地址，添加后原有地址仍然可用。

在 Dify 中配置后，提示“Connection Refused”或“Timeout”？

请检查以下两项：

1. mcp-proxy 服务启动时，--host 参数是否已配置为 Docker 网桥 IP 或宿主机内网 IP，以确保 Docker 容器可以访问。

2. 云服务器安全组或宿主机防火墙是否已放行从 Docker 容器到代理端口（例如 8088）的 TCP 流量。

如何查看 mcp-proxy 服务的运行日志？

若已配置为 systemd 服务，可使用以下命令实时查看日志：

sudo journalctl -u aliyun-mcp-proxy -f