Windsurf MCP-Setup: Bilder in Cascade generieren

Ein MCP-Server in Windsurf ist ein externer Werkzeugkasten, den der Agent mitten im Gespräch aufrufen kann: Du trägst ihn einmal in mcp_config.json ein, und Cascade bekommt Fähigkeiten, die das zugrunde liegende Modell nicht mitbringt. Bildgenerierung ist die offensichtliche Lücke. Windsurf baut dir gern einen Einstellungsbildschirm, verdrahtet die Routen und schreibt die Tests – und lässt dir dann drei graue Rechtecke dort, wo die Illustrationen hingehören.

Die Kurzfassung, falls du nur deswegen hier bist. Leg in deinem BananaBanana-Profil einen Schlüssel an und füg dann das hier in ~/.codeium/windsurf/mcp_config.json ein:

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

Exportier BB_API_KEY=bb_live_YOUR_KEY, lade die MCP-Server neu, und in Cascade tauchen zehn Tools auf. Bilder kosten ab $0.03 pro Stück aus einem vorab aufgeladenen Guthaben, Video ab $0.10, ohne Abo und ohne eigenes Cloud-Projekt. Eine Einschränkung, bevor du einfügst: Auf einem aktuellen Build ist diese Datei vielleicht gar nicht mehr die, die dein Agent liest. Dazu gleich mehr.

Warum sollte Cascade einen Bildgenerator bekommen?

Weil der Moment, in dem du ein Bild brauchst, fast nie ein guter Moment ist, den Editor zu verlassen. Du steckst drei Dateien tief in einem Onboarding-Flow, der leere Zustand braucht eine Grafik, und die Alternative heißt: Browser-Tab, Prompt, Download, Umbenennen, Reinziehen nach public/ und dann suchen, wo du eigentlich warst.

Eine Anweisung ersetzt den ganzen Umweg. Cascade schreibt den Prompt, ruft generate_image auf, holt die Datei in den richtigen Ordner und schreibt das <img>-Tag mit Alt-Text. Du prüfst einen Diff.

Es gibt ein zweites Argument, das bei genau diesem Client mehr zählt. Cascade ist darauf ausgelegt, ganze Features zu bauen, nicht einzelne Änderungen, also kommen die nötigen Assets in Sets: drei leere Zustände, sechs Kategorie-Thumbnails, ein Paket Platzhalter-Avatare. Bei Sets bricht der Workflow über den Browser-Tab endgültig zusammen.

Die Alternative zu einem gehosteten Server ist ein lokaler Bild-MCP-Server, also ein Node- oder Python-Prozess auf deinem Rechner plus ein eigener Schlüssel beim Upstream-Anbieter, mit Kontingenten und Abrechnung auf deinem eigenen Konto. Ein Remote-Server spart dir beides. Der Endpoint läuft schon bei uns, auf derselben Pipeline wie der Web-Generator, und deine einzige Zugangsinformation ist ein bb_live_-String, den du auf der Profilseite widerrufen kannst.

Wo speichert Windsurf die MCP-Konfiguration inzwischen?

Hier stolpern im August 2026 viele, und es lohnt sich, das zu prüfen, bevor du irgendetwas bearbeitest. Windsurf heißt jetzt Devin Desktop von Cognition: windsurf.com leitet auf devin.ai/desktop weiter, und die alte URL docs.windsurf.com/windsurf/cascade/mcp antwortet mit 307 auf docs.devin.ai/desktop/cascade/mcp. Auf der Festplatte heißt die App weiterhin Windsurf, das Deeplink-Schema ist weiterhin windsurf://, und der Config-Ordner ist weiterhin ~/.codeium/windsurf/. Umgezogen ist nur das Branding.

Geändert hat sich aber, dass es jetzt zwei Agenten mit zwei Konfigurationssystemen gibt, und die Cascade-MCP-Doku sagt das ganz oben in einem Warnkasten: Die Datei mcp_config.json gilt für den alten Cascade-Agenten, während der Devin-Local-Agent, Standard für neue Tabs, stattdessen die Config der Devin CLI liest. Stand: 20. August 2026.

Wähl die Datei also danach, mit welchem Agenten du tatsächlich sprichst.

Der alte Cascade-Agent liest ~/.codeium/windsurf/mcp_config.json (%USERPROFILE%\.codeium\windsurf\mcp_config.json unter Windows). Remote-Server bekommen dort ein Feld serverUrl oder url plus headers – das ist das Snippet oben in diesem Artikel.

