Server MCP in Windsurf: generare immagini in Cascade

Un server MCP in Windsurf è una cassetta degli attrezzi esterna che l'agente può chiamare a metà conversazione: lo dichiari una volta in mcp_config.json, e Cascade acquisisce capacità che il modello sottostante non ha di serie. La generazione di immagini è la lacuna più evidente. Windsurf ti imbastisce volentieri una schermata di impostazioni, collega le route e scrive i test, poi ti lascia tre rettangoli grigi dove dovrebbero andare le illustrazioni.

In breve, se sei qui solo per questo. Crea una chiave nel tuo profilo BananaBanana, poi aggiungi questo a ~/.codeium/windsurf/mcp_config.json:

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

Esporta BB_API_KEY=bb_live_YOUR_KEY, ricarica i server MCP, e in Cascade compaiono dieci tool. Le immagini costano da $0.03 l'una da un saldo prepagato, i video da $0.10, senza abbonamento e senza un tuo progetto cloud. Un'avvertenza prima di incollare: se usi una build recente, quel file potrebbe non essere più quello che il tuo agente legge. Ci arriviamo tra un attimo.

Perché dare a Cascade un generatore di immagini?

Perché il momento in cui ti serve un'immagine non è quasi mai un buon momento per uscire dall'editor. Sei al terzo file di un flusso di onboarding, lo stato vuoto ha bisogno di un'illustrazione, e l'alternativa è una scheda del browser, un prompt, un download, una rinomina, un trascinamento in public/ e poi la caccia al punto in cui eri rimasto.

Un'istruzione sostituisce tutta la deviazione. Cascade scrive il prompt, chiama generate_image, mette il file nella cartella giusta e scrive il tag <img> con il testo alt. Tu rivedi un diff.

C'è un secondo argomento che per questo client conta di più. Cascade è pensato per costruire funzionalità intere, non singole modifiche, quindi gli asset di cui ha bisogno arrivano a gruppi: tre stati vuoti, sei miniature di categoria, un pacchetto di avatar segnaposto. Fare i gruppi a mano è proprio dove il flusso con la scheda del browser crolla davvero.

L'alternativa a un server ospitato è far girare un server MCP locale per le immagini, cioè un processo Node o Python sulla tua macchina più una tua chiave del provider a monte, con quote e fatturazione sul tuo account. Un server remoto salta entrambe le cose. L'endpoint gira già dalla nostra parte, sulla stessa pipeline del generatore web, e la tua unica credenziale è una stringa bb_live_ che puoi revocare dalla pagina del profilo.

Dove tiene Windsurf la configurazione MCP adesso?

Ecco la parte su cui la gente inciampa ad agosto 2026, e conviene controllarla prima di modificare qualsiasi cosa. Windsurf ora è Devin Desktop di Cognition: windsurf.com reindirizza a devin.ai/desktop, e il vecchio URL docs.windsurf.com/windsurf/cascade/mcp risponde con un 307 verso docs.devin.ai/desktop/cascade/mcp. Sul disco l'app è ancora Windsurf, lo schema dei deeplink è ancora windsurf:// e la cartella di configurazione è ancora ~/.codeium/windsurf/. È cambiato solo il marchio.

Quello che è cambiato davvero è che ora ci sono due agenti con due sistemi di configurazione, e la documentazione MCP di Cascade lo dice in un riquadro di avviso in cima: il file mcp_config.json vale per l'agente Cascade legacy, mentre l'agente Devin Local, quello predefinito per le nuove schede, legge invece la configurazione della Devin CLI. Verificato il 20 agosto 2026.

Quindi scegli il file in base all'agente con cui stai parlando davvero.

Cascade legacy legge ~/.codeium/windsurf/mcp_config.json (%USERPROFILE%\.codeium\windsurf\mcp_config.json su Windows). Lì i server remoti vogliono un campo serverUrl o url più headers, cioè lo snippet all'inizio di questo articolo.

