Setup MCP Windsurf: Generate Gambar di Cascade

Server MCP di Windsurf adalah kotak peralatan eksternal yang dapat dipanggil oleh agen di tengah percakapan: Anda mendeklarasikannya sekali di mcp_config.json, dan Cascade langsung memperoleh kemampuan yang tidak dimiliki model dasar. Pembuatan gambar adalah kebutuhan yang paling jelas. Windsurf dengan mudah menyusun layar pengaturan, menghubungkan rute, dan menulis pengujian, tetapi meninggalkan tiga persegi panjang abu-abu di tempat ilustrasi seharusnya berada.

Versi ringkas jika Anda hanya butuh langkah cepat: Buat kunci di profil BananaBanana, lalu tambahkan blok berikut ke ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "bananabanana": {
      "serverUrl": "https://bananabanana.pro/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:BB_API_KEY}"
      }
    }
  }
}

Ekspor variabel export BB_API_KEY=bb_live_KUNCI_ANDA, muat ulang server MCP, dan sepuluh alat akan muncul di Cascade. Biaya gambar mulai dari $0.03 per gambar dari saldo prabayar, video mulai $0.10, tanpa langganan dan tanpa perlu menyiapkan proyek cloud sendiri. Satu catatan penting sebelum menyalin: pada build terbaru, file tersebut mungkin bukan lagi file yang dibaca oleh agen Anda. Penjelasannya ada di bawah.

Mengapa memberi Cascade generator gambar?

Karena saat Anda membutuhkan gambar hampir tidak pernah merupakan saat yang tepat untuk meninggalkan editor kode. Anda sedang fokus menyusun alur onboarding, empty state membutuhkan ilustrasi, dan alternatifnya adalah membuka tab browser, menulis prompt, mengunduh, mengganti nama, menyeret ke public/, lalu mencari kembali baris kode tempat Anda berhenti.

Satu instruksi menggantikan seluruh kerumitan tersebut. Cascade menulis prompt, memanggil generate_image, memindahkan file ke folder yang tepat, dan menulis tag <img> lengkap dengan teks alt. Anda hanya perlu meninjau diff.

Ada alasan kedua yang sangat penting untuk klien ini. Cascade dirancang untuk membangun fitur lengkap, bukan hanya editan tunggal, sehingga aset yang dibutuhkan biasanya datang dalam satu paket: tiga empty state, enam thumbnail kategori, paket avatar sementara. Membuat setelan gambar secara manual di tab browser sangat membuang waktu.

Alternatif dari server jarak jauh adalah menjalankan server MCP gambar lokal di mesin Anda, yang memerlukan proses Node atau Python serta kunci penyedia upstream sendiri beserta kuota dan penagihan mandiri. Server jarak jauh meniadakan kedua kerepotan itu. Endpoint berjalan di infrastruktur kami pada pipeline yang sama dengan generator web, dan satu-satunya kredensial Anda adalah string bb_live_ yang dapat dicabut kapan saja dari halaman profil.

Di mana Windsurf menyimpan konfigurasi MCP sekarang?

Ini adalah poin yang membingungkan banyak pengguna pada Agustus 2026, dan perlu diperiksa sebelum Anda mengedit file apa pun. Windsurf kini menjadi bagian dari Devin Desktop Cognition: windsurf.com mengalihkan ke devin.ai/desktop, dan URL lama docs.windsurf.com/windsurf/cascade/mcp dialihkan (307) ke docs.devin.ai/desktop/cascade/mcp. Aplikasi di disk tetap bernama Windsurf, skema deeplink tetap windsurf://, dan folder konfigurasi tetap ~/.codeium/windsurf/. Hanya penamaan merek yang berubah.

Perubahan sebenarnya adalah kini ada dua agen dengan dua sistem konfigurasi yang berbeda. Dokumentasi Cascade MCP menyatakannya dalam kotak peringatan di bagian atas: file mcp_config.json berlaku untuk agen Cascade klasik, sedangkan agen Devin Local (default untuk tab baru) membaca konfigurasi Devin CLI. Diverifikasi pada 20 Agustus 2026.

Jadi pilih file sesuai agen yang sedang Anda ajak bicara.

Cascade klasik membaca ~/.codeium/windsurf/mcp_config.json (%USERPROFILE%\.codeium\windsurf\mcp_config.json di Windows). Server jarak jauh di sana menerima kolom serverUrl atau url ditambah headers, sesuai cuplikan di awal artikel ini.

