Integrasi Model Context Protocol (MCP)

Panduan ini menjelaskan cara menghubungkan agen AI ke server Vapor MCP (Model Context Protocol) untuk mengelola mesin virtual, penyimpanan, dan jaringan melalui bahasa alami (natural language).

Ikhtisar

Vapor mengekspos server MCP jarak jauh di /api/v1/mcp menggunakan transport Streamable HTTP yang didefinisikan dalam spesifikasi MCP (2025-03-26). Setiap klien AI yang kompatibel dengan MCP dapat terhubung ke endpoint ini untuk mendeteksi dan menggunakan 21 alat manajemen infrastruktur.

Informasi Utama

Properti	Nilai
Transport	Streamable HTTP (POST/GET/DELETE)
Endpoint	`https://<host>:7770/api/v1/mcp`
Versi Protokol	`2025-03-26`
Autentikasi	Bearer token (JWT atau API token)
TLS	Aktif secara default (self-signed certs)
Manajemen Sesi	Di dalam memori, TTL 30 menit

1. Autentikasi

Endpoint MCP berada di balik middleware autentikasi standar Vapor. Anda harus menyertakan header Authorization: Bearer <token> yang valid di setiap permintaan.

Opsi A: API Token (Disarankan untuk Agen AI)

API token berumur panjang, persisten, dan ideal untuk autentikasi antar-mesin (machine-to-machine). Token ini tetap aktif meskipun server dihidupkan ulang dan tidak kedaluwarsa kecuali Anda menetapkan tanggal kedaluwarsa secara eksplisit.

Langkah 1 — Login untuk mendapatkan JWT sesi:

bash

curl -ksS -X POST "https://<host>:7770/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username":"<user>","password":"<pass>","auth_type":"password"}'

Respons:

json

{
  "status": "success",
  "data": {
    "token": "eyJhbGci...",
    "expires_at": 1781400787,
    "user": {"username": "awanio", "uid": 1000}
  }
}

Langkah 2 — Buat API token persisten:

bash

curl -ksS -X POST "https://<host>:7770/api/v1/auth/tokens" \
  -H "Authorization: Bearer <jwt-from-step-1>" \
  -H "Content-Type: application/json" \
  -d '{"name": "mcp-agent"}'

Respons:

json

{
  "status": "success",
  "data": {
    "token": "a1b2c3d4e5f6...64-char-hex-string...",
    "token_info": {
      "id": "uuid",
      "name": "mcp-agent",
      "username": "awanio",
      "created_at": "2026-06-13T01:00:00Z"
    }
  }
}

IMPORTANT

Simpan nilai token segera — nilai ini hanya ditampilkan sekali. Ini adalah nilai yang akan Anda gunakan dalam header Authorization: Bearer <token>.

Untuk menggunakan API token dengan MCP, kirimkan sebagai header Basic Auth (middleware kami mengenalinya):

Authorization: Basic <base64(token:)>

Atau masukkan sebagai Bearer token secara langsung — middleware akan mencoba validasi API token terlebih dahulu, kemudian beralih ke pembacaan JWT.

Opsi B: JWT Token (Berumur Pendek)

JWT kedaluwarsa setelah 24 jam. Gunakan opsi ini untuk pengujian cepat tetapi tidak untuk konfigurasi agen yang persisten.

bash

curl -ksS -X POST "https://<host>:7770/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username":"<user>","password":"<pass>","auth_type":"password"}'

Gunakan data.token yang dikembalikan dalam semua permintaan MCP berikutnya.

2. Menangani Sertifikat TLS Self-Signed

Vapor menggunakan sertifikat TLS self-signed secara default. Sebagian besar klien MCP akan menolak koneksi dengan kesalahan verifikasi sertifikat kecuali Anda mengonfigurasinya secara eksplisit.

Memahami Masalah

Saat pertama kali menjalankan Vapor, sistem secara otomatis menghasilkan sertifikat self-signed di /var/lib/vapor/certs/. Karena sertifikat ini tidak ditandatangani oleh Certificate Authority (CA) tepercaya, klien HTTPS yang melakukan verifikasi sertifikat akan menolak koneksi dengan kesalahan seperti:

