Menghubungkan klien AI (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

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.

Dua titik akhir MCP

/mcp adalah titik akhir pelanggan (kunci API pelanggan, vk_; lihat MCP server). /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

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 (ak_...) dengan cakupan yang Anda inginkan, atau masuk OAuth untuk konektor web (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

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:

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

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

Claude Code

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

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

{
  "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)

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.

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.

Codex CLI

Tambahkan ke ~/.codex/config.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:

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

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

Tambahkan ke ~/.gemini/settings.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

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

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

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)

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

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

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

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

Lainnya (HTTP biasa)

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

1. Tanpa klien, daftar alat:

   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

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

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

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

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

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

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

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

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

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

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 untuk format file.

Prompt

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)

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.

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

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

• 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) atau referensi secret:// (Konfigurasi sebagai kode).
• Klien tidak berbagi sesi: setiap koneksi dimulai dengan initialize.
• Cabut kunci di API & AI agents untuk memutus koneksi klien AI seketika.

Pemecahan Masalah

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.