OpenAPI Explorer:Proxy server OpenAPI MCP menggunakan aliyun mcp-proxy

Langkah 1: Konfigurasi Alibaba Cloud CLI

1. Instal atau upgrade Alibaba Cloud CLI ke versi 3.5.0 atau lebih baru. Untuk petunjuknya, lihat Instal, update, dan uninstal Alibaba Cloud CLI.

2. Konfigurasikan CLI dengan pasangan AccessKey dari akun Alibaba Cloud atau Pengguna RAM.

   aliyun configure
   # Masukkan ID AccessKey, Rahasia AccessKey, dan wilayah default sesuai permintaan.

   Jika Anda menggunakan Pengguna RAM, berikan izin pada tabel berikut kepada Pengguna RAM tersebut.

   Izin	Tujuan	Skenario
   ram:ListApplications	Menanyakan aplikasi OAuth berdasarkan nama.	Wajib. Proxy memerlukan izin ini saat pertama kali dijalankan, atau saat informasi otorisasi lokal tidak tersedia. Izin ini juga diperlukan saat Anda menggunakan --oauth-app-name untuk menentukan aplikasi yang sudah ada.
   ram:CreateApplication	Membuat aplikasi OAuth default aliyun-cli-mcp-proxy.	Diperlukan saat Anda tidak menggunakan --oauth-app-name untuk menentukan aplikasi dan aplikasi default belum ada.
   ram:GetApplication	Menanyakan aplikasi OAuth berdasarkan ID.	Disarankan. Proxy menggunakan izin ini untuk menggunakan kembali informasi otorisasi lokal yang tersimpan. Tanpa izin ini, proxy harus menyelesaikan otorisasi OAuth baru setiap kali dijalankan.

Langkah 2: Jalankan proxy untuk pertama kali dan selesaikan otorisasi OAuth

Saat Anda menjalankan mcp-proxy untuk pertama kali, Anda harus menyelesaikan otorisasi OAuth satu kali untuk mendapatkan izin penyegaran token.

1. Jalankan proxy di foreground.

   • Di lingkungan dengan GUI, jika Anda tidak menambahkan parameter --no-browser, CLI secara otomatis membuka browser untuk menjalankan alur login otorisasi OAuth, sehingga Anda tidak perlu memasukkan kode otorisasi secara manual. Setelah otorisasi selesai, langsung lanjut ke langkah 5.

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

   • Di server tanpa GUI, tambahkan parameter --no-browser. Langkah-langkah berikut memandu Anda untuk memperoleh kode otorisasi secara manual.

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

   Catatan

   Anda dapat menggunakan parameter --oauth-app-name untuk menentukan aplikasi OAuth kustom. Aplikasi tersebut harus memenuhi persyaratan berikut:

   • Cakupan OAuth: Termasuk cakupan otorisasi yang ditentukan oleh parameter --scope. Nilai default-nya adalah /acs/mcp-server.

   • Redirect URI: Termasuk http://<host>:<port>/callback, di mana host dan port adalah nilai dari parameter --host dan --port yang Anda gunakan untuk menjalankan proxy.

   • Jenis aplikasi: Harus merupakan aplikasi NativeApp.

2. Terminal mencetak URL otorisasi.

   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. Buka URL tersebut di browser, login, dan selesaikan otorisasi.

4. Setelah otorisasi berhasil, halaman dialihkan ke alamat yang berisi parameter code, atau langsung menampilkan kode otorisasi. Salin nilai code, tempelkan ke terminal, lalu tekan Enter untuk mengonfirmasi.

5. Saat terminal menampilkan pesan OAuth login successful!, proses login otorisasi berhasil.

   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. Saat terminal menampilkan pesan MCP Proxy Server Started, proxy berhasil dijalankan.

   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

Langkah 3: Konfigurasi layanan latar belakang systemd (contoh CentOS)

Untuk menjaga proxy tetap berjalan stabil, konfigurasikan sebagai layanan systemd yang otomatis dijalankan saat boot.

