Configuration MCP dans Windsurf : Générer des images avec Cascade

Un serveur MCP dans Windsurf est une boîte à outils externe que l'agent peut solliciter en pleine conversation : vous le déclarez une fois dans mcp_config.json, et Cascade acquiert des capacités absentes du modèle de base. La génération d'images est le manque le plus flagrant. Windsurf structurera volontiers un écran de paramètres, reliera les routes et rédigera les tests, pour finalement vous laisser trois rectangles gris là où les illustrations devraient se trouver.

En résumé, si vous cherchez juste la méthode rapide : créez une clé dans votre profil BananaBanana, puis ajoutez ce bloc à ~/.codeium/windsurf/mcp_config.json :

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

Exportez BB_API_KEY=bb_live_VOTRE_CLE, rechargez les serveurs MCP, et dix outils apparaîtront dans Cascade. Les images sont facturées dès $0.03 l'unité sur un solde prépayé, la vidéo dès $0.10, sans abonnement et sans avoir à déployer votre propre projet cloud. Une mise en garde avant de copier-coller : sur les versions récentes, ce fichier n'est peut-être plus celui que lit votre agent. Nous y reviendrons dans un instant.

Pourquoi doter Cascade d'un générateur d'images ?

Parce que le moment où vous avez besoin d'une image n'est presque jamais le bon moment pour quitter l'éditeur de code. Vous êtes plongé à trois niveaux dans un flux d'onboarding, l'état vide nécessite un visuel, et l'alternative consiste à ouvrir un onglet de navigateur, saisir un prompt, télécharger, renommer, glisser le fichier dans public/, puis retrouver où vous en étiez dans votre code.

Une seule instruction remplace tout ce détour. Cascade rédige le prompt, appelle generate_image, place le fichier dans le bon dossier et écrit la balise <img> avec son texte alternatif. Vous n'avez plus qu'à vérifier le diff.

Un second argument pèse encore plus lourd pour ce client précis. Cascade est conçu pour construire des fonctionnalités entières et non des retouches isolées ; les ressources graphiques dont il a besoin arrivent donc par lots : trois états vides, six vignettes de catégories, un pack d'avatars temporaires. Créer ces séries à la main dans des onglets de navigateur fait rapidement perdre tout fil conducteur.

L'alternative à un serveur distant consiste à exécuter un serveur MCP d'images en local, ce qui implique un processus Node ou Python sur votre machine ainsi que votre propre clé de fournisseur en amont, avec quotas et facturation sur votre compte personnel. Un serveur distant évite ces deux contraintes. Le point de terminaison fonctionne de notre côté sur le même pipeline que le générateur web, et votre seul identifiant est une chaîne bb_live_ révocable à tout moment depuis la page profil.

Où Windsurf stocke-t-il la configuration MCP aujourd'hui ?

Voici le point qui égare beaucoup d'utilisateurs en août 2026, et il est essentiel de le vérifier avant toute modification. Windsurf fait désormais partie de Devin Desktop de Cognition : le site windsurf.com redirige vers devin.ai/desktop, et l'ancienne URL docs.windsurf.com/windsurf/cascade/mcp effectue une redirection 307 vers docs.devin.ai/desktop/cascade/mcp. Sur le disque, l'application s'appelle toujours Windsurf, le schéma de liens reste windsurf:// et le dossier de configuration demeure ~/.codeium/windsurf/. Seul le branding a évolué.

Ce qui a changé en revanche, c'est la présence de deux agents dotés de deux systèmes de configuration distincts. La documentation Cascade MCP le précise d'ailleurs dans un avertissement en haut de page : le fichier mcp_config.json s'applique à l'agent classique Cascade, tandis que l'agent Devin Local (par défaut pour les nouveaux onglets) lit la configuration de la CLI Devin. Vérifié le 20 août 2026.

Choisissez donc le fichier selon l'agent avec lequel vous interagissez réellement.

Cascade classique lit ~/.codeium/windsurf/mcp_config.json (ou %USERPROFILE%\.codeium\windsurf\mcp_config.json sous Windows). Les serveurs distants y acceptent un champ serverUrl ou url ainsi que headers, correspondant à l'extrait présenté au début de cet article.

