rekayasa Webship

Hubungkan Agen AI dengan Aman ke Server MCP milik Webship

Siapkan Webship’s plane kontrol MCP yang terisolasi dengan TLS 1.3, token bearer yang kuat, binding loopback, tunnel SSH, validasi konfigurasi, dan checklist respons insiden yang praktis.

Diterbitkan 10 September 2026

# Hubungkan Agen AI dengan Aman ke Server MCP milik Webship

Sebuah koneksi MCP ke server web bukanlah widget obrolan. Ini adalah antarmuka operasi yang dapat memeriksa status produksi, mengubah rute dan kebijakan keamanan, memuat ulang sertifikat, mengaktifkan rilis statis, mengoordinasikan perubahan armada, dan memasang pembaruan Webship yang ditandatangani.

Perlakukan sesuai: sebagai API administratif yang istimewa. Pengaturan Webship yang paling aman menjaga MCP listener tetap mati dari data plane publik, mengikatnya ke loopback, melindunginya dengan TLS 1.3 dan token bearer yang kuat, serta mengaksesnya melalui terowongan SSH yang terotentikasi.

Panduan ini membangun pengaturan tersebut, menjelaskan mengapa setiap batas ada, dan memberikan Anda daftar periksa untuk mengoperasikannya tanpa mengubah kenyamanan menjadi paparan.

Mulailah dengan batas kepercayaan

Lalu lintas publik Webship dan lalu lintas MCP menggunakan pendengar (listeners) yang terpisah. Plane kontrol MCP dinonaktifkan secara default dan tidak pernah berbagi listener HTTP normal, HTTP/2, HTTP/3, atau WebTransport. Ketika diaktifkan, ia melayani MCP melalui endpoint TLS 1.3 HTTP/1.1 yang khusus.

Penempatan yang aman memiliki empat kontrol independen:

Keterjangkauan jaringan: listener MCP terikat ke 127.0.0.1, bukan alamat publik atau LAN pribadi.
Identitas transport: klien memverifikasi sertifikat yang diterbitkan oleh CA yang mereka percayai.
Otentikasi aplikasi: setiap permintaan membawa satu token pembawa yang kuat.
Akses administratif: operator mengakses pendengar loopback melalui akun SSH yang diautentikasi dan terowongan.

Tidak ada dari kontrol ini yang menggantikan yang lain. TLS tanpa jalur jaringan pribadi tetap mengekspos permukaan otentikasi. Terowongan tanpa verifikasi sertifikat membuat identitas titik akhir tidak jelas. Token pembawa di dalam file yang dapat dibaca dunia bukanlah rahasia.

Siapkan sertifikat dan token

Terbitkan sertifikat MCP khusus dari CA internal Anda. Untuk terowongan yang ditunjukkan di bawah ini, sertakan localhost dan 127.0.0.1 dalam nama alternatif subjek sertifikat, lalu instal CA penerbit di penyimpanan tepercaya mesin klien MCP. Jangan menyelesaikan kesalahan kepercayaan dengan opsi TLS yang tidak aman.

Buat token unik dengan setidaknya 32 byte ASCII yang dapat dicetak dan tanpa spasi. Nilai acak 32-byte yang dikodekan sebagai heksadesimal akan memberi Anda 64 karakter aman:

umask 077
openssl rand -hex 32

Webship saat ini membaca token MCP langsung dari konfigurasi TOML yang dilindungi; token_file tidak didukung. Simpan hasilnya dalam file konfigurasi yang hanya dapat dibaca oleh akun layanan Webship dan grup administratifnya. Jangan menempatkan token dalam unit systemd, riwayat shell, tiket, pesan obrolan, atau prompt yang dikirim ke model AI.

Pada host Debian khas:

sudo chown root:webship /etc/webship/production.toml
sudo chmod 0640 /etc/webship/production.toml
sudo chown root:webship /etc/webship/mcp-cert.pem /etc/webship/mcp-key.pem
sudo chmod 0644 /etc/webship/mcp-cert.pem
sudo chmod 0640 /etc/webship/mcp-key.pem

Sesuaikan pengguna layanan dan grup dengan instalasi Anda. Kunci pribadi dan konfigurasi harus dapat dibaca oleh Webship, tetapi tidak oleh akun yang tidak terkait.