L'agente Devin Local legge i file di configurazione della CLI: ~/.config/devin/mcp_config.json a livello utente, .devin/mcp_config.json per un progetto condiviso via git e .devin/mcp_config.local.json per i valori personali, che finisce in gitignore in automatico. I nomi dei campi cambiano leggermente:

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

Oppure salta l'editor: devin mcp add bananabanana https://bananabanana.pro/api/mcp crea la voce a livello locale, e il blocco headers lo aggiungi dopo. devin mcp list e devin mcp get bananabanana ti dicono cosa ha caricato davvero la CLI, il che è meglio che tirare a indovinare.

In entrambi i casi l'endpoint è https://bananabanana.pro/api/mcp. Non /mcp, che è la pagina di documentazione per le persone. Un POST lì restituisce HTML e un agente molto confuso. La nostra pagina del server MCP riporta gli stessi snippet più una tabella di compatibilità per ogni client che abbiamo verificato:

Una volta connesso, list_models e get_account sono chiamate gratuite, quindi chiedi a Cascade di lanciarne una come smoke test. get_account restituisce il tuo saldo, il nome della chiave e il suo tetto giornaliero: un modo più economico di verificare l'autenticazione che bruciarci sopra un'immagine.

Caso d'uso: una serie di stati vuoti per l'app che Cascade ha appena costruito

Lo scenario attorno a cui ho costruito queste demo. Cascade imbastisce un piccolo strumento interno, i tre stati vuoti arrivano come div segnaposto con sfondo grigio, e invece di aprire un tool di design passi all'agente una frase di stile e gli lasci produrre la serie.

Tutto il trucco sta nella frase di stile. Gli stati vuoti funzionano solo come gruppo, quindi la palette, lo spessore delle linee e la quantità di spazio bianco devono sopravvivere da un'immagine all'altra. Scrivi la frase una volta, di' all'agente di riusarla parola per parola in ogni chiamata e cambia solo il soggetto:

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

Poi la stessa frase con un soggetto diverso per la schermata senza risultati:

Abbastanza vicine da uscire in coppia, che è l'asticella per le illustrazioni segnaposto. Se ti servono ancora più simili, generate_image accetta un seed, e ripetere il seed con la stessa frase di stile avvicina i risultati. Per personaggi o una mascotte che deve reggere su una dozzina di immagini, la tecnica di prompting conta più del client, e la guida alla coerenza del personaggio ne parla come si deve.

Due note oneste. Le ho generate su Nano Banana Pro a $0.11 perché finiscono in questa pagina e volevo il dettaglio. Per segnaposto che un designer sostituirà tra due settimane, nano-banana-2-lite a $0.03 è la scelta sensata, e la nostra guida a Lite spiega dove il modello economico smette di bastare. È anche il modello predefinito del tool, quindi l'agente finisce lì se non dici altrimenti.

Il video funziona dalla stessa chat. generate_video non addebita mai nulla alla prima chiamata: restituisce un preventivo, e l'agente deve ripetere la chiamata con confirm_cost impostato esattamente su quel numero prima che parta qualcosa. Veo 3.1 Lite a 720p senza audio parte da $0.10 per quattro secondi; Omni Flash costa $0.10 al secondo con l'audio sempre attivo, quindi con $0.30 hai una ripresa di tre secondi.

Stranezze di Windsurf da conoscere prima di andare in produzione

Cinque cose che direi a un collega, raccolte mentre configuravo quanto sopra.

1. Una variabile d'ambiente non impostata fallisce in silenzio. La documentazione è esplicita: ${env:VAR_NAME} viene sostituito con il valore della variabile, e se la variabile non è impostata diventa una stringa vuota. Né errore, né avviso. L'header parte come un Bearer nudo, il nostro server risponde 401, e il tutto sembra un server rotto invece di un export mancante. Le app avviate dall'interfaccia grafica non leggono nemmeno il profilo della shell, quindi un export in .zshrc è invisibile, a meno che tu non abbia lanciato Windsurf da un terminale. Se list_models torna con un errore di autenticazione, controlla la variabile prima di tutto il resto.

