---
title: Menghubungkan klien AI (MCP)
description: Hubungkan Claude Code, Codex CLI, Gemini CLI, Cursor, Claude Desktop, claude.ai, ChatGPT, atau SDK OpenAI ke endpoint MCP admin panel Anda dengan daftar alat lengkap.
url: https://nexcmp.com/id/docs/configure-with-ai/mcp-admin/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# Menghubungkan klien AI (MCP) {#connect-an-ai-client-mcp}

> **Lokasi di admin:** System › Settings › API & AI agents (`/agent/keys`), tab **Connect an AI** menampilkan URL titik akhir dan cuplikan siap salin untuk setiap klien, yang sudah diisi dengan kunci yang baru saja Anda buat.

## Fungsi {#what-it-does}

**Model Context Protocol (MCP)** memungkinkan klien AI memanggil alat. Panel Anda menjalankan server MCP admin di `https://cloud.example.com/mcp/admin`. Hubungkan alat AI Anda sendiri ke sana dan tanyakan dalam bahasa sehari-hari: "apa saja yang belum diatur?", "tambahkan kluster Proxmox saya", "buat paket dengan margin 40%". Klien memanggil alat admin di bawah ini; panel memeriksa cakupan, meminta konfirmasi Anda sebelum melakukan tindakan berisiko, dan mencatat setiap panggilan.