L'agent Devin Local lit les fichiers de configuration de la CLI : ~/.config/devin/mcp_config.json au niveau utilisateur, .devin/mcp_config.json pour un projet partagé via git, et .devin/mcp_config.local.json pour les valeurs personnelles (automatiquement ignoré par git). Les noms de champs diffèrent légèrement :

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

Vous pouvez aussi vous passer de l'éditeur : devin mcp add bananabanana https://bananabanana.pro/api/mcp crée l'entrée dans le scope local, après quoi il suffit d'ajouter le bloc headers. Les commandes devin mcp list et devin mcp get bananabanana vous indiqueront exactement ce que la CLI a chargé.

Dans les deux cas, le point de terminaison est https://bananabanana.pro/api/mcp. Pas /mcp, qui est la page de documentation destinée aux humains. Une requête POST à cette adresse renvoie du HTML et désoriente l'agent. Notre page de documentation du serveur MCP propose ces mêmes extraits ainsi qu'un tableau de compatibilité pour tous les clients vérifiés :

Une fois la connexion établie, les appels à list_models et get_account sont gratuits : demandez à Cascade d'en exécuter un pour vérifier le bon fonctionnement. get_account renvoie votre solde, le nom de la clé et son plafond journalier, ce qui permet de valider l'authentification sans dépenser pour une génération.

Cas d'usage : un ensemble d'états vides pour l'application que Cascade vient de créer

Voici le scénario réel sur lequel reposent ces démonstrations. Cascade génère la structure d'un outil interne, les trois états vides apparaissent sous forme de blocs gris temporaires. Plutôt que d'ouvrir un logiciel de graphisme, vous donnez à l'agent une consigne de style pour générer l'ensemble de la série.

La consigne de style fait toute la différence. Les états vides ne fonctionnent que s'ils forment un ensemble cohérent : la palette de couleurs, l'épaisseur du trait et la proportion d'espace négatif doivent se maintenir d'une image à l'autre. Rédigez la formule une seule fois, demandez à l'agent de la réutiliser textuellement à chaque appel et ne faites varier que le sujet :

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

Puis la même formule avec un sujet adapté pour l'écran « aucun résultat » :

Ces visuels s'associent parfaitement, ce qui est idéal pour des maquettes. Pour une cohérence encore plus stricte, generate_image accepte un paramètre seed ; répéter la même graine avec la même consigne de style rapproche encore les résultats. Pour des personnages ou une mascotte devant rester identiques sur une douzaine d'images, la technique de prompt compte davantage que le client, et notre guide sur la cohérence des personnages détaille cette approche.

Deux remarques transparentes. J'ai généré ces exemples avec Nano Banana Pro à $0.11 car ils figurent dans cet article et nécessitaient une grande netteté. Pour des placeholders qu'un designer remplacera dans deux semaines, nano-banana-2-lite à $0.03 est le choix le plus judicieux, et notre guide sur le modèle Lite montre où ce modèle économique suffit amplement. C'est d'ailleurs le modèle par défaut de l'outil, vers lequel l'agent s'orientera automatiquement si vous ne précisez rien d'autre.

La vidéo fonctionne depuis le même fil de discussion. generate_video ne facture jamais lors du premier appel : il renvoie une estimation de coût et l'agent doit renouveler la requête avec confirm_cost défini sur ce montant exact pour lancer le rendu. Une vidéo muette de 4 secondes en 720p sur Veo 3.1 Lite démarre à $0.10 ; Omni Flash est facturé $0.10 par seconde avec l'audio toujours actif, soit $0.30 pour une prise de 3 secondes.

Particularités de Windsurf à connaître avant de se lancer

Cinq observations pratiques issues de la configuration.

