Windsurf MCP Kurulumu: Cascade İçinde Görsel Üretimi

Windsurf'teki bir MCP sunucusu, ajanın konuşma sırasında başvurabileceği harici bir araç kutusudur: mcp_config.json içine bir kez tanımlarsınız ve Cascade, temel modelde varsayılan olarak bulunmayan yetenekleri kazanır. Görsel üretimi buradaki en belirgin eksikliktir. Windsurf bir ayar ekranının iskeletini kolayca çıkarır, yönlendirmeleri bağlar ve testleri yazar; ancak illüstrasyonların gelmesi gereken yerde üç adet gri dikdörtgen bırakır.

Hızlıca başlamak isteyenler için özet adımlar: BananaBanana profilinizde bir anahtar oluşturun, ardından ~/.codeium/windsurf/mcp_config.json dosyasına şu bloğu ekleyin:

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

export BB_API_KEY=bb_live_ANAHTARINIZ ile ortam değişkenini ayarlayın, MCP sunucularını yeniden yükleyin ve Cascade içinde on yeni araç kullanıma açılsın. Görseller ön ödemeli bakiyenizden görsel başına $0.03'tan, videolar ise $0.10'dan ücretlendirilir; abonelik veya kendi bulut projenizi kurma zorunluluğu yoktur. Yapıştırmadan önce önemli bir detay: güncel sürümlerde ajanınız artık bu dosyayı okumuyor olabilir. Ayrıntılar aşağıda.

Cascade'e neden bir görsel üretici eklemelisiniz?

Çünkü bir görsele ihtiyaç duyduğunuz an, kod editöründen ayrılmak için neredeyse hiçbir zaman doğru an değildir. Bir onboarding akışının derinliklerindesinizdir, boş durum (empty state) için bir çizim gereklidir ve alternatif yöntem şudur: yeni bir tarayıcı sekmesi aç, prompt yaz, indir, yeniden adlandır, public/ dizinine taşı ve ardından kodda nerede kaldığını bulmaya çalış.

Tek bir komut tüm bu süreci ortadan kaldırır. Cascade prompt'u yazar, generate_image aracını çağırır, dosyayı doğru klasöre kaydeder ve alt metniyle birlikte <img> etiketini yazar. Size sadece diff'i incelemek kalır.

Bu istemci için daha da önemli olan ikinci bir neden var: Cascade, tekil düzenlemelerden ziyade komple özellikler geliştirmek üzere tasarlanmıştır; bu nedenle ihtiyaç duyduğu görsel varlıklar setler halinde gelir: üç boş durum ekranı, altı kategori küçük resmi, geçici bir avatar paketi. Bunları tarayıcı sekmelerinde tek tek üretmek iş akışını ciddi şekilde böler.

Uzak sunucunun alternatifi, yerel bir görsel MCP sunucusu çalıştırmaktır; bu da bilgisayarınızda bir Node veya Python işlemi ve kendi sağlayıcı anahtarınız ile kota takibi gerektirir. Uzak sunucu iki zahmetten de kurtarır. Uç nokta bizim tarafımızda, web oluşturucu ile aynı altyapıda çalışır ve tek kimlik bilginiz profil sayfasından dilediğiniz an iptal edebileceğiniz bir bb_live_ anahtarıdır.

Windsurf MCP yapılandırmasını artık nerede tutuyor?

Ağustos 2026 itibarıyla birçok geliştiricinin takıldığı nokta burasıdır ve herhangi bir dosyayı düzenlemeden önce kontrol edilmelidir. Windsurf artık Cognition bünyesindeki Devin Desktop'ın bir parçasıdır: windsurf.com adresi devin.ai/desktop adresine yönlenir ve eski docs.windsurf.com/windsurf/cascade/mcp URL'si docs.devin.ai/desktop/cascade/mcp adresine 307 ile yönlendirilir. Diskteki uygulama adı hâlâ Windsurf, bağlantı şeması windsurf:// ve yapılandırma klasörü ~/.codeium/windsurf/ olarak kalmıştır. Sadece marka ismi değişti.

Asıl değişen şey ise artık iki farklı ajan ve iki yapılandırma sistemi bulunmasıdır. Cascade MCP belgeleri sayfasının başındaki uyarı kutusunda bunu açıkça belirtir: mcp_config.json dosyası klasik Cascade ajanı için geçerlidir; yeni sekmelerin varsayılanı olan Devin Local ajanı ise Devin CLI yapılandırmasını okur. Kontrol tarihi: 20 Ağustos 2026.