CERTIFICATE_VERIFY_FAILED (Python)
DEPTH_ZERO_SELF_SIGNED_CERT (Node.js)
SSL certificate problem: self-signed certificate (curl)

Mendapatkan Sertifikat CA

Sebelum mengonfigurasi kepercayaan, Anda perlu mendapatkan sertifikat server Vapor. Ada tiga cara untuk melakukan ini:

Opsi 1 — Unduh via API (disarankan untuk otomatisasi):

bash

# Gunakan -k untuk unduhan awal karena sertifikat belum tepercaya
curl -ksS "https://<vapor-host>:7770/api/v1/system/tls/server-cert" \
  -H "Authorization: Bearer <token>" \
  -o vapor-ca.crt

Opsi 2 — Unduh dari Web UI: Buka antarmuka web Vapor → Settings → TLS Configuration → klik "Download CA Certificate". Opsi ini hanya mengunduh sertifikat publik server — tanpa kunci privat (private keys).

Opsi 3 — Salin langsung dari server:

bash

scp root@<vapor-host>:/var/lib/vapor/certs/server.crt ./vapor-ca.crt

Metode 1: Mempercayai CA Self-Signed (Disarankan untuk Produksi)

Tambahkan sertifikat self-signed Vapor ke penyimpanan sertifikat tepercaya sistem. Ini adalah metode paling aman karena tetap menjaga verifikasi TLS.

Pada mesin yang menjalankan klien MCP (menggunakan sertifikat vapor-ca.crt yang diperoleh di atas):

bash

# Pada Debian/Ubuntu:
sudo cp vapor-ca.crt /usr/local/share/ca-certificates/vapor-ca.crt
sudo update-ca-certificates

# Pada RHEL/CentOS/Fedora:
sudo cp vapor-ca.crt /etc/pki/ca-trust/source/anchors/vapor-ca.crt
sudo update-ca-trust

# Pada macOS:
sudo security add-trusted-cert -d -r trustRoot \
  -k /Library/Keychains/System.keychain vapor-ca.crt

Setelah mempercayai sertifikat, semua klien HTTPS pada mesin tersebut akan menerima koneksi TLS Vapor tanpa memerlukan opsi khusus.

Metode 2: Menentukan CA Bundle saat Runtime

Arahkan klien MCP atau pustaka HTTP Anda ke file sertifikat Vapor secara langsung, tanpa memodifikasi penyimpanan sertifikat sistem.

Untuk curl:

bash

curl --cacert /path/to/vapor-server.crt -X POST "https://<host>:7770/api/v1/mcp" ...

Untuk Node.js (digunakan oleh sebagian besar SDK klien MCP):

bash

export NODE_EXTRA_CA_CERTS=/path/to/vapor-server.crt

Untuk Python:

python

import httpx
client = httpx.Client(verify="/path/to/vapor-server.crt")

Metode 3: Menonaktifkan Verifikasi TLS (Hanya untuk Pengembangan)

WARNING

Metode ini menonaktifkan semua verifikasi sertifikat dan rentan terhadap serangan man-in-the-middle. Hanya gunakan metode ini di lingkungan pengembangan yang terisolasi.

Untuk curl:

bash

curl -k ...

Untuk Node.js:

bash

export NODE_TLS_REJECT_UNAUTHORIZED=0

Untuk Python:

python

import httpx
client = httpx.Client(verify=False)

Metode 4: Menggunakan Sertifikat CA yang Valid (Disarankan untuk Produksi Multi-Pengguna)