Der Devin-Local-Agent liest die Config-Dateien der CLI: ~/.config/devin/mcp_config.json für den Nutzer-Scope, .devin/mcp_config.json für ein über git geteiltes Projekt und .devin/mcp_config.local.json für persönliche Werte, die automatisch in gitignore landen. Die Feldnamen weichen leicht ab:

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

Oder du lässt den Editor ganz weg: devin mcp add bananabanana https://bananabanana.pro/api/mcp legt den Eintrag im lokalen Scope an, den headers-Block ergänzt du danach. devin mcp list und devin mcp get bananabanana zeigen dir, was die CLI tatsächlich geladen hat – besser als Raten.

So oder so lautet der Endpoint https://bananabanana.pro/api/mcp. Nicht /mcp, denn das ist die Dokumentationsseite für Menschen. Ein POST dorthin liefert HTML und einen sehr verwirrten Agenten. Unsere MCP-Server-Seite enthält dieselben Snippets plus eine Kompatibilitätstabelle für jeden Client, den wir geprüft haben:

Sobald die Verbindung steht: list_models und get_account sind kostenlose Aufrufe, lass Cascade also einen davon als Smoke-Test ausführen. get_account liefert dein Guthaben, den Namen des Schlüssels und sein Tageslimit zurück – ein günstigerer Weg, die Authentifizierung zu prüfen, als dafür ein Bild zu verbrennen.

Anwendungsfall: ein Set leerer Zustände für die App, die Cascade gerade gebaut hat

Das Szenario, um das herum ich diese Demos gebaut habe. Cascade erstellt das Gerüst für ein kleines internes Tool, die drei leeren Zustände landen als Platzhalter-Divs mit grauem Hintergrund, und statt ein Designtool zu öffnen, gibst du dem Agenten einen Stil-Satz und lässt ihn das Set erzeugen.

Der Stil-Satz ist der ganze Trick. Leere Zustände funktionieren nur als Gruppe, also müssen Palette, Linienstärke und Weißraum von einem Bild zum nächsten erhalten bleiben. Schreib die Formulierung einmal, sag dem Agenten, er soll sie bei jedem Aufruf wörtlich wiederverwenden, und variier nur das Motiv:

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

Dann derselbe Satz mit anderem Motiv für den Bildschirm ohne Suchergebnisse:

Nah genug beieinander, um sie als Paar auszuliefern, und das ist die Messlatte für Platzhaltergrafik. Wenn du sie noch enger brauchst: generate_image nimmt einen seed an, und derselbe Seed mit demselben Stil-Satz bringt die Ergebnisse näher zusammen. Bei Figuren oder einem Maskottchen, das ein Dutzend Bilder überstehen muss, zählt die Prompt-Technik mehr als der Client, und der Guide zur Charakterkonsistenz behandelt das gründlich.

Zwei ehrliche Anmerkungen. Ich habe diese Bilder mit Nano Banana Pro für $0.11 generiert, weil sie auf dieser Seite landen und ich die Details wollte. Für Platzhalter, die in zwei Wochen von einer Designerin ersetzt werden, ist nano-banana-2-lite für $0.03 die vernünftige Wahl, und unser Lite-Guide erklärt, ab wann das günstige Modell nicht mehr reicht. Es ist außerdem das Standardmodell des Tools, der Agent landet also dort, solange du nichts anderes sagst.

Video funktioniert aus demselben Chat. generate_video berechnet beim ersten Aufruf nie etwas: Es gibt ein Angebot zurück, und der Agent muss den Aufruf mit confirm_cost auf genau diesen Betrag wiederholen, bevor irgendetwas startet. Veo 3.1 Lite ohne Ton in 720p beginnt bei $0.10 für vier Sekunden. Omni Flash kostet $0.10 pro Sekunde, Ton immer an, für $0.30 bekommst du also einen Take von drei Sekunden.

Windsurf-Eigenheiten, die du vor dem Ausliefern kennen solltest

Fünf Dinge, die ich einem Teamkollegen sagen würde, gesammelt beim Einrichten des Ganzen oben.

1. Eine nicht gesetzte Umgebungsvariable scheitert lautlos. Die Doku ist eindeutig: ${env:VAR_NAME} wird durch den Wert der Variable ersetzt, und ist sie nicht gesetzt, wird daraus ein leerer String. Kein Fehler, keine Warnung. Der Header geht als nacktes Bearer raus, unser Server antwortet mit 401, und das Ganze sieht nach einem kaputten Server aus statt nach einem fehlenden Export. Per GUI gestartete Apps lesen außerdem dein Shell-Profil nicht, ein Export in .zshrc ist also unsichtbar, solange du Windsurf nicht aus einem Terminal gestartet hast. Wenn list_models mit einem Auth-Fehler zurückkommt, prüf zuerst die Variable und erst dann alles andere.

