---
title: MCP server
description: Sambungkan asisten AI (Claude, Cursor, VS Code, dan lainnya) ke API instalasi Anda melalui endpoint MCP bawaan di /mcp — autentikasi, konfigurasi klien, tool, dan aturan keamanan.
url: https://nexcmp.com/id/docs/developers/mcp/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# MCP server {#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 {#what-it-does}

**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.

::: tip 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](https://nexcmp.com/id/docs/configure-with-ai/mcp-admin/) (endpoint `/mcp/admin`, kunci admin `ak_`).
:::

## Persyaratan {#requirements}

| 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](https://nexcmp.com/id/docs/developers/api-keys/) (`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 {#prepare-the-infrastructure}

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) {#connect-customer-side}

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

   ```bash
   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):

   ```json
   {
     "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`:

   ```json
   {
     "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:

```bash
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 {#how-it-works}

| 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 {#safety-rules}

- **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 {#limits}

| 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](https://nexcmp.com/id/docs/developers/api/#rate-limits) |

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

## Verifikasi {#verify}

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 {#limits-notes}

- **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 {#troubleshooting}

| 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`. |