1. Buat file layanan systemd: aliyun-mcp-proxy.

   Ganti konten berikut:

   • Ganti your-user dalam perintah dengan nama pengguna non-root yang sebenarnya yang menjalankan perintah ini. Pengguna ini harus telah mengonfigurasi kredensial dengan menjalankan aliyun configure, dan harus telah menyelesaikan otorisasi OAuth sebelumnya di bawah pengguna ini. Saat layanan dijalankan, proxy menggunakan kembali kredensial otorisasi yang tersimpan di direktori home pengguna ini dan tidak memicu otorisasi browser lagi.

   • ExecStart harus berisi jalur mutlak perintah aliyun. Jalankan which aliyun untuk mendapatkan jalur sebenarnya, lalu ganti /usr/local/bin/aliyun pada contoh. systemd tidak mengurai field ini melalui shell, sehingga substitusi perintah seperti $(which aliyun) tidak berlaku.

   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. Muat ulang konfigurasi systemd dan jalankan layanan.

   # Muat ulang konfigurasi
   sudo systemctl daemon-reload
   # Jalankan layanan
   sudo systemctl start aliyun-mcp-proxy
   # Aktifkan layanan agar berjalan saat boot
   sudo systemctl enable aliyun-mcp-proxy

Langkah 4: Verifikasi layanan proxy

Verifikasi bahwa layanan berjalan dengan baik menggunakan salah satu metode berikut.

• Lihat status layanan

  Jalankan perintah berikut untuk melihat status layanan.

  sudo systemctl status aliyun-mcp-proxy

  Jika output berisi active (running), layanan berhasil dijalankan.

• Request Proxy Port

  Jalankan perintah berikut untuk mengirim permintaan langsung ke port proxy.

  curl http://127.0.0.1:8088/

  Jika proxy berfungsi dengan baik, Anda akan menerima respons kesalahan XML dari server MCP, yang menunjukkan bahwa koneksi antara proxy dan layanan telah terbentuk.

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

Langkah 1: Dapatkan alamat IP bridge Docker host dan jalankan layanan mcp-proxy

Kontainer Dify harus mengakses layanan mcp-proxy melalui alamat IP bridge Docker host.

1. Jalankan perintah berikut untuk mendapatkan dan mencatat alamat IP tersebut.

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

   Perintah ini mengembalikan alamat IP seperti 172.17.0.1.