Bu yüzden dosyanızı etkileşimde bulunduğunuz ajana göre seçin.

Klasik Cascade, ~/.codeium/windsurf/mcp_config.json (Windows üzerinde %USERPROFILE%\.codeium\windsurf\mcp_config.json) dosyasını okur. Buradaki uzak sunucular serverUrl veya url alanı ile birlikte headers alır; bu da makalenin başındaki kod bloğudur.

Devin Local ajanı, CLI yapılandırma dosyalarını okur: kullanıcı kapsamı için ~/.config/devin/mcp_config.json, git üzerinden paylaşılan projeler için .devin/mcp_config.json ve kişisel değerler için .devin/mcp_config.local.json (otomatik olarak gitignore edilir). Alan adları küçük farklılıklar gösterir:

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

Veya doğrudan CLI kullanabilirsiniz: devin mcp add bananabanana https://bananabanana.pro/api/mcp komutu yerel kapsamda girdiyi oluşturur, ardından headers bloğunu eklersiniz. devin mcp list ve devin mcp get bananabanana komutları CLI'nin gerçekte ne yüklediğini net şekilde gösterir.

Her iki durumda da uç nokta https://bananabanana.pro/api/mcp adresidir. İnsanların okuması için hazırlanan dokümantasyon sayfası olan /mcp değildir. Oraya yapılacak bir POST isteği HTML döndürür ve ajanın kafasını karıştırır. MCP sunucu dokümantasyon sayfamız, doğrulanmış tüm istemciler için aynı kod parçacıklarını ve uyumluluk tablosunu içerir:

Bağlantı kurulduktan sonra list_models ve get_account çağrıları ücretsizdir; bağlantıyı test etmek için Cascade'den bunlardan birini çalıştırmasını isteyin. get_account bakiyenizi, anahtar adını ve günlük limiti döndürür; böylece görsel üretme maliyetine girmeden kimlik doğrulamasını onaylayabilirsiniz.

Kullanım senaryosu: Cascade'in az önce oluşturduğu uygulama için boş durum setleri

Bu demoları hazırlarken kullandığım gerçek senaryo: Cascade dahili bir aracın iskeletini oluşturdu, üç boş durum ekranı gri yer tutucu div'ler olarak belirdi. Bir grafik tasarım programı açmak yerine ajana tek bir stil cümlesi verdiniz ve tüm seti üretmesini istediniz.

Stil cümlesi işin temel sırrıdır. Boş durum görselleri ancak bir grup olarak uyumlu olduklarında iyi görünür: renk paleti, çizgi kalınlığı ve negatif alan oranı bir görselden diğerine tutarlı kalmalıdır. Stil cümlesini bir kez yazın, ajana her çağrıda bunu aynen kullanmasını ve yalnızca ana nesneyi değiştirmesini söyleyin:

→ 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}

Ardından aynı stil cümlesiyle «sonuç bulunamadı» ekranı için farklı bir nesne belirleyin:

Yer tutucu olarak mükemmel bir uyum sergilerler. Daha sıkı bir benzerlik isterseniz generate_image aracı seed parametresini destekler; aynı seed değerini aynı stil cümlesiyle tekrarlamak sonuçları birbirine daha da yaklaştırır. Onlarca görsel boyunca tutarlı kalması gereken karakterler veya maskotlar için prompt tekniği istemciden daha önemlidir; bu konu karakter tutarlılığı kılavuzumuzda detaylıca ele alınmıştır.

İki açık not: Bu örnekleri $0.11 fiyatındaki Nano Banana Pro ile ürettim çünkü bu sayfada yayınlanacaklardı ve yüksek detay gerekiyordu. Bir tasarımcının iki hafta içinde değiştireceği geçici yer tutucular için $0.03'lık nano-banana-2-lite son derece mantıklı bir seçimdir ve Lite kılavuzumuz bu modelin nerelerde fazlasıyla yeterli olduğunu açıklar. Ayrıca aracın varsayılan modeli de budur.

Video üretimi de aynı sohbetten çalışır. generate_video ilk çağrıda asla ücret kesmez: tahmini bir maliyet teklifi sunar ve render başlamadan önce ajanın confirm_cost parametresini tam bu tutarla belirterek çağrıyı tekrarlaması gerekir. Veo 3.1 Lite üzerinde 4 saniyelik sessiz 720p video $0.10'dan başlar; Omni Flash ise ses her zaman açık şekilde saniye başına $0.10 ücretlendirilir (3 saniyelik klip $0.30 tutar).

