OpenAPI MCP Server - OpenAPI Explorer

Model Context Protocol (MCP) adalah protokol standar yang memungkinkan Large Language Models (LLMs) berinteraksi dengan alat eksternal dan sumber data, seperti API dan database. Dengan memusatkan logika pemanggilan alat di dalam server, MCP memungkinkan LLM memanggil berbagai fungsi melalui satu protokol terpadu. Topik ini menjelaskan cara membuat dan menggunakan OpenAPI MCP Server agar LLM dapat mengelola sumber daya Alibaba Cloud Anda melalui pemanggilan API.

Buat server MCP

Catatan

Jika Anda melakukan tugas ini sebagai Pengguna RAM, Anda harus memiliki izin yang diperlukan. Untuk informasi selengkapnya, lihat Berikan izin pada OpenAPI MCP Server kepada Pengguna RAM.

Buka halaman OpenAPI MCP Server, klik tab Create an MCP Server, lalu konfigurasikan parameter berikut:

Catatan

Karena batasan panjang konteks dan pemilihan alat pada sebagian besar LLM, kami menyarankan untuk menambahkan tidak lebih dari 30 API ke satu server MCP. Jika Anda perlu menggunakan lebih banyak API, buat beberapa server MCP.

Parameter	Deskripsi
Name	Nama harus terdiri dari 3 hingga 16 karakter dan hanya boleh berisi huruf kecil, angka, tanda hubung (-), dan garis bawah (_). Contoh: `mcp-demo`.
Document Language	Bahasa untuk deskripsi API dalam alat yang dihasilkan.
OAuth Configuration	Alibaba Cloud Official OAuth: Cocok untuk klien lokal, seperti AI Coding Assistant Lingma, Cherry Studio, dan Cursor. Catatan Administrator RAM harus menginstal dan menetapkan aplikasi OpenAPI MCP Server resmi dari halaman RAM console > OAuth Preview > Third-party Application. Jika tidak dilakukan, otorisasi OAuth untuk server MCP Anda akan gagal. Untuk informasi selengkapnya, lihat Instal dan otorisasi aplikasi pihak ketiga. Custom OAuth: Cocok untuk platform yang dikelola sendiri dan layanan pihak ketiga, seperti Dify, AgentScope, dan Claude.
Multi-account MCP	Tentukan apakah akan mengaktifkan manajemen terpusat server MCP di beberapa akun. Untuk informasi selengkapnya, lihat Gunakan OpenAPI MCP Server dalam skenario multi-akun.
List of Cloud Products and APIs	Konfigurasikan layanan cloud dan API-nya untuk server MCP. Anda hanya dapat memilih API untuk satu layanan cloud dalam satu waktu. Untuk menambahkan API dari layanan lain, klik Add Cloud Products and APIs setelah mengonfirmasi pilihan saat ini. Untuk menambahkan lebih banyak API untuk layanan yang sudah ditambahkan, klik Add APIs.
Terraform Tools	Integrasikan alat Terraform ke dalam server MCP melalui kode Terraform HCL. Untuk informasi selengkapnya, lihat Gunakan alat Terraform di OpenAPI MCP Server. Catatan Alat Terraform hanya mendukung pembuatan resource, bukan modifikasi resource.
System Tools	System tools adalah alat resmi bawaan. Jika dipilih, alat tersebut akan diintegrasikan ke dalam server MCP Anda.
Description	Tambahkan deskripsi untuk server MCP.

Klik Create dan konfirmasi peringatan risiko. Setelah server dibuat, sistem menyediakan endpoint Streamable HTTP, endpoint SSE, dan detail konfigurasi klien. Informasi ini diperlukan untuk menghubungkan klien ke server MCP.

Konfigurasikan server MCP di klien

Anda dapat menggunakan server MCP di klien umum, seperti Cherry Studio, Cursor, Lingma, dan Cline. Ikuti metode konfigurasi sesuai klien Anda.

Catatan

Jika Anda menggunakan server MCP di Dify, lihat Integrasikan server OpenAPI MCP di Dify.