2. ${file:…} è il trucco migliore, ed è specifico di Windsurf. La stessa configurazione supporta ${file:/path/to/file}, sostituito con il contenuto (ripulito dagli spazi) di quel file, percorsi con tilde compresi. Quindi "Authorization": "Bearer ${file:~/.secrets/bb_key.txt}" funziona senza alcuna variabile d'ambiente, e aggira del tutto il problema dell'avvio da interfaccia grafica. In Windsurf lo userei al posto di ${env:…}. Cursor e VS Code non lo offrono.

3. Cascade si ferma a 100 tool. È un tetto rigido su tutti gli MCP collegati, secondo la documentazione, e la pagina delle impostazioni di ogni server ti permette di disattivare i singoli tool. Noi ne aggiungiamo dieci. Se hai già qualche server grosso attivo (quello di GitHub da solo ne ha decine), spegni quello che non usi: generate_speech, edit_video e list_generations sono tagli facili se ti servono solo immagini statiche.

4. Il deeplink da un clic non trasporta la tua chiave, ed è una funzione, non un difetto. Windsurf supporta link windsurf://windsurf-mcp-registry?serverName=<name> che aprono una pagina del marketplace da rivedere prima dell'installazione. Nota cosa manca: nessuna configurazione codificata, quindi, a differenza dei link di installazione che mettono in base64 un intero blocco di config, qui non c'è niente che possa far trapelare una credenziale in un URL condiviso. Noi non siamo nel marketplace, quindi in ogni caso qui si passa dal JSON a mano.

5. In un piano team, l'ID del server è determinante. Appena un admin mette in allowlist anche un solo server MCP, tutti i server fuori dall'allowlist vengono bloccati per il team, e il Server ID in allowlist deve corrispondere al nome della chiave nel tuo mcp_config.json, maiuscole comprese. In altre parole: se l'admin ha approvato bananabanana e nel tuo file c'è scritto BananaBanana, non si connette e l'errore non spiega perché. I team enterprise possono anche puntare Windsurf ai propri URL di registro MCP invece che al marketplace predefinito.

Un limite dal lato prodotto, già che siamo onesti sugli spigoli: generate_speech restituisce l'audio come URL e non come qualcosa che Cascade possa riprodurre in linea, quindi il file lo apri tu. Le immagini tornano con una piccola anteprima in linea accanto al link, che dei due è il comportamento più utile.

E OAuth al posto di una chiave API?

Esistono entrambe le strade, e la risposta onesta è che appartengono ad agenti diversi.