Ganti sertifikat self-signed dengan sertifikat yang diterbitkan oleh CA tepercaya (misalnya, Let's Encrypt, PKI internal):

yaml

# vapor.conf
tls_enabled: true
tls_cert_file: "/etc/ssl/vapor/fullchain.pem"
tls_key_file: "/etc/ssl/vapor/privkey.pem"

Kemudian hidupkan ulang Vapor:

bash

sudo systemctl restart vapor

Langkah ini menghilangkan semua masalah verifikasi sertifikat untuk setiap klien.

3. Alur Protokol MCP

Transport Streamable HTTP MCP menggunakan satu endpoint (/api/v1/mcp) dengan tiga metode HTTP:

POST   /api/v1/mcp   ← Pesan JSON-RPC (initialize, tools/list, tools/call, ping)
GET    /api/v1/mcp   ← SSE (Server-Sent Events) stream untuk notifikasi server
DELETE /api/v1/mcp   ← Mengakhiri sesi

Siklus Hidup Koneksi

┌─────────┐                          ┌──────────┐
│  Klien  │                          │  Vapor   │
└────┬─────┘                          └────┬─────┘
     │                                     │
     │  POST initialize                    │
     │────────────────────────────────────►│
     │◄────────────────────────────────────│
     │  200 + header Mcp-Session-Id        │
     │                                     │
     │  POST notifications/initialized     │
     │  (dengan header Mcp-Session-Id)     │
     │────────────────────────────────────►│
     │◄────────────────────────────────────│
     │  202 Accepted                       │
     │                                     │
     │  POST tools/list                    │
     │  (dengan header Mcp-Session-Id)     │
     │────────────────────────────────────►│
     │◄────────────────────────────────────│
     │  200 + definisi alat                │
     │                                     │
     │  POST tools/call                    │
     │  (dengan header Mcp-Session-Id)     │
     │────────────────────────────────────►│
     │◄────────────────────────────────────│
     │  200 + hasil alat                   │
     │                                     │
     │  DELETE (penghentian sesi)          │
     │  (dengan header Mcp-Session-Id)     │
     │────────────────────────────────────►│
     │◄────────────────────────────────────│
     │  204 No Content                     │
     └                                    └

Tahapan dengan curl

1. Inisialisasi:

bash

curl -ksS -D /tmp/headers.txt -X POST "https://localhost:7770/api/v1/mcp" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": {"name": "my-agent", "version": "1.0"}
    }
  }'

Dapatkan ID sesi dari header respons:

bash

SESSION_ID=$(grep -i 'Mcp-Session-Id' /tmp/headers.txt | awk '{print $2}' | tr -d '\r')

2. Konfirmasi inisialisasi:

bash

curl -ksS -X POST "https://localhost:7770/api/v1/mcp" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: ${SESSION_ID}" \
  -d '{"jsonrpc": "2.0", "method": "notifications/initialized"}'

3. Tampilkan daftar alat:

bash

curl -ksS -X POST "https://localhost:7770/api/v1/mcp" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: ${SESSION_ID}" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'

4. Panggil alat (call tool):

bash

curl -ksS -X POST "https://localhost:7770/api/v1/mcp" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: ${SESSION_ID}" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "vm_list",
      "arguments": {}
    }
  }'

5. Akhiri sesi:

bash

curl -ksS -X DELETE "https://localhost:7770/api/v1/mcp" \
  -H "Authorization: Bearer <token>" \
  -H "Mcp-Session-Id: ${SESSION_ID}"

4. Alat yang Tersedia

Server Vapor MCP mengekspos 21 alat yang dikelompokkan berdasarkan domain:

Manajemen Mesin Virtual

Alat	Deskripsi
`vm_list`	Menampilkan daftar semua VM dengan status, UUID, vCPU, memori, dan informasi disk
`vm_get`	Dapatkan informasi detail VM berdasarkan UUID atau nama
`vm_action`	Tindakan siklus hidup: `start`, `shutdown`, `reboot`, `pause`, `resume`, `reset`, `force-off`, `force-reboot`
`vm_delete`	Hapus VM (opsional menghapus volume disk)
`vm_snapshots`	Menampilkan/membuat/memulihkan/menghapus snapshot VM
`vm_backups`	Menampilkan/membuat/menghapus backup VM (penuh/incremental/diferensial)
`vm_templates`	Menampilkan/mendapatkan/menghapus template VM
`vm_metrics`	Dapatkan metrik CPU, memori, disk, dan jaringan secara langsung

Jaringan Virtualisasi