Dağıtım öncesi bilinmesi gereken Windsurf incelikleri

Kurulum sırasında belirlediğim beş pratik nokta:

1. Tanımlanmamış ortam değişkeni sessizce başarısız olur. Belgeler nettir: ${env:DEGISKEN_ADI} değişkenin değeriyle değiştirilir ve değişken atanmamışsa boş bir dizeye dönüşür. Hata veya uyarı verilmez. Başlık sadece Bearer olarak gönderilir, sunucumuz 401 yanıtı verir ve sorun eksik export yerine sunucu arızası gibi görünür. GUI üzerinden başlatılan uygulamalar kabuk profilini okumaz; bu nedenle Windsurf terminalden başlatılmadıkça .zshrc içindeki export görünmez kalır. list_models kimlik doğrulama hatası verirse önce ortam değişkenini kontrol edin.

2. ${file:…} kullanımı daha güvenlidir ve Windsurf'e özgüdür. Yapılandırma, tilde ~ yolları dahil dosya içeriğindeki boşlukları kırparak okuyan ${file:/dosya/yolu} biçimini destekler. Böylece "Authorization": "Bearer ${file:~/.secrets/bb_key.txt}" hiçbir ortam değişkenine ihtiyaç duymadan çalışır ve GUI başlatma sorununu çözer. Windsurf'te bunu tavsiye ederim. Cursor ve VS Code bu özelliği sunmaz.

3. Cascade en fazla 100 araçla sınırlıdır. Bu, bağlı tüm MCP sunucularınızın toplam araç tavanıdır. Her sunucunun ayarlar sayfasından kullanmadığınız araçları kapatabilirsiniz. Biz on araç ekliyoruz. Halihazırda büyük sunucular kullanıyorsanız (GitHub tek başına onlarca araç içerir), kullanmadıklarınızı devre dışı bırakın: sadece görsel istiyorsanız generate_speech, edit_video ve list_generations kolayca kapatılabilir.

4. Tek tıkla derin bağlantı anahtarınızı taşımaz, bu bir güvenlik artısıdır. Windsurf, kurulumdan önce inceleme için pazar yeri sayfasını açan windsurf://windsurf-mcp-registry?serverName=<name> bağlantılarını destekler. Buradaki avantaj: kodlanmış yapılandırma içermez, dolayısıyla paylaşılan bağlantılardan anahtar sızma riski yoktur. Henüz genel katalogda olmadığımız için manuel JSON kurulumu yapıyoruz.

5. Takım planlarında sunucu kimliği büyük/küçük harfe duyarlıdır. Bir yönetici tek bir MCP sunucusunu izin verilenler listesine aldığında, listede olmayan tüm sunucular tüm ekip için engellenir ve izin verilen Server ID'nin mcp_config.json dosyanızdaki anahtar adıyla harfi harfine eşleşmesi gerekir. Yani yönetici bananabanana onayladıysa ve siz BananaBanana yazdıysanız bağlantı kurulamaz ve hata sebebi açıklanmaz.

Kullanıcı deneyimiyle ilgili bir kısıtlama: generate_speech sesi doğrudan Cascade içinde oynatılabilir bir bileşen yerine URL olarak döndürür, bu yüzden dosyayı harici açmanız gerekir. Görsellerde ise bağlantının yanında küçük bir önizleme sunulur.

API anahtarı yerine OAuth kullanmak nasıl olur?

Her iki yöntem de mevcuttur ve farklı ajanlara hitap eder.

Devin CLI (Devin Local ajanı) tam OAuth desteğine sahiptir: devin mcp login <name> komutu tarayıcıda giriş akışını açar, belirteçleri yerel olarak saklar ve dinamik istemci kaydı (DCR) sayesinde ön yapılandırma gerekmeden otomatik yeniler. Sunucumuz DCR ve RFC 8707 kaynak göstergelerine sahip bir OAuth 2.1 yetkilendirme sunucusudur.

Bu makale için API anahtarı yöntemini test ettim (gerçek bir bb_live_ anahtarıyla initialize, get_account, list_models). OAuth denerken sorun yaşarsanız dikkat etmeniz gereken ayar oauthResource parametresidir; uç noktamız https://bananabanana.pro/api/mcp hedef kitlesini bekler.