Agen Devin Local membaca file konfigurasi CLI: ~/.config/devin/mcp_config.json untuk cakupan pengguna, .devin/mcp_config.json untuk proyek bersama di git, dan .devin/mcp_config.local.json untuk nilai pribadi (otomatis diabaikan oleh git). Nama kolom sedikit berbeda:

{
  "mcpServers": {
    "bananabanana": {
      "url": "https://bananabanana.pro/api/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer ${env:BB_API_KEY}"
      }
    }
  }
}

Atau lewati editor: perintah devin mcp add bananabanana https://bananabanana.pro/api/mcp akan membuat entri di cakupan lokal, lalu Anda tinggal menambahkan blok headers. Perintah devin mcp list dan devin mcp get bananabanana menampilkan dengan jelas apa yang sebenarnya dimuat oleh CLI.

Di kedua konfigurasi, endpoint-nya adalah https://bananabanana.pro/api/mcp. Bukan /mcp, yang merupakan halaman dokumentasi web untuk dibaca manusia. Permintaan POST ke sana akan menghasilkan respons HTML dan membingungkan agen. Halaman server MCP kami menyediakan cuplikan yang sama beserta tabel kompatibilitas untuk semua klien terverifikasi:

Setelah terhubung, panggilan list_models dan get_account gratis — minta Cascade menjalankannya sebagai uji coba awal. get_account mengembalikan saldo Anda, nama kunci, dan batas harian, cara yang tepat untuk memverifikasi autentikasi tanpa membuang biaya untuk membuat gambar.

Contoh kasus: rangkaian empty state untuk aplikasi yang baru dibuat Cascade

Skenario nyata tempat saya membuat demo ini. Cascade menyusun struktur antarmuka alat internal, tiga empty state hadir sebagai placeholder div abu-abu, dan alih-alih membuka aplikasi desain grafis, Anda cukup memberikan kalimat deskripsi gaya kepada agen untuk menghasilkan satu set lengkap.

Kalimat deskripsi gaya adalah kuncinya. Tampilan empty state hanya terlihat bagus jika serasi: palet warna, ketebalan garis, dan ruang negatif harus konsisten dari satu gambar ke gambar berikutnya. Tulis deskripsi gaya sekali, perintahkan agen untuk menggunakannya secara persis di setiap pemanggilan, dan ubah subjeknya saja:

→ generate_image {"prompt": "A flat vector illustration for an app empty
   state: an open cardboard box floating above a soft shadow with three small
   paper envelopes drifting out of it, muted teal and warm coral palette on an
   off-white background, thin confident outlines, generous negative space,
   centered composition, no text", "model": "nano-banana-pro",
   "aspect_ratio": "4:3"}
← {"job_id": "…", "status": "processing", "cost_charged_usd": 0.11}

Kemudian gunakan kalimat gaya yang sama dengan subjek berbeda untuk layar «tidak ada hasil»:

Hasilnya serasi sebagai satu set placeholder. Jika Anda membutuhkan keseragaman yang lebih ketat, generate_image mendukung parameter seed, dan mengulang seed yang sama dengan kalimat gaya yang sama akan menghasilkan output yang semakin mirip. Untuk karakter atau maskot yang harus konsisten di belasan gambar, teknik prompt lebih menentukan dibanding klien itu sendiri, sebagaimana dibahas dalam panduan konsistensi karakter.

Dua catatan jujur: Saya membuat contoh-contoh ini menggunakan Nano Banana Pro seharga $0.11 karena ditampilkan langsung di artikel ini dan membutuhkan detail tinggi. Untuk placeholder sementara yang akan diganti desainer dalam dua minggu, nano-banana-2-lite seharga $0.03 adalah pilihan tepat, dan panduan Lite kami menjelaskan batasan kemampuannya. Model ini juga merupakan default dari tool tersebut.

Video juga dapat dibuat dari chat yang sama. generate_video tidak pernah memotong saldo pada pemanggilan pertama: ia memberikan estimasi harga, dan agen harus mengulangi pemanggilan dengan parameter confirm_cost yang bernilai tepat sama sebelum render dimulai. Video 4 detik tanpa suara 720p pada Veo 3.1 Lite mulai dari $0.10; Omni Flash bertarif $0.10 per detik dengan suara bawaan aktif, sehingga klip 3 detik berharga $0.30.