Alat	Deskripsi
`virt_network`	Mengelola jaringan virtual libvirt: `list`, `get`, `start`, `stop`, `delete`, `dhcp_leases`

Penyimpanan Virtualisasi

Alat	Deskripsi
`virt_storage_pool`	Mengelola storage pool: `list`, `get`, `start`, `stop`, `delete`
`virt_volume`	Mengelola volume penyimpanan: `list`, `get`, `create`, `delete`, `resize`
`virt_iso`	Mengelola image ISO: `list`, `get`, `delete`

Jaringan Host

Alat	Deskripsi
`host_network_interfaces`	Menampilkan daftar antarmuka jaringan fisik/virtual
`host_network_bridges`	Menampilkan daftar perangkat bridge Linux
`host_network_bonds`	Menampilkan daftar perangkat bond jaringan
`host_network_vlans`	Menampilkan daftar antarmuka VLAN

Penyimpanan Host

Alat	Deskripsi
`host_storage_disks`	Menampilkan daftar perangkat blok fisik
`host_storage_lvm_vgs`	Menampilkan daftar LVM volume groups
`host_storage_lvm_lvs`	Menampilkan daftar LVM logical volumes
`host_storage_lvm_pvs`	Menampilkan daftar LVM physical volumes
`host_storage_raid`	Menampilkan daftar RAID/MD arrays

5. Konfigurasi Klien

Claude Desktop

Tambahkan konfigurasi berikut ke file pengaturan Claude Desktop Anda:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

json

{
  "mcpServers": {
    "vapor": {
      "type": "streamableHttp",
      "url": "https://<vapor-host>:7770/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-token>"
      }
    }
  }
}

Untuk sertifikat self-signed, pastikan Anda telah mempercayai sertifikat CA tersebut di tingkat sistem operasi (lihat Bagian 2, Metode 1) sebelum menjalankan Claude Desktop.

Ekstensi MCP Cursor / VS Code

Dalam file konfigurasi .cursor/mcp.json proyek Anda atau pengaturan MCP yang setara:

json

{
  "mcpServers": {
    "vapor": {
      "type": "streamableHttp",
      "url": "https://<vapor-host>:7770/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-token>"
      }
    }
  }
}

Jika menggunakan sertifikat self-signed dengan klien MCP berbasis Node.js, atur variabel lingkungan berikut sebelum menjalankan aplikasi:

bash

export NODE_EXTRA_CA_CERTS=/path/to/vapor-server.crt

6. Penanganan Kesalahan (Error Handling)

Kesalahan JSON-RPC

Server MCP menggunakan kode kesalahan standar JSON-RPC 2.0:

Kode	Arti	Deskripsi
-32700	Parse error	Format JSON pada body permintaan salah
-32600	Invalid request	Kolom `jsonrpc` hilang atau versi salah
-32601	Method not found	Nama metode tidak dikenal
-32602	Invalid params	Parameter metode tidak sesuai
-32603	Internal error	Kesalahan pada sisi server

Kesalahan Alat (Tool Errors)

Kesalahan alat dikembalikan sebagai respons JSON-RPC yang sukses dengan properti isError: true di dalam hasilnya:

json

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [{"type": "text", "text": "Failed to start VM: domain is already running"}],
    "isError": true
  }
}

Hal ini memungkinkan agen AI untuk melihat pesan kesalahan tersebut dan memutuskan tindakan selanjutnya.

Kesalahan Autentikasi

HTTP Status	Arti
401	Header `Authorization` hilang atau tidak valid
403	Token valid tetapi izin akses tidak mencukupi

7. Manajemen Sesi

Sesi dibuat secara otomatis saat Anda mengirimkan permintaan initialize.
Server mengembalikan header Mcp-Session-Id — sertakan header ini di semua permintaan berikutnya.
Sesi kedaluwarsa setelah 30 menit tidak ada aktivitas.
Sesi disimpan di dalam memori dan akan hilang saat server dihidupkan ulang.
Untuk mengakhiri sesi lebih awal, kirimkan permintaan DELETE /api/v1/mcp beserta header sesi terkait.

