Alibaba Cloud CLI：使用 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 Proxy 位址。

   在阿里雲 OpenAPI MCP 服務控制台擷取原始的 Streamable HTTP Endpoint 地址，並將該地址中的網域名稱部分（host）替換為本地或內網Proxy 位址。

   樣本轉換：

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

   • 替換為Proxy 位址（假設代理運行在 172.17.0.1:8088）：http://172.17.0.1:8088/accounts/1234/custom/cli-proxy-test/id/1234/mcp

4. 按需填入其他資訊後點擊添加並授權。Dify 將通過該Proxy 位址與 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