2. ${file:…} ist der bessere Trick, und den gibt es nur in Windsurf. Dieselbe Config unterstützt ${file:/path/to/file}, ersetzt durch den getrimmten Inhalt dieser Datei, Tilde-Pfade inklusive. "Authorization": "Bearer ${file:~/.secrets/bb_key.txt}" funktioniert also ganz ohne Umgebungsvariable und umgeht das komplette GUI-Start-Problem. In Windsurf würde ich das statt ${env:…} nehmen. Cursor und VS Code bieten es nicht an.

3. Cascade ist bei 100 Tools gedeckelt. Laut Doku ist das eine harte Obergrenze über alle verbundenen MCPs hinweg, und auf der Einstellungsseite jedes Servers kannst du einzelne Tools abschalten. Wir bringen zehn mit. Wenn du schon ein paar große Server betreibst (der von GitHub allein hat Dutzende), schalt ab, was du nicht brauchst: generate_speech, edit_video und list_generations kannst du leicht streichen, wenn du nur Standbilder willst.

4. Der Ein-Klick-Deeplink transportiert deinen Schlüssel nicht, und das ist ein Feature. Windsurf unterstützt Links vom Typ windsurf://windsurf-mcp-registry?serverName=<name>, die vor der Installation eine Marketplace-Seite zur Prüfung öffnen. Achte darauf, was fehlt: keine kodierte Konfiguration. Anders als bei Installationslinks, die einen ganzen Config-Block in base64 packen, kann hier nichts eine Zugangsinformation in eine geteilte URL leaken. Wir sind nicht im Marketplace, bei uns ist es also ohnehin manuelles JSON.

5. Im Team-Plan trägt die Server-ID Gewicht. Sobald ein Admin auch nur einen einzigen MCP-Server auf die Allowlist setzt, ist jeder nicht freigegebene Server fürs Team blockiert, und die freigegebene Server-ID muss mit dem Schlüsselnamen in deiner mcp_config.json übereinstimmen, inklusive Groß- und Kleinschreibung. Heißt: Hat dein Admin bananabanana freigegeben und in deiner Datei steht BananaBanana, verbindet sich nichts, und die Fehlermeldung verrät dir nicht, warum. Enterprise-Teams können Windsurf außerdem auf eigene MCP-Registry-URLs statt auf den Standard-Marketplace zeigen lassen.

Eine Einschränkung auf Produktseite, wo wir schon ehrlich über Ecken und Kanten reden: generate_speech gibt Audio als URL zurück, nicht als etwas, das Cascade inline abspielen kann, du öffnest die Datei also selbst. Bilder kommen mit einer kleinen Inline-Vorschau neben dem Link zurück, das ist das nützlichere Verhalten der beiden.

Und OAuth statt API-Schlüssel?

Beide Wege gibt es, und ehrlich gesagt gehören sie zu verschiedenen Agenten.

Die Devin CLI (also der Local-Agent) hat echte OAuth-Unterstützung: devin mcp login <name> öffnet einen Browser-Flow, speichert die Tokens lokal und erneuert sie automatisch, und sie nutzt Dynamic Client Registration, sodass du nichts vorab registrieren musst. Unser Server ist ein OAuth-2.1-Autorisierungsserver mit DCR und Resource Indicators nach RFC 8707, auf dem Papier passt das also zusammen. Die Cascade-Doku gibt außerdem an, dass OAuth für jeden Transporttyp unterstützt wird.

Für diesen Artikel habe ich den Weg mit API-Schlüssel gegen den Endpoint getestet (initialize, get_account, list_models mit einem echten bb_live_-Schlüssel), nicht den Browser-Flow. Betrachte OAuth hier also als „sollte funktionieren, von mir nicht geprüft“. Wenn du es ausprobierst und es hakt, ist oauthResource die Stellschraube, die du suchst: Sie überschreibt den resource-Parameter nach RFC 8707, denn unser Endpoint akzeptiert https://bananabanana.pro/api/mcp als Audience.

Es gibt auch einen praktischen Grund, warum ich standardmäßig den Schlüssel nehme. Schlüssel sind kostenlos, und du kannst mehrere haben, jeder mit eigenem Nutzungsprotokoll (Tool, Modell, Kosten, Prompt-Vorschau) und optionalem USD-Tageslimit unter Profil → MCP-API-Schlüssel. Dieses Limit würde ich tatsächlich einstellen, bevor ich einem autonomen Agenten ein Tool gebe, das Geld ausgibt.