Aktifkan pendengar terisolasi

Tambahkan bagian ini ke konfigurasi Webship yang aktif:

[security.mcp]
enabled = true
listen = "127.0.0.1:9443"
token = "replace-with-your-generated-64-character-token"
allowed_ips = []
expose_remote = false

[security.mcp.tls]
cert = "/etc/webship/mcp-cert.pem"
key = "/etc/webship/mcp-key.pem"

Daftar allowed_ips yang kosong tidak membuka endpoint. Klien loopback tetap diizinkan secara default. expose_remote = false membuat batas yang dimaksud menjadi jelas: jika seseorang nanti mengubah listen ke alamat non-loopback, Webship menolak konfigurasi alih-alih secara diam-diam mempublikasikan control plane.

Webship juga menolak pendengar MCP yang diaktifkan tanpa TLS, tanpa token, dengan token yang pendek atau mengandung spasi, atau dengan jalur sertifikat yang kosong. Token placeholder publik ditolak sebelum terekspos secara remote.

Validasi sebelum memulai ulang

MCP listener, identitas TLS, dan perubahan token membangun ulang control plane, jadi mereka memerlukan restart proses. Validasi konfigurasi lengkap terlebih dahulu:

/usr/local/bin/webship --check-config --config /etc/webship/production.toml
sudo systemctl restart webship
sudo systemctl status webship --no-pager

Konfirmasi bahwa pendengar hanya ada di loopback:

ss -ltn | grep '127.0.0.1:9443'

Jangan tambahkan port 9443 ke aturan firewall publik host. Langkah berikutnya akan mengaksesnya melalui SSH.

Buat terowongan pribadi

Dari workstation administrator, teruskan port lokal ke pendengar loopback Webship:

ssh -N \
  -L 127.0.0.1:19443:127.0.0.1:9443 \
  webship-admin@edge.example.com

Klien MCP sekarang terhubung ke https://localhost:19443/mcp. TCP mencapai server SSH, SSH membawa koneksi ke host, dan host membuka koneksi akhir ke Webship pada loopback. Menutup sesi SSH menghapus jalur itu segera.

Gunakan otentikasi SSH berbasis kunci, batasi administrator mana yang dapat membuka terowongan, dan terapkan kontrol akses host normal Anda. Jika diperlukan host lompat, biarkan pendengar MCP pada antarmuka loopback host Webship dan perpanjang jalur SSH alih-alih memperlebar pendengar.

Konfigurasikan klien MCP

Format konfigurasi klien berbeda, tetapi entri HTTP MCP yang khas terlihat seperti ini:

{
  "mcpServers": {
    "webship-production": {
      "url": "https://localhost:19443/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

Gunakan mekanisme rahasia terlindungi milik klien ketika ada. Jika tidak, batasi konfigurasi klien ke akun sistem operasi saat ini. Klien HTTP—bukan model—yang harus menambahkan header otorisasi. Jangan pernah menempelkan token aktif ke dalam percakapan.

Biarkan verifikasi sertifikat tetap diaktifkan. Jika klien menolak sertifikat, perbaiki nama alternatif subjek sertifikat atau pasang CA internal yang benar. Jangan menambahkan bypass permanen.

Jadikan sesi pertama hanya-baca

Setelah terowongan dan klien terhubung, mulailah dengan penemuan dan pemeriksaan:

Minta tools/list; responsnya adalah skema argumen otoritatif untuk rilis yang sedang berjalan.
Hubungi webship.get_config dan catat versi konfigurasi saat ini.
Periksa webship.reverse_proxy.get_status, webship.security.get_status, webship.ddos.get_status, dan webship.tls.get_status sesuai kebutuhan.
Gunakan webship.policy.explain atau webship.security.simulate sebelum mengubah kebijakan.
Konfirmasi bahwa konfigurasi yang dikembalikan menyamarkan token bearer.

Hanya kemudian uji mutasi di lingkungan non-produksi. Mutasi konfigurasi Webship memerlukan ID versi saat ini. Penulisan yang usang ditolak alih-alih menimpa perubahan yang lebih baru. Kebijakan kandidat dapat diperiksa dengan verifikasi bayangan dan skenario laboratorium lalu lintas sebelum aktivasi.

Webship juga menolak penurunan keamanan langsung yang dipilih. Permintaan MCP tidak dapat mematikan WAF, lapisan DDoS, API Shield, tantangan bot, kebijakan edge-auth, atau lapisan header respons yang aktif. Perubahan yang terkait dengan listener, protokol, worker, runtime, dan autentikasi MCP memerlukan restart yang disengaja.

Para penjaga tersebut mengurangi kesalahan; mereka tidak membuat setiap tindakan yang sah menjadi tidak berbahaya. Token tersebut memberikan kontrol yang kuat, termasuk operasi pembaruan dan pelepasan. Tinjau panggilan alat yang diusulkan persis seperti Anda meninjau perintah shell administrator.

Jika pengikatan jarak jauh tidak dapat dihindari

Loopback ditambah SSH adalah desain yang direkomendasikan. Jika lingkungan Anda memerlukan pendengar jaringan pribadi, buat pengecualian tersebut secara eksplisit:

[security.mcp]
enabled = true
listen = "10.20.0.15:9443"
expose_remote = true
allowed_ips = ["10.20.10.0/24"]
token = "replace-with-your-generated-64-character-token"

Pertahankan blok TLS dari contoh sebelumnya, gunakan sertifikat yang sesuai dengan nama DNS pribadi, dan terapkan rentang sumber yang sama di firewall host dan jaringan. Jangan pernah menggunakan 0.0.0.0/0 atau ::/0 sebagai daftar izin untuk kenyamanan. Ingat bahwa daftar izin aplikasi melihat alamat sumber yang benar-benar mencapai Webship; verifikasi perilaku ketika load balancer, gateway NAT, atau service mesh berada di depannya.

Paparan jarak jauh meningkatkan nilai log akses terpusat, jendela operasional yang pendek, dan rotasi cepat. Ini tidak diperlukan hanya karena klien MCP dijalankan di mesin lain; itulah tepatnya yang diselesaikan oleh terowongan SSH.

Operasikan plane kontrol dengan sengaja

Gunakan daftar periksa ini untuk produksi:

Jaga MCP tetap dinonaktifkan di tempat yang tidak diperlukan oleh agen atau operator.
Terikat ke loopback dan gunakan terowongan SSH secara default.
Gunakan identitas TLS khusus dan tetap aktifkan verifikasi sertifikat.
Hasilkan token pembawa unik untuk setiap lingkungan Webship.
Lindungi TOML, konfigurasi klien, kunci TLS, dan kunci SSH dengan izin sistem berkas.
Pisahkan kredensial pengembangan, pengujian, dan produksi.
Mulai sesi dengan alat status dan simulasi kebijakan sebelum mutasi.
Simpan dan tinjau acara audit keamanan Webship.
Putar token dan restart Webship setelah dugaan paparan.
Tutup terowongan saat sesi administratif berakhir.

Untuk respons insiden, tutup terowongan yang aktif, batasi akun SSH, ganti token MCP dalam TOML yang dilindungi, mulai ulang Webship, dan tinjau catatan audit keamanan dan versi konfigurasi terbaru. Jika kunci privat TLS mungkin terekspos, keluarkan sertifikat dan kunci baru sebagai bagian dari proses restart yang sama. Uji token lama setelahnya dan pastikan ditolak.

Sebuah plane kontrol harus tetap menjadi plane kontrol

MCP berguna karena seorang agen dapat memeriksa status nyata dan menerapkan perubahan yang tervalidasi tanpa menjalankan operasi tersebut melalui jalur permintaan publik. Keuntungan itu hilang jika pendengar kontrol menjadi titik akhir internet lain.

Jaga batas tetap sederhana: pendengar terpisah, kemampuan loopback, TLS yang diverifikasi, satu kredensial pembawa yang dilindungi, terowongan yang diautentikasi, perubahan yang diperiksa versinya, dan proses peninjauan manusia untuk operasi yang kuat. Webship menyediakan protokol dan pengaman; operator yang memutuskan siapa yang dapat mengaksesnya.

Panduan ini didasarkan pada dokumentasi operator Webship 1.3.1, contoh konfigurasi yang dikirimkan, kode validasi dan transport MCP, pengaman konfigurasi runtime, dan katalog alat. Tinjau dokumentasi Webship saat ini dan respons tools/list dari server yang sedang berjalan sebelum menerapkannya ke rilis lain.