Jika sesi kedaluwarsa, klien harus melakukan inisialisasi ulang dengan mengirimkan permintaan initialize yang baru.

8. Pertimbangan Keamanan

Selalu gunakan TLS. Endpoint MCP mentransmisikan token autentikasi dan dapat mengembalikan data infrastruktur yang sensitif. Jangan pernah menjalankan Vapor tanpa TLS di lingkungan jaringan.
Gunakan API token untuk agen. API token disesuaikan per pengguna, persisten, dan dapat dicabut secara individual. Buat token khusus untuk setiap integrasi agen AI dan berikan nama yang deskriptif (misalnya, claude-desktop, cursor-ide).
Batasi akses jaringan. Jika host Vapor hanya diakses dari mesin tertentu, gunakan aturan firewall untuk membatasi akses port 7770.

Cabut token jika tidak lagi diperlukan:

bash

curl -ksS -X DELETE "https://<host>:7770/api/v1/auth/tokens/<token-id>" \
  -H "Authorization: Bearer <jwt>"

Pantau panggilan alat. Semua pemanggilan alat MCP dicatat oleh Vapor beserta ID sesi untuk kebutuhan audit. Periksa log server untuk entri berlabel [MCP].

Integrasi Model Context Protocol (MCP) ​

Ikhtisar ​

Informasi Utama ​

1. Autentikasi ​

Opsi A: API Token (Disarankan untuk Agen AI) ​

Opsi B: JWT Token (Berumur Pendek) ​

2. Menangani Sertifikat TLS Self-Signed ​

Memahami Masalah ​

Mendapatkan Sertifikat CA ​

Metode 1: Mempercayai CA Self-Signed (Disarankan untuk Produksi) ​

Metode 2: Menentukan CA Bundle saat Runtime ​

Metode 3: Menonaktifkan Verifikasi TLS (Hanya untuk Pengembangan) ​

Metode 4: Menggunakan Sertifikat CA yang Valid (Disarankan untuk Produksi Multi-Pengguna) ​

3. Alur Protokol MCP ​

Siklus Hidup Koneksi ​

Tahapan dengan curl ​

4. Alat yang Tersedia ​

Manajemen Mesin Virtual ​

Jaringan Virtualisasi ​

Penyimpanan Virtualisasi ​

Jaringan Host ​

Penyimpanan Host ​

5. Konfigurasi Klien ​

Claude Desktop ​

Ekstensi MCP Cursor / VS Code ​

6. Penanganan Kesalahan (Error Handling) ​

Kesalahan JSON-RPC ​

Kesalahan Alat (Tool Errors) ​

Kesalahan Autentikasi ​

7. Manajemen Sesi ​

8. Pertimbangan Keamanan ​

Integrasi Model Context Protocol (MCP)

Ikhtisar

Informasi Utama

1. Autentikasi

Opsi A: API Token (Disarankan untuk Agen AI)

Opsi B: JWT Token (Berumur Pendek)

2. Menangani Sertifikat TLS Self-Signed

Memahami Masalah

Mendapatkan Sertifikat CA

Metode 1: Mempercayai CA Self-Signed (Disarankan untuk Produksi)

Metode 2: Menentukan CA Bundle saat Runtime

Metode 3: Menonaktifkan Verifikasi TLS (Hanya untuk Pengembangan)

Metode 4: Menggunakan Sertifikat CA yang Valid (Disarankan untuk Produksi Multi-Pengguna)

3. Alur Protokol MCP

Siklus Hidup Koneksi

Tahapan dengan curl

4. Alat yang Tersedia

Manajemen Mesin Virtual

Jaringan Virtualisasi

Penyimpanan Virtualisasi

Jaringan Host

Penyimpanan Host

5. Konfigurasi Klien

Claude Desktop

Ekstensi MCP Cursor / VS Code

6. Penanganan Kesalahan (Error Handling)

Kesalahan JSON-RPC

Kesalahan Alat (Tool Errors)

Kesalahan Autentikasi

7. Manajemen Sesi

8. Pertimbangan Keamanan