Wo wir bei Berechtigungen sind: Die Config der Devin CLI versteht Regeln pro Tool mit Matchern der Form mcp__<server>__<tool>, was gut zu einem kostenpflichtigen Server passt.

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

Kostenlose Abfragen laufen, ohne dich zu unterbrechen, und alles, was einen Render startet, hält an und fragt nach.

Was haben die Demo-Medien dieses Artikels gekostet?

Standardpreise pro Generierung, dieselben Zahlen, die list_models dem Agenten meldet:

Beide leeren Zustände saßen beim ersten Aufruf, teils Glück, teils weil flache Vektormotive gnädig sind. Bei fotorealistischen Produktbildern solltest du einen zweiten Durchlauf einplanen.

Wenn du diesen Server schon in einem anderen Editor nutzt, ist die Windsurf-Config oben der einzige neue Teil: derselbe Schlüssel, dasselbe Guthaben, derselbe Generierungsverlauf. Die Anleitung für Cursor und das Setup für VS Code behandeln denselben Server aus diesen beiden Clients, und jeder Anwendungsfall lässt sich fast wörtlich übertragen. Bereit? Leg einen Schlüssel an und bitte Cascade um das erste Bild.

FAQ

Unterstützt Windsurf Remote-MCP-Server mit Authorization-Header?

Ja. Remote-HTTP-Server in mcp_config.json bekommen ein Feld serverUrl (oder url) plus ein optionales headers-Objekt, und Cascade unterstützt die Transporte stdio, Streamable HTTP und SSE. Sowohl serverUrl als auch headers akzeptieren Interpolation mit ${env:VAR} und ${file:/path}, der Schlüssel muss also nie im Klartext in der Datei stehen. Das ist die Config, die dieser Guide verwendet, abgeglichen mit der offiziellen Doku am 20. August 2026.

Welche Config-Datei liest mein Windsurf-Agent tatsächlich?

Kommt auf den Agenten an. Der alte Cascade-Agent liest ~/.codeium/windsurf/mcp_config.json. Der Devin-Local-Agent, auf aktuellen Builds Standard für neue Tabs, liest stattdessen die Dateien der Devin CLI: ~/.config/devin/mcp_config.json, .devin/mcp_config.json oder .devin/mcp_config.local.json für persönliche Schlüssel. Wenn dein Server nach einer Config-Änderung partout nicht auftaucht, prüf zuerst diese Aufteilung, denn die Datei, die du bearbeitet hast, ist womöglich einfach nicht die, die gerade gilt.

Brauche ich ein eigenes Cloud-Konto, um in Windsurf Bilder zu generieren?

Nein. Lokal laufende Bild-MCP-Server brauchen einen Schlüssel beim Upstream-Anbieter, mit Kontingenten und Abrechnung auf deinem eigenen Konto. Der Remote-Server generiert über unseren verwalteten Schlüssel-Pool, deine einzige Zugangsinformation ist also der bb_live_-Schlüssel aus deinem Profil. Neue Accounts starten mit $0.20 Guthaben, das sind sechs Bilder mit dem günstigsten Modell, bevor du irgendetwas bezahlst.

Kann Cascade über denselben Server Videos generieren?

Ja, mit einem verpflichtenden Bestätigungsschritt. generate_video gibt beim ersten Aufruf ein Angebot zurück und berechnet nichts. Der Agent muss den Aufruf mit confirm_cost in genau dieser Höhe wiederholen, bevor ein Render startet. Die Preise reichen von $0.10 für einen viersekündigen Clip ohne Ton in 720p mit Veo 3.1 Lite bis $4.40 für einen Veo-3.1-Render der Spitzenklasse mit Ton, und Omni Flash kostet $0.10 pro Sekunde, Ton immer an. Clips brauchen eine bis zehn Minuten, also fragt der Agent get_result ab, während er weiterarbeitet.

Warum zeigt mein MCP-Server in Windsurf einen Auth-Fehler?

In neun von zehn Fällen liegt es an der Zugangsinformation, nicht an der Config. Ein nicht gesetztes ${env:BB_API_KEY} wird zu einem leeren String, statt einen Fehler zu werfen, der Request geht also mit leerem Bearer-Token raus und kommt mit 401 zurück. Prüf, ob die Variable für den Windsurf-Prozess sichtbar ist (GUI-Starts lesen dein Shell-Profil nicht), oder wechsle zu ${file:~/.secrets/bb_key.txt} und spar dir das Problem. Ist der Schlüssel richtig und die Tools tauchen trotzdem nicht auf, prüf, ob die URL auf /api/mcp endet und ob eine Team-Allowlist die Server-ID blockiert.