2. Jalankan layanan mcp-proxy di foreground. Atau, modifikasi perintah startup di systemd lalu jalankan layanan.

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

   Catatan

   Alamat callback ditentukan oleh parameter --host dan --port. Setelah Anda mengubah alamat listen dari 127.0.0.1 ke alamat IP bridge Docker, tambahkan alamat callback baru (misalnya, http://172.17.0.1:8088/callback) ke aplikasi OAuth yang sesuai di Konsol RAM pada bagian Integrations > OAuth Applications (Public Preview). Jika tidak, startup akan gagal karena alamat callback tidak lolos validasi.

Langkah 2: Konfigurasi server MCP di Dify

1. Buka halaman konfigurasi Tools > MCP di Dify.

2. Klik Add MCP Server (HTTP).

3. Pada bidang Server Endpoint URL, masukkan alamat proxy MCP.

   Di konsol Layanan OpenAPI MCP Alibaba Cloud, dapatkan alamat asli Streamable HTTP Endpoint, lalu ganti bagian domain (host) dari alamat tersebut dengan alamat proxy lokal atau internal Anda.

   Contoh konversi:

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

   • Ganti dengan alamat proxy (asumsikan proxy berjalan di 172.17.0.1:8088): http://172.17.0.1:8088/accounts/1234/custom/cli-proxy-test/id/1234/mcp

4. Isi informasi lainnya sesuai kebutuhan lalu klik Add & Authorize. Dify berkomunikasi dengan layanan MCP melalui alamat proxy ini.

Mitigasi

• Isolasi lingkungan — Jalankan proxy hanya di lingkungan single-user yang tepercaya, dan hindari penggunaannya di server bersama multi-pengguna.

• Kontrol akses jaringan — Ikat alamat listen proxy (--host) ke 127.0.0.1 (default) atau alamat IP internal tertentu. Gunakan aturan firewall atau grup keamanan untuk membatasi cakupan akses ke port proxy (misalnya, hanya izinkan akses dari alamat IP server aplikasi tertentu), dan jangan pernah mengekspos port tersebut ke Internet.

• Kontrol akses — Gunakan parameter --allowed-servers atau --blocked-servers untuk membatasi cakupan server MCP yang dapat diakses dan mencegah proxy digunakan untuk mengakses layanan yang tidak dimaksudkan. Untuk petunjuknya, lihat Konfigurasi kontrol akses server.

• Prinsip hak istimewa minimal — Konfigurasikan akses hak istimewa minimal untuk pengguna CLI yang digunakan proxy dan server MCP terkait. Berikan izin read-only terlebih dahulu.

• Audit dan pemantauan — Tinjau log akses layanan proxy secara berkala dan pantau permintaan mencurigakan. Permintaan yang diblokir oleh kontrol akses dicatat dalam log proxy.

Konfigurasi kontrol akses server

aliyun utils mcp-proxy mendukung mekanisme daftar putih dan blacklist untuk membatasi cakupan server MCP yang dapat diakses melalui proxy.

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

Respons insiden keamanan

Jika Anda mencurigai token autentikasi proxy bocor atau disalahgunakan, segera lakukan tindakan berikut:

• Hentikan layanan mcp-proxy.

• Hapus file konfigurasi lokal: rm ~/.aliyun/.mcpproxy_config.

• Hapus aplikasi OAuth untuk membatalkan secara permanen token penyegaran yang bocor. Login ke Konsol RAM sebagai administrator RAM. Di panel navigasi kiri, pilih Integrations > OAuth Applications (Public Preview). Pada tab Enterprise Applications, klik Delete Application di kolom Actions aplikasi target. Anda juga dapat menggunakan CLI untuk menghapus aplikasi tersebut. Setelah dihapus, saat Anda menyelesaikan otorisasi OAuth lagi, CLI secara otomatis membuat aplikasi baru.

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

• Periksa log panggilan API untuk memastikan apakah terdapat operasi mencurigakan.

• Jalankan ulang proxy dan selesaikan otorisasi OAuth untuk mendapatkan token baru.

Setelah menjalankan aliyun utils mcp-proxy untuk autentikasi OAuth, muncul error “ERROR: OAuth flow returned empty RefreshToken” dan proxy gagal dijalankan. Mengapa?

Kesalahan ini menunjukkan bahwa aplikasi OAuth yang sedang digunakan bukan aplikasi NativeApp, sehingga tidak dapat mengembalikan token penyegaran dalam alur otorisasi. Tangani masalah ini dengan salah satu cara berikut:

• Hapus aplikasi OAuth lalu jalankan ulang proxy. CLI secara otomatis membuat aplikasi NativeApp.

• Buat secara manual aplikasi NativeApp, lalu tentukan aplikasi tersebut menggunakan --oauth-app-name saat menjalankan proxy.

Apa yang harus saya lakukan jika muncul error “failed to find OAuth application” dengan kode error NoPermission saat menjalankan proxy?

Contoh error:

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", ...}}

Selama tahap startup, proxy perlu menanyakan atau membuat aplikasi OAuth, dan operasi ini dilakukan menggunakan kredensial Alibaba Cloud CLI. Error di atas menunjukkan bahwa Pengguna RAM yang sesuai dengan kredensial CLI saat ini belum diberikan izin yang ditentukan oleh bidang AuthAction (ram:ListApplications dalam contoh ini).

Tangani masalah ini dengan salah satu cara berikut:

• Berikan izin yang diperlukan kepada Pengguna RAM. Untuk informasi lebih lanjut, lihat Langkah 1: Konfigurasi Alibaba Cloud CLI.

• Jalankan proxy menggunakan kredensial yang memiliki izin yang diperlukan, seperti akun Alibaba Cloud atau Pengguna RAM lain yang telah menyelesaikan otorisasi.

Apa yang harus saya lakukan jika startup gagal dengan error “does not have required redirect URI” setelah mengubah --host atau --port?

Aplikasi OAuth harus berisi alamat callback yang sesuai dengan startup saat ini. Mengubah --host atau --port mengubah alamat ini. Contoh error:

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]

Login ke Konsol RAM sebagai administrator RAM. Di panel navigasi kiri, pilih Integrations > OAuth Applications (Public Preview). Pada tab Enterprise Applications, klik nama aplikasi target. Di bagian Basic Information, klik Edit, lalu tambahkan alamat yang ditunjukkan oleh required redirect URI dalam pesan error ke daftar alamat callback. Aplikasi yang sama dapat menyimpan beberapa alamat callback, dan alamat yang sudah ada tetap tersedia setelah Anda menambahkan yang baru.

Apa yang harus saya lakukan jika muncul “Connection Refused” atau “Timeout” setelah mengonfigurasi proxy di Dify?

Periksa dua hal berikut:

1. Saat layanan mcp-proxy dijalankan, periksa apakah parameter --host diatur ke alamat IP bridge Docker atau alamat IP internal host, sehingga kontainer Docker dapat mengakses layanan tersebut.

2. Periksa apakah grup keamanan server cloud atau firewall host mengizinkan traffic TCP dari kontainer Docker ke port proxy (misalnya, 8088).

Bagaimana cara melihat log runtime layanan mcp-proxy?

Jika proxy dikonfigurasi sebagai layanan systemd, jalankan perintah berikut untuk melihat log secara real-time:

sudo journalctl -u aliyun-mcp-proxy -f