1. Une variable d'environnement non définie échoue silencieusement. La documentation est formelle : ${env:NOM_VARIABLE} est remplacée par la valeur de la variable, et si celle-ci n'est pas définie, elle devient une chaîne vide. Sans erreur ni avertissement. L'en-tête est envoyé sous la forme Bearer , notre serveur répond 401, et tout semble indiquer une panne du serveur plutôt qu'un export manquant. Les applications lancées via l'interface graphique ne lisent pas le profil du terminal, de sorte qu'un export dans .zshrc est invisible si Windsurf n'a pas été lancé depuis la console. Si list_models renvoie une erreur d'authentification, vérifiez la variable avant tout.

2. La syntaxe ${file:…} est plus robuste et spécifique à Windsurf. La configuration prend en charge ${file:/chemin/vers/fichier}, remplacé par le contenu épuré du fichier, y compris avec le tilde ~. Ainsi, "Authorization": "Bearer ${file:~/.secrets/bb_key.txt}" fonctionne sans aucune variable d'environnement et élimine le problème du lancement par l'interface graphique. C'est l'option que je recommande dans Windsurf. Cursor et VS Code ne la proposent pas.

3. Cascade plafonne à 100 outils. Il s'agit d'une limite stricte sur l'ensemble de vos serveurs MCP connectés. Dans les réglages de chaque serveur, vous pouvez désactiver des outils individuels. Nous en ajoutons dix. Si vous utilisez déjà plusieurs serveurs volumineux (celui de GitHub en compte des dizaines), désactivez ce dont vous n'avez pas besoin : generate_speech, edit_video et list_generations se retirent facilement si vous ne cherchez que des images.

4. Le lien direct en un clic ne transmet pas votre clé, ce qui renforce la sécurité. Windsurf prend en charge les liens du type windsurf://windsurf-mcp-registry?serverName=<name> qui ouvrent une page du registre pour examen avant installation. Remarquez ce qui manque : aucune configuration encodée en base64 n'est injectée dans l'URL, évitant toute fuite d'identifiants dans un lien partagé. Notre serveur n'étant pas dans le registre public, la configuration s'effectue manuellement via JSON.

5. Sur les forfaits d'équipe, l'identifiant du serveur est sensible à la casse. Dès qu'un administrateur place un serveur MCP en liste blanche, tous les serveurs non approuvés sont bloqués pour l'équipe, et le Server ID autorisé doit correspondre au caractère près au nom de la clé dans votre mcp_config.json. Si l'admin a validé bananabanana et que votre fichier indique BananaBanana, la connexion échouera sans message d'erreur explicite. Les équipes Enterprise peuvent également pointer Windsurf vers leur propre registre MCP plutôt que sur le catalogue par défaut.

Une remarque sur l'expérience utilisateur : generate_speech renvoie l'audio sous forme d'URL et non via un lecteur intégré dans Cascade, ce qui nécessite d'ouvrir le fichier séparément. Les images, en revanche, s'affichent avec un aperçu directement à côté du lien, ce qui est bien plus pratique.

Qu'en est-il d'OAuth plutôt que d'une clé API ?

Les deux approches existent et s'adressent à des agents différents.