::: info Dua titik akhir MCP
`/mcp` adalah titik akhir **pelanggan** (kunci API pelanggan, `vk_`; lihat [MCP server](https://nexcmp.com/id/docs/developers/mcp/)). `/mcp/admin` adalah titik akhir **admin** yang dijelaskan di sini (kunci admin `ak_` atau OAuth). Keduanya tidak pernah dicampur: alat admin tidak terlihat di `/mcp`, dan `/mcp/admin` hanya menerima kunci admin.
:::

## Persyaratan {#requirements}

| Item | Persyaratan |
|---|---|
| Endpoint | `https://cloud.example.com/mcp/admin` pada domain panel Anda sendiri. Salin URL persis dari tab **Connect an AI**. Halaman yang sama mencantumkan URL lokal (`http://127.0.0.1:<port>/mcp/admin`) untuk alat yang berjalan di server itu sendiri. |
| Kredensial | [Kunci API admin](https://nexcmp.com/id/docs/configure-with-ai/admin-api-keys/) (`ak_...`) dengan cakupan yang Anda inginkan, **atau** masuk OAuth untuk konektor web ([OAuth connectors](https://nexcmp.com/id/docs/configure-with-ai/oauth-connectors/)). |
| Klien | Klien MCP apa pun yang mendukung transpor **Streamable HTTP** dan header `Authorization` kustom. Versi protokol 2025-11-25, 2025-06-18, dan 2025-03-26. |
| Jaringan | Jika Anda menempatkan proksi balik sendiri di depan panel, proksi tersebut harus meneruskan `/mcp/admin`. Konektor web (claude.ai, ChatGPT) terhubung dari server vendor, sehingga URL harus dapat dijangkau dari internet. |

## Siapkan infrastruktur {#prepare-the-infrastructure}

Tidak ada yang perlu diinstal di server. Jika Anda membatasi kunci berdasarkan IP, pastikan alamat tempat klien Anda terhubung berada dalam rentang tersebut. Uji keterjangkauan terlebih dahulu:

```bash
curl -i -X POST https://cloud.example.com/mcp/admin
```

Respons `401` dengan header `WWW-Authenticate: Bearer ... resource_metadata=...` berarti titik akhir aktif dan memerlukan kredensial.

## Hubungkan di NexCMP {#connect-in-nexcmp}

1. Membuat kunci: **System › Settings › API & AI agents › API keys › New key**. Untuk percobaan pertama, gunakan `admin:read` saja; tambahkan cakupan tulis saat Anda membutuhkannya. Lihat [Admin API keys](https://nexcmp.com/id/docs/configure-with-ai/admin-api-keys/).
2. Buka tab **Connect an AI**. Selama dialog "kunci dibuat" masih baru, setiap cuplikan di bawah ini sudah berisi kunci asli Anda. Jika tidak, cuplikan akan menampilkan placeholder `ak_YOUR_KEY`.
3. Salin cuplikan untuk klien Anda, lalu jalankan atau tempel seperti yang dijelaskan berikutnya.

![Tab Connect an AI dengan URL MCP dan satu kartu berisi tombol salin per klien](https://nexcmp.com/id/docs/images/configure-with-ai/mcp-admin-01-connect.webp)

### Claude Code {#claude-code}

```bash
claude mcp add --transport http nexcmp https://cloud.example.com/mcp/admin \
  --header "Authorization: Bearer ak_XXXX"
```

Kemudian jalankan `claude` dan tanyakan "list the tools from nexcmp" atau "what is left to set up?".

Diverifikasi pada 30/10/2026 dengan Claude Code 2.1: `claude mcp add --transport http …` menulis server (tambahkan `-s project` untuk menyimpannya di `.mcp.json` proyek — Claude Code akan meminta Anda menyetujui server proyek saat pertama kali). Untuk skrip, `claude -p "…" --mcp-config .mcp.json --strict-mcp-config --allowedTools "mcp__nexcmp__*"` berjalan tanpa konfirmasi persetujuan dan membatasi Claude hanya menggunakan tool milik panel.

### Claude Desktop {#claude-desktop}

Memerlukan Node.js 18 atau yang lebih baru. Tambahkan ini ke `claude_desktop_config.json` (menggunakan bridge `mcp-remote`) dan mulai ulang Claude Desktop:

```json
{
  "mcpServers": {
    "nexcmp": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://cloud.example.com/mcp/admin", "--header", "Authorization:Bearer ak_XXXX"]
    }
  }
}
```

Jika sistem Anda merusak spasi pada argumen header, simpan seluruh nilainya ke dalam environment variable sebagai gantinya, persis seperti pada endpoint pelanggan: `"args": [..., "--header", "Authorization:${NEXCMP_AUTH_HEADER}"]` dengan `"env": { "NEXCMP_AUTH_HEADER": "Bearer ak_XXXX" }`.

### claude.ai (konektor kustom) {#claude-ai-custom-connector}

Kunci tidak diperlukan: masuk menggunakan OAuth. Di claude.ai, buka pengaturan konektor, tambahkan custom connector, tempel `https://cloud.example.com/mcp/admin`, lalu masuk dengan akun admin NexCMP Anda dan pilih izin pada layar persetujuan. Detail: [Konektor OAuth](https://nexcmp.com/id/docs/configure-with-ai/oauth-connectors/).

### ChatGPT (developer mode) {#chatgpt-developer-mode}

Kunci tidak diperlukan. Di ChatGPT, aktifkan developer mode, tambahkan konektor MCP dengan URL `https://cloud.example.com/mcp/admin`, pilih OAuth, lalu masuk dengan akun admin NexCMP Anda. Detail: [Konektor OAuth](https://nexcmp.com/id/docs/configure-with-ai/oauth-connectors/).

### Codex CLI {#codex-cli}

Tambahkan ke `~/.codex/config.toml`:

```toml
[mcp_servers.nexcmp]
url = "https://cloud.example.com/mcp/admin"
bearer_token_env_var = "NEXCMP_KEY"
```

Kemudian ekspor kunci di shell yang memulai Codex:

```bash
export NEXCMP_KEY=ak_XXXX
codex
codex mcp list   # shows nexcmp with "Bearer token" auth
```

::: tip Non-interaktif `codex exec`
Di `codex exec` (skrip, CI) Codex tidak bertanya sebelum memanggil alat, dan melewati alat yang mengubah data. Tambahkan `default_tools_approval_mode = "approve"` di bawah `[mcp_servers.nexcmp]` untuk mengizinkannya memanggil alat tersebut; panel tetap mengembalikan pratinjau dan meminta konfirmasi untuk tindakan uang, keamanan, dan penghapusan. Diuji dengan Codex CLI 0.166 pada 30/10/2026.
:::

### Gemini CLI {#gemini-cli}

Tambahkan ke `~/.gemini/settings.json`:

```json
{
  "mcpServers": {
    "nexcmp": {
      "httpUrl": "https://cloud.example.com/mcp/admin",
      "headers": { "Authorization": "Bearer ak_XXXX" }
    }
  }
}
```

Gemini CLI menonaktifkan server MCP di folder yang tidak dipercayainya. Mulai di folder yang Anda percayai (atau percayai folder saat diminta), lalu periksa dengan `gemini mcp list` — ini menampilkan `nexcmp … Connected`. Anda dapat menyimpan kunci di luar file dengan `"Authorization": "Bearer $NEXCMP_KEY"`. Diuji dengan Gemini CLI 0.66 pada 30/10/2026.

### Cursor {#cursor}

Tambahkan ke `~/.cursor/mcp.json` (atau `.cursor/mcp.json` di dalam proyek):

```json
{
  "mcpServers": {
    "nexcmp": {
      "url": "https://cloud.example.com/mcp/admin",
      "headers": { "Authorization": "Bearer ak_XXXX" }
    }
  }
}
```

::: tip Jauhkan kunci dari file konfigurasi
Jika klien mendukungnya, baca kunci dari variabel lingkungan alih-alih menulisnya di dalam file: Codex melakukan ini secara default (`bearer_token_env_var`), dan Cursor menerima `"Bearer ${env:NEXCMP_KEY}"`. Jangan pernah melakukan commit pada file yang berisi kunci.
:::

### OpenAI Agents SDK (Python) {#openai-agents-sdk-python}

```python
from agents.mcp import MCPServerStreamableHttp

nexcmp = MCPServerStreamableHttp(
    params={"url": "https://cloud.example.com/mcp/admin",
            "headers": {"Authorization": "Bearer ak_XXXX"}},
    name="nexcmp",
)
```

Eksekusi lengkap (diuji dengan `openai-agents` 0.24 pada 30/10/2026 — alat baca, lalu perubahan saldo yang mengembalikan pratinjau konfirmasi dan diterapkan pada pemanggilan kedua dengan `confirm_token`):

```python
import asyncio
from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp

async def main():
    async with MCPServerStreamableHttp(params={"url": "https://cloud.example.com/mcp/admin",
            "headers": {"Authorization": "Bearer ak_XXXX"}}, name="nexcmp") as nexcmp:
        agent = Agent(name="admin", model="gpt-5", mcp_servers=[nexcmp],
                      instructions="You operate a hosting panel through the nexcmp tools. Ask me before confirming money actions.")
        result = await Runner.run(agent, "Run system_health and summarise it in one line.")
        print(result.final_output)

asyncio.run(main())
```

### OpenAI Responses API {#openai-responses-api}

Teruskan server sebagai alat bertipe `mcp`. Pertahankan `require_approval` pada `always` agar program Anda bertanya sebelum setiap pemanggilan:

```json
{
  "type": "mcp",
  "server_label": "nexcmp",
  "server_url": "https://cloud.example.com/mcp/admin",
  "headers": { "Authorization": "Bearer ak_XXXX" },
  "require_approval": "always"
}
```

### Lainnya (HTTP biasa) {#anything-else-plain-http}

Klien tanpa MCP dapat memanggil alat yang sama melalui HTTP. `GET /v1/admin/agent/tools` mencantumkannya, `POST /v1/admin/agent/tools/<name>` menjalankan satu alat dengan isi JSON berisi argumen, dan `GET /v1/admin/openapi.json` mengembalikan deskripsi OpenAPI 3.1 (setiap alat adalah satu operasi). Semuanya memerlukan `Authorization: Bearer ak_...`.

## Verifikasi {#verify}

1. Tanpa klien, daftar alat:

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

   Hasilnya adalah respons JSON-RPC dengan alat yang diizinkan oleh cakupan Anda.
2. Di klien Anda, tanyakan "run system_health". Ini mengembalikan peringatan, kesehatan infrastruktur yang terhubung, pembayaran, email, AI, dan status lisensi.
3. Buka **API & AI agents › Activity**: pemanggilan tercantum beserta nama klien dan `mcp`.
4. Pada server, `sudo nexcmp status` mencetak baris "MCP admin" yang menyatakan `ready` saat titik akhir merespons (HTTP 401 tanpa kunci adalah status sehat).

## Peralatan {#tools}

Server menyediakan 58 alat. Klien hanya melihat alat yang diizinkan oleh cakupan kuncinya: alat baca memerlukan `admin:read`, alat tulis memerlukan cakupannya sendiri. Alat tulis juga menerima argumen opsional `confirm_token` (lihat [Confirmation](#confirmation-confirm-token)). Argumen diperiksa terhadap skema setiap alat: argumen yang tidak dikenal atau salah ketik ditolak dengan pesan yang menyebutkan namanya.

Harga dalam USD: harga paket dalam dolar per jam (`hourly_usd`), saldo dalam sen. Rahasia dapat diatur tetapi tidak pernah dikembalikan.

### Ikhtisar dan log {#overview-and-logs}

| Alat | Fungsi | Cakupan | Mengubah data | Meminta Anda |
|---|---|---|---|---|
| `system_health` | Peringatan yang memerlukan perhatian, kesehatan infrastruktur, pembayaran, email, AI, status lisensi, dan pembaruan. | `admin:read` | Tidak | Tidak |
| `setup_checklist` | Apa yang dikonfigurasi dan yang tersisa: lisensi, infrastruktur, zona, templat OS, paket, pembayaran, email, branding, legal, pesanan uji. | `admin:read` | Tidak | Tidak |
| `license_status` | Status lisensi dan apakah versi NexCMP yang lebih baru tersedia. | `admin:read` | Tidak | Tidak |
| `audit_search` | Cari log audit admin dan log kunci API. | `admin:read` | Tidak | Tidak |

### Pengaturan, branding, legal, modul {#settings-branding-legal-modules}

| Alat | Fungsi | Cakupan | Mengubah data | Meminta Anda |
|---|---|---|---|---|
| `settings_get` | Membaca pengaturan umum (filter `keys`; akhiran `*` mencocokkan awalan). | `admin:read` | Tidak | Tidak |
| `settings_update` | Mengubah pengaturan umum dari objek datar `values`. Hanya kunci yang mencantumkan `settings_get` yang diterima. | `settings:write` | Ya | Saat kunci menyentuh pembayaran, keamanan masuk, sakelar seluruh situs, atau harga |
| `branding_get` | Nama merek, warna, mata uang tampilan, nama penjual, logo, dan URL favicon. | `admin:read` | Tidak | Tidak |
| `branding_update` | Atur nama merek (hingga 60 karakter), warna (`#rrggbb`), mata uang tampilan (`usd` atau `vnd`), dan nama penjual. | `settings:write` | Ya | Tidak |
| `branding_logo_set` | Unggah logo terang atau gelap atau favicon dari URL https atau base64 (PNG, JPEG, WEBP, ICO, atau SVG, hingga 512 KB). | `settings:write` | Ya | Tidak |
| `legal_get` | Ketentuan layanan dan kebijakan privasi (Bahasa Inggris dan Vietnam) serta standar netral. | `admin:read` | Tidak | Tidak |
| `legal_update` | Atur teks ketentuan dan privasi (markdown sederhana, tanpa HTML, hingga 50 KB masing-masing). Kosongkan untuk mengembalikan ke default. | `settings:write` | Ya | Tidak |
| `modules_get` | Modul opsional mana yang aktif dan mana yang dapat dialihkan. | `admin:read` | Tidak | Tidak |
| `module_set` | Nyalakan atau matikan modul opsional (`key` harus berupa salah satu dari `settable`). | `settings:write` | Ya | Tidak |

### Email dan peringatan {#email-and-alerts}

| Alat | Fungsi | Cakupan | Mengubah data | Meminta Anda |
|---|---|---|---|---|
| `smtp_get` | Pengaturan email keluar (kata sandi disamarkan) dan status antrean. | `admin:read` | Tidak | Tidak |
| `smtp_configure` | Atur server SMTP. Mengubah host, port, atau keamanan memerlukan kata sandi kembali. | `settings:write` (+ `secrets:write` untuk kata sandi) | Ya | Tidak |
| `smtp_test` | Kirim email uji coba nyata dengan pengaturan yang disimpan. | `settings:write` | Mengirim email | Tidak |
| `telegram_get` | Saluran pemberitahuan admin (id chat; token bot tidak pernah ditampilkan). | `admin:read` | Tidak | Tidak |
| `telegram_configure` | Tambah atau perbarui saluran peringatan Telegram (token bot dan id chat) serta aktifkan atau nonaktifkan peringatan admin. | `settings:write` (+ `secrets:write` untuk token) | Ya | Tidak |
| `telegram_test` | Kirim pesan uji coba ke saluran Telegram. | `settings:write` | Mengirim pesan | Tidak |

### Pembayaran dan mata uang {#payments-and-currency}

| Alat | Fungsi | Cakupan | Mengubah data | Meminta Anda |
|---|---|---|---|---|
| `payments_get` | Status Stripe, PayPal, kripto (USDT), dan transfer bank, ditambah saluran yang diaktifkan dan biaya. | `admin:read` | Tidak | Tidak |
| `payment_configure` | Atur kredensial satu gateway (`stripe`, `paypal`, `crypto`, atau `bank`). | `billing:write` (+ `secrets:write`) | Ya | Selalu |
| `payment_test` | Periksa kredensial gateway yang disimpan dengan penyedia. | `billing:write` | Tidak | Tidak |
| `currency_get` | Mata uang tampilan dan kurs USD ke VND (otomatis atau manual). | `admin:read` | Tidak | Tidak |
| `currency_set` | Atur mata uang tampilan dan/atau kurs manual (0 berarti otomatis, jika tidak 15000 hingga 50000). | `billing:write` | Ya | Saat Anda mengubah kurs manual |

### Infrastruktur dan zona {#infrastructure-and-zones}

| Alat | Fungsi | Cakupan | Mengubah data | Meminta Anda |
|---|---|---|---|---|
| `cloudstack_get` | Endpoint CloudStack serta id zona dan jaringan yang tersimpan (kunci disamarkan). | `admin:read` | Tidak | Tidak |
| `cloudstack_test` | Uji endpoint dengan kunci API dan rahasia tanpa menyimpan; mencantumkan zona. | `infra:write` (+ `secrets:write`, karena Anda meneruskan kunci) | Tidak | Tidak |
| `cloudstack_connect` | Simpan koneksi CloudStack. | `infra:write` (+ `secrets:write`) | Ya | Selalu |
| `proxmox_list` | Klaster Proxmox VE ditambahkan sebagai sumber, beserta kesehatannya. | `admin:read` | Tidak | Tidak |
| `proxmox_add` | Tambahkan klaster Proxmox VE dengan token API (`user@realm!tokenid`) dan kuncinya. | `infra:write` (+ `secrets:write`) | Ya | Tidak |
| `proxmox_test` | Sambungkan ke klaster berdasarkan id; keberhasilan pertama akan menyematkan sertifikat TLS-nya. | `infra:write` | Ya | Tidak |
| `proxmox_attach_zone` | Jual klaster Proxmox di zona yang ada, secara opsional dengan node sebagai region. | `infra:write` | Ya | Tidak |
| `zones_list` | Zona (lokasi) yang dapat dipilih pelanggan. | `admin:read` | Tidak | Tidak |
| `zone_create` | Buat zona. | `infra:write` | Ya | Tidak |

### Katalog dan paket {#catalog-and-plans}

| Alat | Fungsi | Cakupan | Mengubah data | Meminta Anda |
|---|---|---|---|---|
| `templates_list` | Templat OS yang dapat diinstal pelanggan. | `admin:read` | Tidak | Tidak |
| `templates_sync` | Impor templat OS dari CloudStack. | `catalog:write` | Ya | Tidak |
| `template_update` | Aktifkan atau sembunyikan templat, ganti namanya, atur pengguna login atau urutannya. | `catalog:write` | Ya | Tidak |
| `offerings_list` | Penawaran layanan CloudStack (CPU, memori, disk root) untuk membangun paket. | `admin:read` | Tidak | Tidak |
| `plans_list` | Paket dengan harga per jam dan per bulan, ukuran, zona, dan berapa banyak server yang menggunakannya. | `admin:read` | Tidak | Tidak |
| `plan_create` | Buat paket. Harga sebagai `hourly_usd`. Paket CloudStack memerlukan `cs_offering_id`; paket Proxmox memerlukan `backend_id`. | `catalog:write` | Ya | Tidak |
| `plan_update` | Ganti nama, tampilkan atau sembunyikan, aktifkan atau nonaktifkan, atau ubah harga paket. Perubahan ukuran pada paket yang sedang digunakan memerlukan salinan. | `catalog:write` | Ya | Saat harga berubah |
| `plans_from_offerings` | Buat tabel paket pemula dari penawaran (atau ukuran Proxmox) menggunakan biaya Anda dan persentase margin. Mengembalikan pratinjau; panggil lagi dengan `apply=true` untuk membuat paket. | `catalog:write` | Dengan `apply=true` | Selalu saat menerapkan |
| `quota_defaults_get` | Batas default pelanggan. | `admin:read` | Tidak | Tidak |
| `quota_defaults_set` | Ubah pengaturan `quota_*`. | `catalog:write` | Ya | Tidak |
| `coupons_list` | Batch kode diskon dan hadiah. | `admin:read` | Tidak | Tidak |
| `coupon_create` | Buat batch kode: tipe `money` (nilai nominal dalam sen USD) atau `percent` (1 hingga 100, dengan diskon maksimum). | `catalog:write` | Ya | Selalu |

### Pelanggan dan reseller {#customers-and-resellers}

| Alat | Fungsi | Cakupan | Mengubah data | Meminta Anda |
|---|---|---|---|---|
| `customers_search` | Cari pelanggan berdasarkan email, nama, atau IP. | `admin:read` | Tidak | Tidak |
| `customer_get` | Akun, saldo, server, dan penagihan terkini dari satu pelanggan. | `admin:read` | Tidak | Tidak |
| `customer_adjust_balance` | Tambahkan (positif) atau kurangi (negatif) kredit dalam sen USD. Alasan wajib diisi. | `billing:write` | Ya | Selalu |
| `customer_block` | Blokir pelanggan, opsional menghentikan server mereka. Alasan wajib diisi. | `customers:write` | Ya | Selalu |
| `customer_unblock` | Buka blokir pelanggan. | `customers:write` | Ya | Tidak |
| `resellers_list` | Reseller dengan wallet dan status. | `admin:read` | Tidak | Tidak |
| `reseller_get` | Situs, wallet, pengguna, dan gateway dari satu reseller. | `admin:read` | Tidak | Tidak |

### AI provider {#ai-provider}

| Alat | Fungsi | Cakupan | Mengubah data | Meminta Anda |
|---|---|---|---|---|
| `ai_provider_get` | Penyedia kompatibel-OpenAI yang digunakan oleh AI Chat dan AI Agent pelanggan (kunci disamarkan). | `admin:read` | Tidak | Tidak |
| `ai_provider_set` | Atur penyedia: URL dasar, model, API key, model fallback, reasoning effort, diaktifkan. | `ai:write` (+ `secrets:write` untuk kuncinya) | Ya | Tidak |
| `ai_provider_test` | Ajukan satu pertanyaan ke penyedia yang tersimpan untuk memeriksa apakah berfungsi. | `ai:write` | Tidak | Tidak |

### File konfigurasi {#configuration-files}

| Alat | Fungsi | Cakupan | Mengubah data | Meminta Anda |
|---|---|---|---|---|
| `config_export` | Ekspor konfigurasi sebagai YAML (rahasia menjadi referensi `secret://`). | `admin:read` | Tidak | Tidak |
| `config_plan` | Bandingkan konfigurasi YAML dengan panel aktif dan buat daftar perubahan yang akan terjadi. | `admin:read` | Tidak | Tidak |
| `config_apply` | Terapkan konfigurasi YAML bagian demi bagian. Setiap perubahan mengikuti aturan scope dan konfirmasi standar. | `admin:read` + scope dari setiap perubahan | Ya | Per perubahan |

Lihat [Konfigurasi sebagai kode](https://nexcmp.com/id/docs/configure-with-ai/config-as-code/) untuk format file.

## Prompt {#prompts}

Server juga menawarkan tiga prompt siap pakai yang dapat ditampilkan klien sebagai pintasan:

| Prompt | Argumen | Tindakan yang diminta kepada AI |
|---|---|---|
| `initial-setup` | tidak ada | Panggil `setup_checklist`, jelaskan setiap langkah yang terbuka dalam satu kalimat, minta informasi yang dibutuhkan kepada Anda, jalankan langkah tersebut dengan alat yang sesuai, pratinjau perubahan biaya atau keamanan, dan akhiri dengan `system_health`. |
| `add-proxmox` | `endpoint` (opsional, `https://host:8006`) | Minta token API, lalu `proxmox_add`, `proxmox_test`, alat zona dan `proxmox_attach_zone`; lalu usulkan paket dengan `plans_from_offerings` dan tunggu persetujuan Anda. |
| `launch-pricing` | `margin_pct` (opsional, default 40) | Minta biaya bulanan Anda per vCPU, per GB RAM, dan per GB disk, tampilkan tabel pratinjau dengan biaya, harga per bulan, dan harga per jam, lalu buat paket setelah Anda menyetujuinya. |

## Konfirmasi (`confirm_token`) {#confirmation-confirm-token}

Tindakan yang memindahkan uang, menghapus data, mengubah kredensial pembayaran, atau keamanan masuk terdiri dari dua langkah:

1. Panggilan pertama tidak mengubah apa pun. Hasil alat dimulai dengan "CONFIRMATION REQUIRED" dan menyertakan **pratinjau** (apa yang akan dipanggil, mengapa tindakan tersebut sensitif, nilai baru, dan nilai saat ini) serta `confirm_token`.
2. Klien harus menunjukkan pratinjau kepada Anda. Hanya setelah Anda menyetujuinya, klien akan memanggil alat yang sama lagi dengan argumen yang sama ditambah `confirm_token`.
3. Token ini berfungsi sekali, hanya untuk permintaan persis tersebut, dan kedaluwarsa setelah 5 menit.

Instruksi server memberi tahu AI untuk memperlakukan hasil alat sebagai data, bukan sebagai instruksi, dan tidak boleh mengulang panggilan dengan token yang belum Anda setujui. Anda adalah pengaman: baca pratinjau.

::: warning Jangan setujui otomatis
Beberapa klien dapat menyetujui setiap panggilan alat secara otomatis. Untuk alat tulis, tetap aktifkan persetujuan per panggilan, atau gunakan kunci baca-saja, sehingga rencana yang salah dari AI tidak dapat menjangkau panel Anda tanpa sepengetahuan Anda.
:::

## Cara kerja {#how-it-works}

| Item | Detail |
|---|---|
| Transportasi | `POST /mcp/admin` dengan pesan JSON-RPC 2.0; jawabannya adalah `application/json`. Hingga 20 pesan dalam satu batch. `GET /mcp/admin` menjawab 405 (tidak ada aliran server); `DELETE /mcp/admin` mengakhiri sesi. |
| Autentikasi | `Authorization: Bearer ak_...` (kunci manual atau token akses OAuth). Kredensial yang hilang atau salah memberikan 401 dengan `WWW-Authenticate: Bearer ... resource_metadata=...`, yang memungkinkan klien OAuth memulai proses masuk sendiri. |
| Sesi | `Mcp-Session-Id` dikeluarkan oleh `initialize`, terikat pada kunci tersebut dan berlaku selama 24 jam. |
| Kapabilitas | Alat dan prompt. Tanpa sumber daya. |
| Ukuran | Badai permintaan hingga 1 MB; hasil alat dipotong setelah sekitar 100 KB. |
| Asal | Permintaan yang membawa header `Origin` dari situs lain ditolak (`origin_not_allowed`). Klien baris perintah dan desktop tidak mengirimkannya. |
| Gerbang yang sama seperti REST | Setiap panggilan alat dikirim ulang melalui saluran permintaan panel Anda dengan kunci Anda, sehingga cakupan, rentang IP, batasan laju, konfirmasi, dan log aktivitas berlaku persis seperti pada panggilan API langsung. |

## Batas & catatan {#limits-notes}

- Alat yang tidak dapat Anda lihat adalah cakupan yang tidak Anda berikan. Tambahkan cakupan ke kunci baru.
- Menetapkan kata sandi atau kunci API melalui klien AI berarti rahasia tersebut melewati AI tersebut. Jika Anda mau, matikan `secrets:write` dan masukkan sendiri rahasia di panel admin, atau gunakan bidang **Secret** AI Chat ([AI Chat di admin](https://nexcmp.com/id/docs/configure-with-ai/ai-chat-in-admin/#secrets)) atau referensi `secret://` ([Konfigurasi sebagai kode](https://nexcmp.com/id/docs/configure-with-ai/config-as-code/#secrets)).
- Klien tidak berbagi sesi: setiap koneksi dimulai dengan `initialize`.
- Cabut kunci di **API & AI agents** untuk memutus koneksi klien AI seketika.

## Pemecahan Masalah {#troubleshooting}

| Gejala | Penyebab | Solusi |
|---|---|---|
| 401 `invalid_key` | Kunci salah, terpotong, atau bukan kunci admin (misalnya kunci `vk_`) | Gunakan kunci `ak_`. |
| 401 `key_expired` atau `key_revoked` | Kunci habis masa berlakunya atau telah dicabut | Buat kunci baru. |
| 403 `ip_not_allowed` | IP Anda berada di luar rentang IP kunci | Sambungkan dari IP yang diizinkan. |
| 403 `origin_not_allowed` | Halaman browser di asal lain memanggil endpoint | Gunakan klien desktop atau CLI. |
| 404 pada permintaan dengan `Mcp-Session-Id` | Sesi milik kunci lain atau sudah kedaluwarsa | Kirim `initialize` lagi. |
| 400 `MCP-Protocol-Version` tidak didukung | Klien menggunakan versi yang tidak dikenali oleh server | Perbarui klien; yang didukung: 2025-11-25, 2025-06-18, 2025-03-26. |
| Daftar alat terlalu pendek | Cakupan kunci | Buat kunci dengan lebih banyak cakupan. |
| `insufficient_scope` pada panggilan | Suatu alat memerlukan cakupan kedua, misalnya `secrets:write` | Tambahkan cakupan ke kunci baru. |
| 429 `rate_limited` | Panggilan per menit melebihi yang diizinkan oleh kunci | Tunggu selama `Retry-After` atau tingkatkan batasan pada kunci baru. |
| claude.ai atau ChatGPT tidak dapat terhubung | URL tidak dapat dijangkau dari internet, atau proksi memblokir `/mcp/admin` atau `/oauth-admin/` | Periksa DNS, TLS, dan reverse proxy. |

Untuk semua kode galat, lihat [Admin API keys](https://nexcmp.com/id/docs/configure-with-ai/admin-api-keys/#errors).