MCP server

Di mana letaknya di portal: API reference › Tools (https://<your-domain>/apidoc) menampilkan snippet endpoint dan klien; kunci dibuat di API keys (/api-keys). Tidak ada pengaturan di admin: endpoint ini merupakan bagian dari panel.

Fungsi

Model Context Protocol (MCP) memungkinkan asisten AI memanggil tool. NexCMP menyediakan endpoint MCP di https://<your-domain>/mcp. Setiap operasi API publik menjadi satu tool (vm_list, vm_start, billing_wallet, ...), sehingga pelanggan dapat bertanya kepada asisten mereka "VM mana saja milik saya yang sedang berjalan?" atau "hentikan VM staging". Asisten bertindak hanya dengan kunci API dan izin milik pelanggan itu sendiri.

Mengonfigurasi NexCMP itu sendiri dengan AI?

Halaman ini adalah endpoint MCP pelanggan (/mcp). Untuk membiarkan asisten AI mengonfigurasi panel Anda sendiri sebagai administrator, lihat Configure with AI (endpoint /mcp/admin, kunci admin ak_).

Persyaratan

Item	Persyaratan
Server	Tidak ada yang perlu diinstal: endpoint dilayani oleh panel dan dapat dijangkau di mana pun panel berada. Reverse proxy Anda harus meneruskan /mcp ke panel.
Pelanggan	Sebuah API key (vk_...) dengan cakupan (scope) yang dibutuhkan oleh asisten.
Klien	Klien MCP yang mendukung transpor Streamable HTTP dan header kustom Authorization: Claude Code, Claude Desktop (melalui bridge mcp-remote), Cursor, VS Code dengan mode agen Copilot, dan sejenisnya.
Versi protokol	2025-11-25, 2025-06-18, dan 2025-03-26.

Siapkan infrastruktur

Tidak ada, selain memastikan https://<your-domain>/mcp tidak diblokir oleh firewall atau aturan proxy. Klien MCP berbasis browser dari origin lain akan ditolak kecuali origin tersebut diizinkan; klien command-line dan desktop tidak mengirim header Origin dan berfungsi sebagaimana mestinya.

Menghubungkan (sisi pelanggan)

1. Buat kunci API di portal (API keys › Create key) hanya dengan cakupan yang ingin Anda gunakan untuk asisten, masa kedaluwarsa yang singkat, dan jika memungkinkan, pembatasan IP.

2. Tambahkan server ke klien Anda. Ganti cloud.example.com dan kuncinya.

   Claude Code

   claude mcp add --transport http cloud https://cloud.example.com/mcp \
     --header "Authorization: Bearer vk_XXXX"

   Cursor (~/.cursor/mcp.json atau .cursor/mcp.json; tetapkan CLOUD_API_KEY di environment tempat Cursor dijalankan):

   {
     "mcpServers": {
       "cloud": {
         "url": "https://cloud.example.com/mcp",
         "headers": { "Authorization": "Bearer ${env:CLOUD_API_KEY}" }
       }
     }
   }

   Claude Desktop (memerlukan Node.js 18+; claude_desktop_config.json), melalui bridge mcp-remote:

   {
     "mcpServers": {
       "cloud": {
         "command": "npx",
         "args": ["-y", "mcp-remote", "https://cloud.example.com/mcp", "--header", "Authorization:${CLOUD_AUTH_HEADER}"],
         "env": { "CLOUD_AUTH_HEADER": "Bearer vk_XXXX" }
       }
     }
   }

   Tulis header tanpa spasi setelah titik dua dan masukkan seluruh nilai ke dalam variabel environment, seperti di atas.

3. Muat ulang klien dan minta untuk mencantumkan tool Anda.

Periksa koneksi tanpa klien:

curl -s https://cloud.example.com/mcp \
  -H "Authorization: Bearer vk_XXXX" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Cara kerja

Item	Detail
Endpoint	POST /mcp dengan pesan JSON-RPC 2.0; jawabannya adalah application/json. GET /mcp menjawab 405 (tidak ada stream server-to-client); DELETE /mcp mengakhiri sesi.
Autentikasi	Hanya Authorization: Bearer vk_... (token sesi, cookie, dan kunci admin ditolak dengan 401 dan header WWW-Authenticate: Bearer).
Sesi	Mcp-Session-Id diterbitkan oleh initialize, terikat ke kunci tersebut, berlaku selama 24 jam; maksimal 16 sesi per kunci.
Peralatan	Satu untuk setiap operasi API publik yang terlihat oleh kunci. Nama tool adalah perintah CLI dengan _ sebagai pengganti spasi dan tanda hubung (vm firewall add menjadi vm_firewall_add) dan sama dengan operationId pada OpenAPI. Tool dicantumkan hanya jika kunci memiliki cakupannya dan modul diaktifkan.
Kapabilitas	Hanya tool (tidak ada resource atau prompt).
Ukuran	Body request hingga 1 MB; teks hasil tool hingga sekitar 100 KB (sisanya dipotong dengan catatan); panggilan memakan waktu paling lama 55 detik.

Aturan keamanan

• Gerbang yang sama seperti REST. Setiap tools/call melalui pipeline permintaan panel sendiri: cakupan, situs, pembatasan IP, batas laju, idempotensi, pemeriksaan kepemilikan (404 untuk sumber daya milik orang lain), dan kuota semuanya berlaku. MCP tidak dapat memberikan apa pun yang tidak dimiliki oleh kunci tersebut.
• Konfirmasi. Alat yang memerlukan biaya, menghapus, atau mengembalikan kredensial (tiket konsol, kubeconfig, rahasia S3 atau SSH, pengaturan ulang kata sandi, kunci baru) memerlukan argumen confirm: true. Deskripsi alat menginstruksikan asisten untuk meneruskannya hanya setelah pengguna menyetujui, sehingga instruksi yang disembunyikan di halaman web atau log tidak dapat memicunya sendiri.
• Idempotensi. Alat berbayar menerima idempotency_key; jika diabaikan, kunci yang stabil akan turunan dari nama alat dan argumennya, sehingga percobaan ulang yang identik tidak dapat menagih dua kali.
• Tidak diekspos sebagai alat: titik akhir streaming (obrolan AI Agent), tiket WebSocket SSH atau konsol satu kali, unduhan biner, dan titik akhir aplikasi VPN (/v1/ext/*).
• Tidak pernah diizinkan: API tidak pernah mengizinkan isi ulang, perubahan kata sandi, penghapusan akun, atau pembuatan kunci, sehingga tidak ada asisten yang dapat melakukannya.

Batas

Batas	Default
Pemanggilan alat per kunci	60 per menit
Permintaan MCP per kunci	240 per menit
Ditambah batas kunci dan akun normal	Lihat REST API

Melebihi batas, titik akhir akan menjawab HTTP 429 dengan galat JSON-RPC dan Retry-After.

Verifikasi

1. Perintah curl di atas mengembalikan hasil JSON-RPC dengan daftar tools. Hanya alat yang cocok dengan cakupan kunci yang akan muncul.
2. Di klien Anda, tanyakan "list my VMs": asisten memanggil vm_list dan menampilkan hasilnya.
3. Di portal, waktu Last used pada kunci akan bergeser, dan panggilan tulis akan muncul di Key usage log.

Batas & catatan

• Masuk peramban (OAuth). Halaman referensi juga menjelaskan cara masuk melalui peramban untuk klien yang mendukung MCP OAuth. Pada instalasi NexCMP yang didukung dan teruji adalah kunci API (atau cmp login untuk CLI).
• Situs reseller tidak menampilkan bagian MCP; pelanggan mereka menggunakan domain reseller untuk API.
• Hak istimewa minimum. Buat kunci khusus untuk setiap asisten dengan cakupan baca terlebih dahulu; tambahkan cakupan tulis hanya bila diperlukan.
• Cabut kunci di API keys untuk memutus akses asisten secara instan.

Pemecahan Masalah

Gejala	Penyebab	Solusi
401 dengan WWW-Authenticate: Bearer	Tidak ada kunci, kunci salah, atau token sesi	Kirim Authorization: Bearer vk_....
403 tentang Origin	Halaman peramban pada asal yang berbeda	Gunakan klien desktop atau CLI; atau minta administrator Anda untuk mengizinkan asal tersebut (mcp_allowed_origins).
404 pada permintaan dengan Mcp-Session-Id	Sesi milik kunci lain atau kedaluwarsa	Jalankan initialize lagi.
405 pada GET /mcp	Harapan: server tidak memiliki alur peristiwa	Gunakan POST saja (klien melakukan ini secara otomatis).
Daftar alat terlalu pendek	Cakupan kunci atau modul	Tambahkan cakupan ke kunci; aktifkan modul.
Alat menjawab bahwa ia membutuhkan confirm: true	Alat berbayar, hapus, atau sensitif	Asisten harus menyetel confirm setelah Anda menyetujui.
429	Batas laju MCP atau kunci	Tunggu hingga Retry-After.
Klien tidak dapat terhubung dengan tajuk	Klien tanpa dukungan tajuk kustom	Gunakan jembatan mcp-remote.