La Devin CLI (quindi l'agente Local) ha un vero supporto OAuth: devin mcp login <name> apre un flusso nel browser, salva i token in locale e li rinnova in automatico, e usa la registrazione dinamica del client, così non devi preregistrare nulla. Il nostro server è un authorization server OAuth 2.1 con DCR e resource indicator RFC 8707, quindi sulla carta i due combaciano. Anche la documentazione di Cascade dice che OAuth è supportato per ogni tipo di trasporto.

Per questo articolo ho provato sull'endpoint la strada con chiave API (initialize, get_account, list_models con una vera chiave bb_live_) e non il flusso nel browser, quindi considera OAuth qui come «dovrebbe funzionare, non verificato da me». Se lo provi e si comporta male, l'opzione di configurazione che ti serve è oauthResource, che sovrascrive il parametro resource di RFC 8707, dato che il nostro endpoint accetta https://bananabanana.pro/api/mcp come audience.

C'è anche un motivo pratico per cui di default uso la chiave. Le chiavi sono gratis e puoi averne diverse, ognuna con il suo log d'uso (tool, modello, costo, anteprima del prompt) e un tetto giornaliero in USD opzionale in Profilo → Chiavi API MCP. Quel tetto è la cosa che configurerei davvero prima di dare a un agente autonomo un tool che spende soldi.

Già che parliamo di permessi: la configurazione della Devin CLI capisce regole per singolo tool con i matcher mcp__<server>__<tool>, che si sposano bene con un server a pagamento.

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

Le consultazioni gratuite girano senza interromperti, e tutto ciò che avvia un render si ferma e chiede.

Quanto sono costati i media demo di questo articolo?

Prezzi standard per generazione, gli stessi numeri che list_models riporta all'agente:

Entrambi gli stati vuoti sono riusciti alla prima chiamata, un po' per fortuna e un po' perché i soggetti vettoriali flat perdonano molto. Le foto prodotto fotorealistiche sono il caso in cui conviene mettere in conto un rifacimento.

Se usi già questo server in un altro editor, la configurazione di Windsurf qui sopra è l'unica parte nuova: stessa chiave, stesso saldo, stessa cronologia delle generazioni. La guida per Cursor e il setup per VS Code coprono lo stesso server da quei due client, e ogni caso d'uso si trasferisce quasi parola per parola. Pronto? Crea una chiave e chiedi a Cascade la prima immagine.

FAQ

Windsurf supporta i server MCP remoti con un header Authorization?

Sì. I server HTTP remoti in mcp_config.json accettano un campo serverUrl (o url) più un oggetto headers opzionale, e Cascade supporta i trasporti stdio, Streamable HTTP e SSE. Sia serverUrl sia headers accettano l'interpolazione ${env:VAR} e ${file:/path}, quindi la chiave non deve mai stare nel file in chiaro. È la configurazione usata in questa guida, verificata sulla documentazione ufficiale il 20 agosto 2026.

Quale file di configurazione legge davvero il mio agente Windsurf?

Dipende dall'agente. L'agente Cascade legacy legge ~/.codeium/windsurf/mcp_config.json. L'agente Devin Local, quello predefinito per le nuove schede nelle build recenti, legge invece i file della Devin CLI: ~/.config/devin/mcp_config.json, .devin/mcp_config.json, oppure .devin/mcp_config.local.json per le chiavi personali. Se il server non compare dopo una modifica alla configurazione, questa divisione è la prima cosa da controllare, perché il file che hai modificato potrebbe semplicemente non essere quello in uso.

Mi serve un mio account cloud per generare immagini in Windsurf?

No. I server MCP per immagini che girano in locale hanno bisogno di una chiave del provider a monte, con quote e fatturazione sul tuo account. Il server remoto esegue la generazione sul nostro pool di chiavi gestito, quindi la tua unica credenziale è la chiave bb_live_ del tuo profilo. I nuovi account partono con un saldo di benvenuto di $0.20, cioè sei immagini sul modello più economico prima di pagare qualsiasi cosa.

Cascade può generare video tramite lo stesso server?

Sì, con un passaggio di conferma obbligatorio. generate_video restituisce un preventivo alla prima chiamata e non addebita nulla; l'agente deve ripetere la chiamata con confirm_cost uguale a quell'importo prima che parta un render. I prezzi vanno da $0.10 per una clip Veo 3.1 Lite di quattro secondi a 720p senza audio fino a $4.40 per un render Veo 3.1 di fascia alta con audio, e Omni Flash costa $0.10 al secondo con l'audio sempre attivo. Le clip richiedono da uno a dieci minuti, quindi l'agente interroga get_result mentre continua a lavorare.

Perché il mio server MCP mostra un errore di autenticazione in Windsurf?

Nove volte su dieci è la credenziale, non la configurazione. Un ${env:BB_API_KEY} non impostato diventa una stringa vuota invece di generare un errore, quindi la richiesta parte con un bearer token vuoto e torna con un 401. Controlla che la variabile sia visibile al processo di Windsurf (gli avvii da interfaccia grafica non leggono il profilo della shell), oppure passa a ${file:~/.secrets/bb_key.txt} e il problema sparisce. Se la chiave è giusta ma i tool continuano a non comparire, verifica che l'URL finisca con /api/mcp e che un'allowlist del team non stia bloccando l'ID del server.