Anahtarı tercih etmek için pratik bir neden daha var: Anahtarlar ücretsizdir ve birden fazla oluşturulabilir; her biri kendi kullanım geçmişine (araç, model, maliyet, prompt özeti) ve Profil → MCP API Anahtarları bölümünde isteğe bağlı günlük USD limitine sahiptir. Bu günlük limit, otonom bir ajana harcama yetkisi vermeden önceki en iyi güvenlik önlemidir.

İzinler açısından: Devin CLI yapılandırması mcp__<server>__<tool> seçicileriyle araç bazlı kuralları destekler, bu da ücretli sunucular için idealdir:

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

Ücretsiz bilgi sorguları kesintisiz çalışırken, render başlatan işlemler onayınızı ister.

Bu makaledeki demo medyalarının maliyeti ne oldu?

Üretim başına standart fiyatlar, list_models aracının ajana bildirdiği değerlerin aynısıdır:

Her iki boş durum görseli de ilk denemede başarılı oldu. Gerçekçi ürün fotoğrafları için birkaç deneme payı ayırmak faydalı olacaktır.

Bu sunucuyu başka bir editörde kullanıyorsanız, yukarıdaki Windsurf yapılandırması tek yeni kısımdır: aynı anahtar, aynı bakiye ve aynı geçmiş. Cursor kılavuzumuz ve VS Code kurulumu bu istemcilerdeki adımları ele alır. Başlamaya hazır mısınız? Bir anahtar oluşturun ve Cascade'den ilk görselinizi isteyin.

Sıkça Sorulan Sorular (SSS)

Windsurf Authorization başlığına sahip uzak MCP sunucularını destekler mi?

Evet. mcp_config.json içindeki uzak HTTP sunucuları serverUrl (veya url) alanı ve isteğe bağlı headers nesnesi alır. Cascade stdio, Streamable HTTP ve SSE aktarımlarını destekler. Her iki alan da anahtarın düz metin olarak saklanmasını önlemek için ${env:VAR} ve ${file:/path} enterpolasyonunu destekler. 20 Ağustos 2026 resmi belgelerine göre doğrulanmıştır.

Windsurf ajanım gerçekte hangi yapılandırma dosyasını okuyor?

Kullandığınız ajana bağlıdır. Klasik Cascade ajanı ~/.codeium/windsurf/mcp_config.json dosyasını okur. Yeni sekmelerin varsayılanı olan Devin Local ajanı ise Devin CLI dosyalarını okur: ~/.config/devin/mcp_config.json, .devin/mcp_config.json veya kişisel anahtarlar için .devin/mcp_config.local.json. Yapılandırma sonrası sunucu görünmüyorsa önce bu ayrımı kontrol edin.

Windsurf'te görsel üretmek için kendi bulut hesabıma ihtiyacım var mı?

Hayır. Yerel çalışan görsel MCP sunucuları harici sağlayıcı anahtarlarına ve kendi faturanıza ihtiyaç duyar. Uzak sunucu ise üretimleri bizim yönetilen altyapımızda gerçekleştirir; tek ihtiyacınız profilinizdeki bb_live_ anahtarıdır. Yeni hesaplar $0.20 başlangıç bakiyesiyle açılır, bu da en ucuz modelde ödeme yapmadan 6 görsel üretmek için yeterlidir.

Cascade aynı sunucu üzerinden video da üretebilir mi?

Evet, zorunlu bir onay adımıyla birlikte. generate_video ilk çağrıda fiyat teklifi verir ve bakiye düşmez; ajanın render başlatmadan önce çağrıyı bu tutara eşit bir confirm_cost parametresiyle tekrarlaması gerekir. Fiyatlar Veo 3.1 Lite 720p 4 saniyelik sessiz klip için $0.10'dan sesli üst düzey Veo 3.1 için $4.40'a kadar uzanır; Omni Flash her zaman ses dahil saniye başına $0.10 ücretlendirilir. Kliplerin oluşması bir ila on dakika sürer ve bu sırada ajan get_result ile durumu sorgular.

MCP sunucum Windsurf'te neden kimlik doğrulama hatası veriyor?

On durumun dokuzunda sorun yapılandırma sözdiziminde değil kimlik bilgisindedir. Tanımlanmamış bir ${env:BB_API_KEY}, hata vermeksizin boş dizeye dönüşür, istek boş bearer belirteciyle gider ve 401 yanıtı döner. Değişkenin Windsurf işlemi tarafından görülebildiğinden emin olun veya ${file:~/.secrets/bb_key.txt} yöntemine geçin. Anahtar doğruysa URL'nin /api/mcp ile bittiğini ve takım beyaz listesinin sunucu kimliğini engellemediğini doğrulayın.