Catatan penting Windsurf yang perlu diketahui

Lima poin praktis yang saya catat selama proses konfigurasi:

1. Variabel lingkungan yang tidak disetel gagal tanpa pesan error. Dokumentasi menyatakan dengan jelas: ${env:NAMA_VARIABEL} digantikan dengan nilai variabel, dan jika tidak disetel, akan berubah menjadi string kosong. Tanpa peringatan atau error. Header dikirimkan hanya berupa Bearer , server merespons 401, dan masalah tampak seperti kerusakan server padahal hanya variabel yang hilang. Aplikasi yang diluncurkan dari GUI tidak membaca profil shell, sehingga perintah export di .zshrc tidak terbaca kecuali Windsurf dibuka dari terminal. Jika list_models memunculkan error autentikasi, periksa variabel terlebih dahulu.

2. Sintaks ${file:…} lebih andal dan merupakan fitur khas Windsurf. Konfigurasi mendukung ${file:/path/to/file} yang akan membaca isi file yang telah dipangkas spasinya, termasuk path dengan tilde ~. Penulisan "Authorization": "Bearer ${file:~/.secrets/bb_key.txt}" bekerja tanpa variabel lingkungan dan menyelesaikan masalah peluncuran via GUI. Saya merekomendasikan opsi ini di Windsurf. Cursor dan VS Code tidak memilikinya.

3. Cascade memiliki batas maksimal 100 alat. Ini adalah batas total untuk semua server MCP yang terhubung. Pada menu pengaturan masing-masing server, Anda dapat menonaktifkan alat yang tidak diperlukan. Kami menambahkan sepuluh alat. Jika Anda sudah menggunakan beberapa server besar, nonaktifkan alat yang tidak terpakai: generate_speech, edit_video, dan list_generations dapat dimatikan jika Anda hanya membutuhkan gambar.

4. Deeplink satu klik tidak menyertakan kunci Anda demi keamanan. Windsurf mendukung tautan windsurf://windsurf-mcp-registry?serverName=<name> yang membuka halaman marketplace untuk ditinjau sebelum pemasangan. Keunggulannya: tidak ada konfigurasi terenkode yang berisiko membocorkan kredensial melalui URL bersama. Karena server kami belum masuk ke marketplace publik, kita menggunakan konfigurasi manual via JSON.

5. Pada paket tim, ID server bersifat peka huruf besar/kecil (case-sensitive). Begitu admin memasukkan satu server MCP ke whitelist, semua server lain otomatis terblokir untuk tim, dan Server ID yang diizinkan harus sama persis dengan nama kunci di mcp_config.json. Artinya jika admin menyetujui bananabanana dan file Anda menulis BananaBanana, koneksi akan gagal tanpa penjelasan error yang jelas. Tim Enterprise juga dapat mengarahkan Windsurf ke registri MCP internal mereka.

Catatan pengalaman pengguna: generate_speech mengembalikan audio berupa URL dan bukan pemutar audio terintegrasi di Cascade, sehingga file harus dibuka terpisah. Namun untuk gambar, tersedia pratinjau thumbnail langsung di samping tautan.

Bagaimana dengan OAuth dibanding API Key?

Kedua jalur tersedia dan masing-masing ditujukan untuk agen yang berbeda.

Devin CLI (agen Devin Local) memiliki dukungan OAuth penuh: perintah devin mcp login <name> membuka alur login di browser, menyimpan token secara lokal dan memperbaruinya otomatis melalui Dynamic Client Registration (DCR) tanpa pendaftaran manual. Server kami merupakan server otorisasi OAuth 2.1 dengan DCR dan indikator sumber daya RFC 8707.

Dalam artikel ini saya menguji jalur API key (initialize, get_account, list_models dengan kunci bb_live_ asli). Jika Anda mencoba OAuth dan mengalami kendala, opsi penting yang perlu diperhatikan adalah oauthResource, yang menimpa parameter resource RFC 8707, karena endpoint kami menerima audiens https://bananabanana.pro/api/mcp.

Ada pula alasan praktis untuk memilih API key: kunci gratis dan dapat dibuat beberapa buah, masing-masing memiliki log penggunaan sendiri (alat, model, biaya, ringkasan prompt) dan batas harian USD opsional di Profil → Kunci API MCP. Batas harian ini adalah perlindungan terbaik sebelum memberikan akses alat berbayar ke agen otonom.