Konfigurasi satu-klik

Catatan

Anda harus menginstal Cherry Studio atau Cursor terlebih dahulu.

Jika Anda menggunakan server MCP di Cherry Studio atau Cursor, Anda dapat menggunakan fitur one-click configuration untuk mengonfigurasinya.

Konfigurasi manual

Cherry Studio

Catatan

Pastikan Cherry Studio telah diinstal.

Konfigurasikan model server di Cherry Studio.
1. Kami menyarankan menggunakan model qwen3-235b-a22b dari Alibaba Cloud Model Studio.
  Kunci API dihasilkan di konsol Model Studio. Alamat API adalah https://dashscope.aliyuncs.com/compatible-mode/v1/.
2. Setelah menambahkan model, edit model tersebut untuk mengonfigurasi kemampuan seperti networking, inference, dan tools.
Konfigurasikan server MCP.
1. Pada bagian Settings > MCP Servers, tambahkan server.
2. Konfigurasikan server MCP. Masukkan nama, pilih Streamable HTTP sebagai tipe, dan untuk URL, masukkan Streamable HTTP endpoint yang diberikan saat Anda membuat server MCP.
3. Klik Save. Sistem kemudian akan mengarahkan Anda ke halaman User Authorization. Tinjau informasi otorisasi, lalu klik Authorize. Untuk pengenalan OAuth secara mendetail, lihat OAuth Management.
  Catatan
  Anda harus memberikan izin operasi API yang diperlukan kepada Pengguna RAM yang berpartisipasi dalam otorisasi sebelumnya. Jika tidak, kesalahan izin dapat terjadi. Untuk informasi selengkapnya, lihat Berikan izin kepada Pengguna RAM.
  Setelah otorisasi selesai, Cherry Studio secara otomatis menjalankan server MCP.

Cursor

Catatan

Pastikan Cursor telah diinstal. Contoh ini menggunakan Free Edition Cursor. Anda dapat mengunduh edisi yang sesuai dengan kebutuhan Anda.

Pada bilah menu Cursor, pilih File > Preferences > Cursor Settings > Tools & Integrations, lalu klik Add Custom MCP untuk mengonfigurasi server MCP.
Dari halaman detail server MCP, salin konfigurasi klien dalam format JSON, tempelkan ke file mcp.json, lalu tekan Ctrl+S untuk menyimpan.
Selesaikan otorisasi di halaman User Authorization. Untuk pengenalan OAuth secara mendetail, lihat OAuth Management.
Catatan
Anda harus memberikan izin operasi API yang diperlukan kepada Pengguna RAM yang berpartisipasi dalam otorisasi sebelumnya. Jika tidak, kesalahan izin dapat terjadi. Untuk informasi selengkapnya, lihat Berikan izin kepada Pengguna RAM.
Anda dapat melihat informasi server MCP yang dikonfigurasi di Cursor Settings.

AI Coding Assistant Lingma

Catatan

Pastikan Lingma telah diinstal.

Buka plugin Lingma dan klik MCP tools pada halaman pengantar.
Di pojok kanan atas jendela pop-up, klik ikon + lalu pilih Add manually.

Pada jendela Add MCP Server, konfigurasikan parameter berikut lalu klik Add.

Name	Nama server MCP. Kami menyarankan agar sama dengan nama yang Anda masukkan di halaman Alibaba Cloud OpenAPI MCP Server.
Type	Pilih `STDIO`.
Command	Masukkan `npx`.
Arguments	Formatnya adalah `mcp-remote-alibaba-cloud <SSE Endpoint>`. Catatan Hanya SSE Endpoint yang didukung. Dapatkan SSE Endpoint dari detail yang disediakan setelah Anda membuat layanan MCP.

Selesaikan otorisasi di halaman User Authorization. Untuk pengenalan OAuth secara mendetail, lihat OAuth Management.
Catatan
Anda harus memberikan izin operasi API yang diperlukan kepada Pengguna RAM yang berpartisipasi dalam otorisasi sebelumnya. Jika tidak, kesalahan izin dapat terjadi. Untuk informasi selengkapnya, lihat Berikan izin kepada Pengguna RAM.
Gambar berikut menunjukkan konfigurasi server MCP yang berhasil di Lingma:

