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

步驟一：配置阿里雲 CLI

1. 安裝或升級阿里雲 CLI，確保版本不低於 3.2.0。安裝方法，請參見安裝CLI（Linux）。

2. 使用具備建立 OAuth 應用許可權的阿里雲帳號或 RAM 使用者憑證配置 CLI。也可在後續步驟中使用 --oauth-app-name 參數指定一個已建立的 OAuth 應用。

   aliyun configure
   # 根據提示輸入AccessKey ID、AccessKey Secret和預設地區。

步驟二：首次運行代理並完成 OAuth 授權

首次運行 mcp-proxy 時，需完成一次性 OAuth 授權以擷取重新整理 Token 的許可權。

1. 在前台啟動。

   • 在有圖形介面的環境中，不帶--no-browser參數時，CLI 會自動拉起瀏覽器執行 OAuth 授權登入流程，完成授權後無需手動輸入code。完成後您可直接跳至第5步。

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

   • 在無圖形介面的伺服器環境中操作時，請添加--no-browser參數，後續將引導您擷取code。

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

   說明

   您可以使用 --oauth-app-name 參數指定自訂 OAuth 應用，該應用必須滿足以下條件：

   • Oauth範圍（Scope）：必須為 /acs/mcp-server。

   • 回調地址（Redirect URI）：必須與 aliyun mcp-proxy 認證時使用的回調地址一致。

   • 應用類型：必須為Native類型的應用。

     

2. 終端將輸出授權 URL。

   Setting up MCPOAuth profile 'default-mcp'...
   Opening browser for OAuth login...
   URL: https://signin.aliyun.com/oauth2/v1/auth?client_id=XXX8&response_type=code&scope=%2Facs%2Fmcp-server&redirect_uri=http://0.0.0.0: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 successfully, code received: XXXX
   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

步驟三：配置為 systemd 後台服務（以CentOS為例）

為確保代理穩定運行，建議將其配置為開機自啟的 systemd 服務。

1. 建立 systemd 服務檔案：aliyun-mcp-proxy。

   說明：

   • 將命令中的 your-user 替換為實際運行此命令的非 root 使用者名稱。該使用者必須是已通過 aliyun configure 配置憑據的使用者。

   • ExecStart 中的 $(which aliyun) 可自動定位 aliyun 命令路徑。如果定位失敗，可手動將其替換為 which aliyun 命令的輸出結果（例如 /usr/local/bin/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=$(which aliyun) 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.aliyun.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. 在前台啟動 aliyun mcp-proxy 代理服務。或者，在 systemd 中修改啟動命令然後通過服務啟動。

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

步驟二：在 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 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

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

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

Available Servers:
  - ecs
    MCP: http://127.0.0.1:8088/acs/mcp-server/ecs/mcp
  - oss
    MCP: http://127.0.0.1:8088/acs/mcp-server/oss/mcp
  - ram (blocked)

安全事件處理

如果懷疑代理認證 Token 泄露或被濫用，立即執行以下操作：

• 停止 MCP Proxy 服務。

• 刪除本地設定檔：rm ~/.aliyun/.mcpproxy_config。

• 在阿里雲控制台撤銷 OAuth 授權。

• 檢查 API 呼叫日誌，確認是否存在異常操作。

• 重新設定 MCP Proxy 並產生新的 Token。

執行 aliyun mcp-proxy 進行 OAuth 認證後，出現 “ERROR: OAuth flow returned empty RefreshToken” 錯誤且代理啟動失敗，是什麼原因？

此問題通常是由於 OAuth 應用類型或認證身份不正確導致。請確保：

• 使用的 OAuth 應用類型為 Native 類型。

• 使用主帳號或 RAM 使用者進行認證，RAM 角色扮演不支援擷取OAuth Refresh Token。

在 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