Terkait izin: konfigurasi Devin CLI mendukung aturan per alat menggunakan pencocokan mcp__<server>__<tool>, yang sangat cocok untuk server berbayar.

{
  "permissions": {
    "allow": ["mcp__bananabanana__list_models", "mcp__bananabanana__get_result"],
    "ask": ["mcp__bananabanana__generate_video"]
  }
}

Permintaan informasi gratis akan berjalan tanpa interupsi, sementara proses render akan meminta konfirmasi terlebih dahulu.

Berapa biaya pembuatan media demo di artikel ini?

Harga standar per generasi, sama persis dengan angka yang dilaporkan list_models ke agen:

Kedua empty state berhasil dibuat pada percobaan pertama berkat toleransi gaya vektor flat. Untuk foto produk fotorealistik, sebaiknya sediakan anggaran untuk beberapa kali generate ulang.

Jika Anda sudah menggunakan server ini di editor lain, konfigurasi Windsurf di atas adalah satu-satunya bagian baru: kunci, saldo, dan riwayat generasi tetap sama. Panduan kami untuk Cursor dan VS Code membahas penggunaan server ini di editor tersebut. Siap memulai? Buat kunci API dan minta Cascade membuat gambar pertama Anda.

Pertanyaan Umum (FAQ)

Apakah Windsurf mendukung server MCP jarak jauh dengan header Authorization?

Ya. Server HTTP jarak jauh di mcp_config.json menerima kolom serverUrl (atau url) dan objek headers opsional. Cascade mendukung protokol stdio, Streamable HTTP, dan SSE. Kolom serverUrl dan headers mendukung interpolasi ${env:VAR} dan ${file:/path} agar kunci tidak tersimpan sebagai teks biasa. Diverifikasi sesuai dokumentasi resmi per 20 Agustus 2026.

File konfigurasi mana yang sebenarnya dibaca oleh agen Windsurf saya?

Tergantung agen yang digunakan. Agen Cascade klasik membaca ~/.codeium/windsurf/mcp_config.json. Agen Devin Local (default pada tab baru) membaca file Devin CLI: ~/.config/devin/mcp_config.json, .devin/mcp_config.json, atau .devin/mcp_config.local.json untuk kunci pribadi. Jika server tidak muncul setelah diedit, periksa perbedaan ini terlebih dahulu.

Apakah saya memerlukan akun cloud sendiri untuk membuat gambar di Windsurf?

Tidak. Server MCP gambar lokal memerlukan kunci penyedia pihak ketiga dengan kuota dan tagihan mandiri. Server jarak jauh menjalankan proses generasi pada infrastruktur terkelola kami, sehingga Anda hanya memerlukan kunci bb_live_ dari profil Anda. Akun baru mendapatkan saldo awal $0.20, cukup untuk 6 gambar pada model ekonomis tanpa membayar apa pun.

Bisakah Cascade membuat video melalui server yang sama?

Bisa, dengan langkah konfirmasi wajib. generate_video memberikan penawaran harga pada pemanggilan pertama tanpa memotong saldo; agen harus mengulangi pemanggilan dengan menyertakan confirm_cost sesuai nominal tersebut sebelum render dimulai. Harga mulai dari $0.10 untuk klip 4 detik tanpa suara 720p pada Veo 3.1 Lite hingga $4.40 untuk render kualitas tertinggi Veo 3.1 dengan audio; Omni Flash bertarif $0.10 per detik dengan audio bawaan. Pembuatan video membutuhkan waktu satu hingga sepuluh menit, dan agen akan melakukan polling berkala melalui get_result.

Mengapa server MCP saya menampilkan error autentikasi di Windsurf?

Sembilan dari sepuluh kasus disebabkan oleh masalah kredensial dan bukan kesalahan sintaks. Variabel ${env:BB_API_KEY} yang belum disetel akan berubah menjadi string kosong tanpa memunculkan error, mengirimkan bearer token kosong dan menerima respons 401. Pastikan variabel dapat dibaca oleh proses Windsurf (peluncuran via GUI tidak membaca profil shell) atau beralihlah ke ${file:~/.secrets/bb_key.txt}. Jika kunci sudah benar tetapi alat belum muncul, pastikan URL berakhiran /api/mcp dan whitelist tim tidak memblokir Server ID.