Cline

Catatan

Pastikan plugin Cline telah diinstal di IDE Anda. Topik ini menggunakan VS Code sebagai contoh. Untuk informasi selengkapnya, lihat Cline.

Buka plugin Cline di VS Code dan masukkan kunci API Anda.
Pada bilah menu atas, klik MCP Servers untuk mengonfigurasi server MCP.
Selesaikan otorisasi di halaman User authorization. Untuk pengenalan OAuth secara mendetail, lihat OAuth Management.
Catatan
Anda harus memberikan izin operasi API yang diperlukan kepada Pengguna RAM yang berpartisipasi dalam otorisasi sebelumnya. Jika tidak, kesalahan izin dapat terjadi. Untuk informasi selengkapnya, lihat Berikan izin kepada Pengguna RAM.
Setelah otorisasi selesai, konfigurasi berhasil jika server MCP yang baru dikonfigurasi muncul di bagian MCP Servers di bagian bawah Cline.

Inspector

Catatan

Bagian ini hanya memberikan pengenalan singkat. Untuk informasi selengkapnya, lihat Inspector.
Versi Node.js Anda harus 22.7.5 atau lebih baru.

Di terminal, jalankan perintah berikut untuk memulai Inspector. Setelah dimulai, Anda dapat mengaksesnya di http://localhost:6274 secara default.
```
npx @modelcontextprotocol/inspector
```
Pada panel navigasi kiri klien MCP Inspector, pilih tipe transport. Contoh ini menggunakan Streamable HTTP. Di kolom URL, masukkan Streamable HTTP endpoint yang dihasilkan saat Anda membuat server MCP, lalu klik Connect.
Selesaikan otorisasi di halaman User Authorization. Untuk pengenalan OAuth secara mendetail, lihat OAuth Management.
Catatan
Anda harus memberikan izin operasi API yang diperlukan kepada Pengguna RAM yang berpartisipasi dalam otorisasi sebelumnya. Jika tidak, kesalahan izin dapat terjadi. Untuk informasi selengkapnya, lihat Berikan izin kepada Pengguna RAM.
Setelah otorisasi selesai, Anda dapat melihat informasi server MCP di tab Tools.
Anda dapat mengklik alat apa pun untuk melihat detailnya di sebelah kanan. Anda juga dapat mengatur parameter untuk menjalankan alat tersebut.

Gunakan server MCP

Setelah dikonfigurasi, Anda dapat menggunakan server MCP untuk mengelola sumber daya cloud Anda. Untuk informasi selengkapnya, lihat bagian "Metode lain untuk mengintegrasikan server MCP" dalam topik ini.

Cherry Studio

Dari menu kotak teks, pilih server MCP.
Uji server MCP. Misalnya, Anda dapat mengkueri instance ECS di suatu wilayah:
```
Please query the ECS instances in region cn-chengdu and set x_mcp_region_id to cn-chengdu.
```
Catatan
Hasilnya akan akurat jika server MCP memilih API yang benar dan mengonfigurasi parameter permintaan dengan tepat. Jika terjadi kesalahan, Anda dapat mencoba mengubah konfigurasi server MCP untuk mengatasinya.

Cursor

Pilih model dan kunci API. Karena Cursor memiliki persyaratan khusus untuk penyedia LLM, lihat Supported providers untuk informasi selengkapnya. Contoh ini menggunakan nilai default.
Di kotak dialog Cursor, klik Add Context dan pilih server MCP Anda.
Di kotak dialog, masukkan kueri bahasa alami untuk menguji server MCP Anda. Misalnya, masukkan "Please query the number of ECS instances in the China (Chengdu) region and show only the instance count" lalu tekan Enter. Saat diminta, klik Run tool untuk melanjutkan.
Lihat hasil eksekusi. Hasilnya akan akurat jika server MCP memilih API yang benar dan mengonfigurasi parameter permintaan dengan tepat. Jika terjadi kesalahan, Anda dapat mencoba mengubah konfigurasi server MCP untuk mengatasinya.