La CLI Devin (et donc l'agent Devin Local) intègre un véritable support OAuth : la commande devin mcp login <name> ouvre le flux dans le navigateur, enregistre les jetons localement et les actualise automatiquement grâce à l'enregistrement dynamique de clients (DCR) sans configuration préalable. Notre serveur est un serveur d'autorisation OAuth 2.1 avec DCR et indicateurs de ressources RFC 8707. La documentation de Cascade confirme également la prise en charge d'OAuth pour chaque type de transport.

Pour cet article, j'ai privilégié le chemin par clé d'API (initialize, get_account, list_models avec une vraie clé bb_live_). Si vous testez OAuth et rencontrez des difficultés, l'option à surveiller est oauthResource, qui remplace le paramètre resource de la RFC 8707, notre point de terminaison attendant l'audience https://bananabanana.pro/api/mcp.

Il existe aussi une raison pratique de préférer la clé : elles sont gratuites et vous pouvez en créer plusieurs, chacune disposant de son historique d'utilisation (outil, modèle, coût, aperçu du prompt) et d'un plafond quotidien facultatif en USD dans Profil → Clés API MCP. Ce plafond est la précaution idéale avant de donner à un agent autonome accès à des outils payants.

Côté autorisations : la configuration de Devin CLI gère des règles par outil avec les sélecteurs mcp__<serveur>__<outil>, ce qui s'avère particulièrement utile pour un serveur payant.

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

Les requêtes gratuites s'exécutent sans interruption, et toute opération de rendu demande une confirmation explicite.

Combien ont coûté les médias de démonstration de cet article ?

Tarifs standard par génération, identiques à ceux retournés par list_models à l'agent :

Les deux états vides ont abouti dès le premier essai, en partie grâce à la souplesse du style vectoriel. Pour des rendus fotoréalistes de produits, prévoyez quelques essais supplémentaires.

Si vous utilisez déjà ce serveur dans un autre éditeur, la configuration Windsurf présentée ci-dessus est la seule nouveauté : même clé, même solde et même historique de génération. Nos guides pour Cursor et VS Code abordent le même serveur dans ces environnements. Prêt à démarrer ? Créez une clé et demandez à Cascade votre premier visuel.

FAQ

Windsurf prend-il en charge les serveurs MCP distants avec en-tête d'autorisation ?

Oui. Les serveurs HTTP distants dans mcp_config.json acceptent un champ serverUrl (ou url) et un objet headers facultatif. Cascade supporte les transports stdio, Streamable HTTP et SSE. serverUrl et headers acceptent l'interpolation avec ${env:VAR} et ${file:/chemin}, évitant de stocker la clé en clair. Configuration vérifiée d'après la documentation officielle le 20 août 2026.

Quel fichier de configuration mon agent Windsurf lit-il exactement ?

Cela dépend de l'agent. L'agent classique Cascade lit ~/.codeium/windsurf/mcp_config.json. L'agent Devin Local (par défaut sur les nouveaux onglets) lit les fichiers de la CLI Devin : ~/.config/devin/mcp_config.json, .devin/mcp_config.json ou .devin/mcp_config.local.json pour les clés personnelles. Si votre serveur n'apparaît pas après modification, vérifiez cette distinction en priorité.

Ai-je besoin d'un compte cloud personnel pour générer des images dans Windsurf ?

Non. Les serveurs MCP d'images locaux nécessitent des clés de fournisseur avec quotas et facturation sur votre compte. Le serveur distant exécute les générations sur notre infrastructure gérée, vous n'avez donc besoin que de la clé bb_live_ issue de votre profil. Les nouveaux comptes reçoivent un crédit initial de $0.20, permettant de créer six images sur le modèle économique sans débourser un centime.

Cascade peut-il générer des vidéos via le même serveur ?

Oui, avec une étape de confirmation obligatoire. generate_video fournit un devis lors du premier appel sans rien facturer ; l'agent doit renouveler l'appel avec le paramètre confirm_cost défini sur ce montant pour démarrer le rendu. Les prix s'échelonnent de $0.10 pour un clip muet de 4 secondes en 720p sur Veo 3.1 Lite jusqu'à $4.40 pour un rendu haute qualité Veo 3.1 avec audio ; Omni Flash est facturé $0.10 par seconde avec audio systématique. Le rendu prend entre une et dix minutes, pendant lesquelles l'agent consulte régulièrement get_result.

Pourquoi mon serveur MCP affiche-t-il une erreur d'authentification dans Windsurf ?

Dans neuf cas sur dix, le problème vient de l'identifiant et non de la configuration. Une variable ${env:BB_API_KEY} non définie est remplacée par une chaîne vide sans générer d'erreur explicite, envoyant un jeton bearer vide qui déclenche une erreur 401. Assurez-vous que la variable est accessible par le processus Windsurf (le lancement par l'interface graphique ne charge pas le profil du shell) ou utilisez ${file:~/.secrets/bb_key.txt}. Si la clé est valide et que les outils n'apparaissent toujours pas, vérifiez que l'URL se termine par /api/mcp et qu'aucune règle d'équipe ne bloque l'identifiant du serveur.