OpenAPI Explorer:Gunakan aliyun mcp-proxy untuk melakukan proxy terhadap OpenAPI MCP Server

Pengenalan aliyun mcp-proxy

aliyun mcp-proxy adalah tool proxy yang disertakan dalam Alibaba Cloud CLI. Tool ini menyederhanakan cara aplikasi seperti Dify dan LangChain berinteraksi dengan OpenAPI MCP Server. Anda harus menyelesaikan proses otorisasi OAuth secara manual saat pertama kali menjalankan tool ini. Setelah itu, layanan proxy akan secara otomatis menangani penyegaran token. Aplikasi dapat memanggil API layanan Alibaba Cloud melalui proxy tanpa perlu mengelola logika autentikasi.

Cara kerja

Aplikasi mengirim permintaan API ke aliyun mcp-proxy. Layanan proxy menambahkan kredensial yang diperlukan lalu meneruskan permintaan tersebut ke OpenAPI MCP Server.

[Application] -> [aliyun mcp-proxy] -> [OpenAPI MCP Server] -> [Alibaba Cloud Service API]

Konfigurasi dan jalankan proxy

Langkah 1: Konfigurasi Alibaba Cloud CLI

1. Instal atau tingkatkan Alibaba Cloud CLI ke versi 3.2.0 atau yang lebih baru. Untuk petunjuk instalasi, lihat Instal CLI (Linux).

2. Konfigurasikan CLI menggunakan kredensial Akun Alibaba Cloud atau Pengguna Resource Access Management (RAM) yang memiliki izin untuk membuat aplikasi OAuth. Anda juga dapat menggunakan parameter --oauth-app-name pada langkah berikutnya untuk menentukan aplikasi OAuth yang sudah ada.

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

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

Saat Anda menjalankan mcp-proxy untuk pertama kalinya, Anda harus menyelesaikan otorisasi OAuth sekali saja untuk mendapatkan izin penyegaran token.

1. Jalankan proses di latar depan.

   • Di lingkungan dengan antarmuka pengguna grafis (GUI), CLI secara otomatis membuka browser untuk proses otorisasi OAuth jika Anda tidak menyertakan parameter --no-browser. Setelah otorisasi selesai, Anda tidak perlu memasukkan kode otorisasi secara manual. Anda dapat langsung melanjutkan ke Langkah 5.

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

   • Di lingkungan server tanpa GUI, tambahkan parameter --no-browser. Proses tersebut akan memandu Anda untuk mendapatkan kode otorisasi.

     aliyun 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 kondisi berikut:

   • OAuth Scope: Harus /acs/mcp-server.

   • Redirect URI: Harus sama dengan Redirect URI yang digunakan untuk autentikasi aliyun mcp-proxy.

   • Application Type: Harus berupa aplikasi tipe Native.

     

2. Terminal menampilkan URL otorisasi.

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

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

5. Saat terminal menampilkan OAuth login successful!, berarti otorisasi telah berhasil.

   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. Saat terminal menampilkan MCP Proxy Server Started, berarti proxy telah 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

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

Untuk memastikan proxy berjalan stabil, Anda dapat mengonfigurasinya sebagai layanan systemd yang otomatis dijalankan saat startup.

1. Buat file layanan systemd bernama `aliyun-mcp-proxy.service`.

   Catatan:

   • Ganti your-user dalam perintah dengan username pengguna non-root yang menjalankan perintah ini. Pengguna ini harus sama dengan pengguna yang telah mengonfigurasi kredensial menggunakan aliyun configure.

   • ExecStart dalam $(which aliyun) secara otomatis menemukan path perintah aliyun. Jika path tidak ditemukan, gantilah secara manual dengan output dari perintah which aliyun, misalnya /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. Muat ulang konfigurasi systemd dan mulai layanan tersebut.

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

Langkah 4: Verifikasi layanan proxy

Anda dapat memverifikasi apakah layanan berjalan dengan benar melalui salah satu cara berikut.

• Lihat status layanan

  Jalankan perintah berikut untuk melihat status layanan.

  sudo systemctl status aliyun-mcp-proxy

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

• Meminta port proxy

  Jalankan perintah berikut untuk mengirim permintaan langsung ke port proxy.

  curl http://127.0.0.1:8088/

  Jika proxy berfungsi dengan benar, Anda akan menerima respons error berformat XML dari MCP Server. Hal ini mengonfirmasi bahwa proxy telah terhubung ke layanan tersebut.

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

Kasus penggunaan: Integrasi Dify

Bagian ini menggunakan contoh Dify yang di-deploy dengan Docker Compose pada Instance ECS yang sama. Bagian ini menunjukkan cara mengonfigurasi dan menggunakan mcp-proxy.

Langkah 1: Dapatkan IP bridge Docker host dan mulai 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 tersebut mengembalikan alamat IP seperti 172.17.0.1.

2. Jalankan layanan mcp-proxy di foreground. Atau, Anda dapat memodifikasi perintah start di systemd lalu menjalankannya sebagai layanan.

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

Langkah 2: Konfigurasi MCP Server di Dify

1. Buka halaman konfigurasi Tools > MCP di Dify.

2. Klik Add MCP Service (HTTP).

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

   Dapatkan alamat Streamable HTTP Endpoint asli dari Konsol Layanan OpenAPI MCP Alibaba Cloud. Ganti bagian nama domain (host) dari alamat tersebut dengan alamat proxy lokal atau jaringan 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 (dengan asumsi proxy berjalan di 172.17.0.1:8088):
     http://172.17.0.1:8088/accounts/1234/custom/cli-proxy-test/id/1234/mcp
     

4. Masukkan informasi lain yang diperlukan, lalu klik Add and Authorize. Dify akan berkomunikasi dengan layanan MCP Anda melalui alamat proxy ini.

Risiko keamanan

Parameter

Perintah aliyun mcp-proxy mendukung berbagai parameter untuk menyesuaikan dengan skenario tertentu.

FAQ

Setelah saya menjalankan aliyun mcp-proxy untuk autentikasi OAuth, saya mendapatkan error "ERROR: OAuth flow returned empty RefreshToken" dan proxy gagal dijalankan. Mengapa?

Masalah ini biasanya disebabkan oleh tipe aplikasi OAuth atau identitas autentikasi yang salah. Pastikan bahwa:

• Tipe aplikasi OAuth diatur ke Native.

• Anda menggunakan akun root atau Pengguna RAM untuk autentikasi. Asumsi Peran RAM tidak mendukung pemerolehan token penyegaran OAuth.

Setelah saya mengonfigurasi proxy di Dify, saya mendapatkan error "Connection Refused" atau "Timeout". Apa yang harus saya lakukan?

Periksa konfigurasi berikut:

1. Saat menjalankan layanan mcp-proxy, pastikan parameter --host diatur ke IP bridge Docker atau IP jaringan internal host. Hal ini memastikan kontainer Docker dapat mengaksesnya.

2. Periksa apakah Grup keamanan ECS atau firewall internal host mengizinkan traffic TCP dari kontainer Docker ke port proxy, seperti 8088.

Bagaimana cara melihat log operasional layanan mcp-proxy?

Jika Anda mengonfigurasi proxy sebagai layanan systemd, Anda dapat menggunakan perintah berikut untuk melihat log secara real-time:

sudo journalctl -u aliyun-mcp-proxy -f