Lingma

Di Lingma, pilih model dari daftar drop-down Agent dan masukkan prompt. Misalnya, untuk mengkueri instance ECS di wilayah China (Chengdu), Anda harus mengatur x_mcp_region_id ke ID wilayah tersebut.
Ikuti petunjuk di Lingma untuk mengeksekusi tugas.
Lihat hasilnya. Hasilnya akan akurat jika server MCP memilih API yang benar dan mengonfigurasi parameter permintaan dengan tepat. Jika terjadi kesalahan, Anda dapat mencoba mengubah konfigurasi server MCP untuk mengatasinya.

Cline

Di jendela dialog Cline, masukkan kueri bahasa alami untuk menguji server MCP Anda. Misalnya, masukkan "Please query the number of ECS instances in the China (Chengdu) region."
Gambar di atas menunjukkan bahwa Cline menggunakan server MCP yang dikonfigurasi dan memilih API DescribeInstances. Nilai parameter RegionId juga diambil dari input.
Tinjau hasil eksekusi. Hasilnya akan akurat jika server MCP memilih API yang benar dan mengonfigurasi parameter permintaan dengan tepat. Jika terjadi kesalahan, Anda dapat mencoba mengubah konfigurasi server MCP untuk mengatasinya.

Ubah konfigurasi server MCP untuk meningkatkan akurasi output

Jika LLM memberikan respons yang tidak akurat berdasarkan server MCP, Anda dapat mengubah ikhtisar API, deskripsi, atau deskripsi parameter permintaan di halaman detail server MCP untuk meningkatkan pemahamannya tentang fitur API. Contoh berikut menunjukkan cara mengubah konfigurasi server MCP.

Contoh 1: Kesalahan atau data tidak akurat saat mengoperasikan resource di luar wilayah China (Hangzhou)

Server MCP menggunakan x_mcp_region_id untuk mengalihkan endpoint. Jika LLM gagal memahami dari input Anda bahwa ia harus melewatkan x_mcp_region_id, maka secara default akan mengoperasikan resource di wilayah China (Hangzhou).

Anda dapat mengatasi masalah ini dengan salah satu dari dua cara berikut:

Beritahu secara eksplisit LLM mengenai nilai x_mcp_region_id yang diinginkan dalam prompt Anda.
```
Query the ECS instances in the China (Qingdao) region and set x_mcp_region_id to cn-qingdao.
```
Sesuaikan ikhtisar API atau deskripsi parameter RegionId di halaman detail server MCP.
Misalnya, Anda dapat menambahkan "Pass the user-specified region to x_mcp_region_id" ke ikhtisar API. Atau, Anda dapat menambahkan "If the RegionId parameter is specified, it must be passed along with x_mcp_region_id" ke deskripsi RegionId.
Prosedur
1. Buka halaman View MCP Servers, temukan server MCP yang diinginkan lalu klik Edit di kolom Actions.
2. Pilih API yang diinginkan lalu klik Edit di kolom Actions.
3. Ubah ikhtisar API, deskripsi permintaan, dan deskripsi parameter.
4. Setelah menyimpan perubahan, putuskan koneksi dari server MCP di klien lalu sambungkan kembali agar perubahan berlaku.

Contoh 2: Hapus parameter opsional dari API

Dokumen API mencakup parameter untuk semua kasus penggunaan yang mungkin, tetapi beberapa parameter opsional mungkin tidak diperlukan dalam sebagian besar kasus penggunaan. Anda dapat menghapus parameter opsional ini di server MCP. Saat melewatkan parameter, LLM tidak akan mengakses parameter yang dihapus. Hal ini mengurangi tingkat kesalahan model dan menurunkan penggunaan token.

Kontrol akses untuk server MCP

Agen AI yang diintegrasikan dengan OpenAPI MCP Server tidak memiliki identitas atau izin bawaan untuk mengakses Alibaba Cloud. Agen tersebut bertindak sebagai proxy, melakukan operasi atas nama pengguna. Alur kerja dimulai oleh klien melalui alur OAuth. Setelah pengguna memberikan persetujuan, agen AI menerima kredensial sementara. Semua operasi selanjutnya dilakukan di bawah identitas pengguna dan dibatasi oleh izin pengguna tersebut. Hal ini memastikan kepatuhan terhadap prinsip hak istimewa minimal dan menyediakan auditabilitas yang jelas, karena semua tindakan dicatat di ActionTrail di bawah identitas pengguna yang memberikan otorisasi.

Agen yang berlaku: Cherry Studio, Lingma, Qwen Code, Cursor, Claude Code, Dify, AgentScope, dan LangGraph.

FAQ

1. Dapatkah klien MCP memanggil semua API yang didefinisikan dalam toolset?

Tidak selalu. Keberhasilan pemanggilan API bergantung pada izin Pengguna RAM yang mengotorisasi klien. Jika pengguna tidak memiliki izin untuk memanggil API tertentu, upaya LLM untuk memanggilnya juga akan gagal.

Untuk mengatasi hal ini, administrator RAM harus memberikan izin yang diperlukan kepada Pengguna RAM. Untuk informasi selengkapnya, lihat Berikan izin kepada Pengguna RAM.

Penting

Untuk mencegah kehilangan data yang tidak disengaja, hindari memberikan izin kepada Pengguna RAM untuk tindakan destruktif, seperti menghapus resource. LLM dapat salah memahami prompt dan memanggil API penghapusan, yang dapat berdampak negatif pada bisnis Anda.

2. Saat saya masuk sebagai Pengguna RAM, mengapa saya menerima kesalahan "permission denied" saat membuat server MCP?

Minta administrator RAM untuk menyambungkan kebijakan AliyunOpenAPIMCPServerFullAccess ke akun Pengguna RAM Anda. Untuk informasi selengkapnya, lihat Berikan izin kepada Pengguna RAM.
Atau, minta administrator RAM untuk menyambungkan kebijakan kustom ke akun Pengguna RAM Anda:
1. Administrator RAM dapat membuat kebijakan kustom di RAM console. Untuk informasi selengkapnya, lihat Buat kebijakan kustom.
  Isi kebijakan adalah sebagai berikut:
  Kebijakan akses untuk server MCP
  Kebijakan ini memberikan izin untuk membuat, memperbarui, mengkueri, dan menghapus server MCP. Kebijakan ini juga memberikan izin untuk mengkueri alat sistem server MCP.
```
{
  "Version": "1",
  "Statement": [
    {
      "Action": [
        "openapiexplorer:*Mcp*",
        "ram:*Application*"
      ],
      "Resource": "*",
      "Effect": "Allow"
    }
  ]
}
```
2. Minta administrator RAM untuk menyambungkan kebijakan kustom ke akun Pengguna RAM Anda. Untuk informasi selengkapnya, lihat Berikan izin kepada Pengguna RAM.

3. Jika endpoint server MCP terpapar, apakah siapa pun dapat menggunakannya?

Tidak. Bahkan jika endpoint terpapar, pihak yang tidak sah tidak dapat menggunakannya. Saat klien terhubung ke endpoint, sistem memulai alur OAuth yang mengharuskan pengguna untuk mengotentikasi dan memberikan persetujuan. Sistem kemudian memvalidasi bahwa akun pengguna cocok dengan akun pemilik server MCP. Akses hanya diberikan jika akun tersebut cocok.

Cara lain untuk mengintegrasikan MCP

Integrasikan dengan Dify menggunakan konfigurasi aplikasi OAuth kustom. Didukung di Dify 1.8.0 dan versi yang lebih baru. Untuk informasi selengkapnya, lihat Integrasikan server OpenAPI MCP di Dify.
Integrasikan dengan agen menggunakan SDK MCP resmi untuk menangani alur OAuth. Untuk informasi selengkapnya, lihat Integrasikan server OpenAPI MCP dengan agen AI.