Configuración MCP en Windsurf: Generar imágenes en Cascade

Un servidor MCP en Windsurf es una caja de herramientas externa a la que el agente puede recurrir en mitad de una conversación: lo declaras una vez en mcp_config.json y Cascade adquiere capacidades con las que el modelo base no viene equipado. La generación de imágenes es la carencia más evidente. Windsurf estructurará con gusto una pantalla de ajustes, conectará las rutas y escribirá los tests, para luego dejarte tres rectángulos grises donde deberían ir las ilustraciones.

Versión resumida, por si solo venías a por esto: crea una clave en tu perfil de BananaBanana y añade esto a ~/.codeium/windsurf/mcp_config.json:

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

Exporta BB_API_KEY=bb_live_TU_CLAVE, recarga los servidores MCP y aparecerán diez herramientas en Cascade. Las imágenes se cobran desde $0.03 por unidad sobre un saldo prepagado, el vídeo desde $0.10, sin suscripciones ni necesidad de configurar tu propio proyecto cloud. Una advertencia antes de pegar: si estás en una versión reciente, puede que ese archivo ya no sea el que lee tu agente. Más sobre esto en un momento.

¿Por qué darle a Cascade un generador de imágenes?

Porque el momento en que necesitas una imagen casi nunca es un buen momento para salir del editor. Estás a tres niveles de profundidad en un flujo de onboarding, el estado vacío necesita diseño gráfico, y la alternativa es abrir una pestaña del navegador, escribir un prompt, descargar, renombrar, arrastrar a public/ y luego buscar dónde te habías quedado.

Una sola instrucción sustituye todo ese rodeo. Cascade escribe el prompt, llama a generate_image, coloca el archivo en la carpeta correcta y escribe la etiqueta <img> con su texto alt. Tú solo revisas un diff.

Hay un segundo argumento aún más relevante para este cliente en particular. Cascade está diseñado para construir funcionalidades completas, no para ediciones aisladas, por lo que los recursos que necesita suelen venir en grupos: tres estados vacíos, seis miniaturas de categorías, un paquete de avatares provisionales. Crear conjuntos a mano en pestañas del navegador es donde el flujo de trabajo se vuelve realmente pesado.

La alternativa a un servidor remoto es ejecutar un servidor MCP local de imágenes, lo que implica un proceso Node o Python en tu máquina más tu propia clave de proveedor upstream, con cuotas y facturación en tu cuenta. Un servidor remoto evita ambos problemas. El endpoint ya se ejecuta en nuestra infraestructura, sobre el mismo pipeline que el generador web, y tu única credencial es una cadena bb_live_ que puedes revocar en cualquier momento desde el perfil.

¿Dónde guarda Windsurf la configuración MCP ahora?

Aquí está el punto que confunde a muchos en agosto de 2026, y conviene comprobarlo antes de editar nada. Windsurf ahora forma parte de Devin Desktop de Cognition: windsurf.com redirige a devin.ai/desktop, y la antigua URL docs.windsurf.com/windsurf/cascade/mcp hace un 307 a docs.devin.ai/desktop/cascade/mcp. La app sigue llamándose Windsurf en disco, el esquema de enlaces sigue siendo windsurf:// y la carpeta de configuración sigue siendo ~/.codeium/windsurf/. Solo cambió la marca.

Lo que sí cambió es que ahora hay dos agentes con dos sistemas de configuración distintos, y la documentación de Cascade MCP lo advierte en un recuadro superior: el archivo mcp_config.json aplica al agente clásico Cascade, mientras que el agente Devin Local, que es el predeterminado para nuevas pestañas, lee la configuración de Devin CLI. Comprobado el 20 de agosto de 2026.

Por lo tanto, elige el archivo según el agente con el que estés interactuando.

Cascade clásico lee ~/.codeium/windsurf/mcp_config.json (%USERPROFILE%\.codeium\windsurf\mcp_config.json en Windows). Los servidores remotos allí aceptan un campo serverUrl o url más headers, que es el fragmento del inicio de este artículo.

El agente Devin Local lee los archivos de configuración de la CLI: ~/.config/devin/mcp_config.json para el ámbito de usuario, .devin/mcp_config.json para proyectos compartidos en git, y .devin/mcp_config.local.json para valores personales (ignorado automáticamente en git). Los nombres de los campos varían ligeramente:

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

O sáltate el editor: devin mcp add bananabanana https://bananabanana.pro/api/mcp crea la entrada en el ámbito local y luego añades el bloque headers. Comandos como devin mcp list y devin mcp get bananabanana te muestran exactamente qué ha cargado la CLI.

En ambos casos, el endpoint es https://bananabanana.pro/api/mcp. No /mcp, que es la página de documentación para humanos. Un POST allí devuelve HTML y confunde por completo al agente. Nuestra página de documentación MCP incluye estos mismos fragmentos y una tabla de compatibilidad para todos los clientes verificados:

Una vez conectado, list_models y get_account son llamadas gratuitas, así que pide a Cascade que ejecute una de ellas como prueba inicial. get_account devuelve tu saldo, el nombre de la clave y su límite diario, lo que permite verificar la autenticación sin gastar en una generación.

Caso de uso: conjunto de estados vacíos para la app que Cascade acaba de crear

El escenario sobre el que preparé estas demos. Cascade construye la estructura de una herramienta interna, los tres estados vacíos quedan como divs grises provisionales, y en lugar de abrir una herramienta de diseño le das al agente una frase de estilo para que genere todo el paquete.

La frase de estilo es la clave de todo. Los estados vacíos solo funcionan como conjunto: la paleta, el grosor de línea y el espacio negativo deben mantenerse de una imagen a otra. Escribe la cláusula una vez, indícale al agente que la reutilice textualmente en cada llamada y varía solo el sujeto:

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

Luego, la misma frase con un sujeto diferente para la pantalla de «sin resultados»:

Combinan a la perfección como pareja, que es el objetivo para recursos provisionales. Si necesitas un ajuste aún más estricto, generate_image acepta un parámetro seed, y repetir el seed con la misma cláusula de estilo acerca más los resultados. Para personajes o mascotas que deban mantenerse a lo largo de muchas imágenes, la técnica de prompting importa más que el cliente, como explicamos en la guía de consistencia de personajes.

Dos notas honestas. Generé estos ejemplos con Nano Banana Pro a $0.11 porque se publican en esta página y quería el máximo detalle. Para marcadores de posición que un diseñador reemplazará en dos semanas, nano-banana-2-lite a $0.03 es la elección sensata, y nuestra guía de Lite detalla dónde este modelo económico rinde de sobra. Además, es el modelo predeterminado de la herramienta, por lo que el agente lo elegirá automáticamente a menos que especifiques lo contrario.

El vídeo también funciona desde el mismo chat. generate_video nunca cobra en la primera llamada: devuelve un presupuesto y el agente debe repetir la llamada con confirm_cost fijado exactamente en esa cifra antes de que comience el renderizado. Veo 3.1 Lite mudo en 720p durante 4 segundos parte de $0.10; Omni Flash cobra $0.10 por segundo con audio siempre activo, por lo que una toma de 3 segundos cuesta $0.30.

Particularidades de Windsurf a tener en cuenta

Cinco aspectos que destacaría a un compañero, recopilados durante la configuración.

1. Una variable de entorno no definida falla en silencio. La documentación es clara: ${env:NOMBRE_VARIABLE} se reemplaza por el valor de la variable, y si no está definida, se convierte en una cadena vacía. Sin errores ni avisos. El encabezado se envía como un Bearer vacío, nuestro servidor responde 401 y parece un error del servidor en lugar de una variable faltante. Las aplicaciones iniciadas desde la interfaz gráfica no leen el perfil del shell, por lo que un export en .zshrc es invisible a menos que abras Windsurf desde la terminal. Si list_models devuelve error de autenticación, revisa la variable antes que cualquier otra cosa.

2. ${file:…} es una mejor alternativa y es exclusiva de Windsurf. La misma configuración admite ${file:/ruta/al/archivo}, sustituyéndolo por el contenido del archivo sin espacios, soportando rutas con tilde ~. De este modo, "Authorization": "Bearer ${file:~/.secrets/bb_key.txt}" funciona sin variables de entorno y evita por completo el problema del inicio vía GUI. Prefiero esto a ${env:…} en Windsurf. Ni Cursor ni VS Code lo ofrecen.

3. Cascade tiene un tope de 100 herramientas. Es un límite estricto para la suma de todos tus servidores MCP conectados. En la página de ajustes de cada servidor puedes desactivar herramientas individuales. Nosotros añadimos diez. Si ya usas servidores grandes (el de GitHub contiene decenas), desactiva lo que no uses: generate_speech, edit_video y list_generations son fáciles de descartar si solo buscas imágenes.

4. El enlace directo en un clic no transmite tu clave, lo cual es una ventaja de seguridad. Windsurf admite enlaces del tipo windsurf://windsurf-mcp-registry?serverName=<name> que abren una página del catálogo antes de instalar. Fíjate en el detalle: no contiene configuración codificada, por lo que, a diferencia de instaladores que usan bloques enteros en base64, nada aquí puede filtrar credenciales en una URL compartida. Aún no estamos en el catálogo oficial, así que la configuración es mediante JSON manual.

5. En planes de equipo, el ID del servidor es determinante. En cuanto un administrador añade un servidor MCP a la lista de permitidos, cualquier servidor no incluido queda bloqueado para todo el equipo, y el Server ID autorizado debe coincidir exactamente en mayúsculas y minúsculas con el nombre de la clave en tu mcp_config.json. Es decir: si el admin autorizó bananabanana y tu archivo pone BananaBanana, no conectará y el error no explicará el motivo. Los equipos Enterprise también pueden apuntar Windsurf a su propio registro MCP en lugar del marketplace predeterminado.

Una limitación de producto sobre asperezas actuales: generate_speech devuelve el audio como URL en vez de un reproductor que Cascade pueda emitir en línea, por lo que tendrás que abrir el archivo tú mismo. Las imágenes, en cambio, devuelven una vista previa en línea junto al enlace, lo cual resulta mucho más práctico.

¿Qué hay de OAuth en lugar de una API key?

Ambas vías existen y corresponden a agentes diferentes.

Devin CLI (el agente Local) cuenta con soporte real para OAuth: devin mcp login <name> abre el flujo en el navegador, almacena los tokens localmente y los renueva de forma automática mediante registro dinámico de clientes (DCR) sin registros previos. Nuestro servidor es un servidor de autorización OAuth 2.1 con DCR e indicadores de recursos RFC 8707. La documentación de Cascade también indica compatibilidad con OAuth para cada tipo de transporte.

Para este artículo utilicé el método con clave de API (initialize, get_account, list_models con una clave real bb_live_). Si pruebas OAuth y encuentras problemas, el parámetro de ajuste es oauthResource, que sobrescribe el parámetro resource de RFC 8707, ya que nuestro endpoint espera como audiencia https://bananabanana.pro/api/mcp.

Existe además una razón práctica para preferir la clave: son gratuitas y puedes tener varias, cada una con su propio registro de uso (herramienta, modelo, coste, vista previa de prompt) y un límite diario opcional en USD en Perfil → Claves API MCP. Ese límite es justo lo que conviene configurar antes de dar acceso de gasto a un agente autónomo.

En cuanto a permisos: la configuración de Devin CLI admite reglas por herramienta con selectores mcp__<servidor>__<herramienta>, lo cual encaja muy bien con un servidor de pago.

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

Las consultas gratuitas se ejecutan sin interrumpirte y cualquier operación de renderizado solicitará confirmación.

¿Cuánto costaron los recursos multimedia de este artículo?

Precios estándar por generación, exactamente las cifras que list_models reporta al agente:

Ambos estados vacíos se lograron al primer intento, en parte por suerte y en parte porque el vector plano es muy permisivo. Para tomas fotorrealistas de producto conviene presupuestar un par de intentos adicionales.

Si ya utilizas este servidor en otro editor, la configuración de Windsurf es la única novedad: misma clave, mismo saldo y mismo historial de generación. Las guías para Cursor y VS Code cubren el mismo servidor en esos clientes. ¿Listo para probarlo? Crea una clave y pide a Cascade tu primera imagen.

FAQ

¿Admite Windsurf servidores MCP remotos con encabezado de autorización?

Sí. Los servidores HTTP remotos en mcp_config.json admiten un campo serverUrl (o url) y un objeto opcional headers. Cascade es compatible con transportes stdio, Streamable HTTP y SSE. Tanto serverUrl como headers admiten interpolación con ${env:VAR} y ${file:/ruta}, evitando guardar la clave en texto plano. Configuración comprobada con la documentación oficial el 20 de agosto de 2026.

¿Qué archivo de configuración lee realmente mi agente en Windsurf?

Depende del agente. El agente clásico Cascade lee ~/.codeium/windsurf/mcp_config.json. El agente Devin Local (predeterminado en nuevas pestañas) lee los archivos de Devin CLI: ~/.config/devin/mcp_config.json, .devin/mcp_config.json o .devin/mcp_config.local.json para claves personales. Si el servidor no aparece tras editar la configuración, comprueba esta diferencia.

¿Necesito una cuenta en la nube propia para generar imágenes en Windsurf?

No. Los servidores MCP de imágenes locales requieren claves de un proveedor externo con cuotas y facturación en tu cuenta. El servidor remoto procesa las generaciones en nuestro grupo de claves gestionado, por lo que solo necesitas la clave bb_live_ de tu perfil. Las cuentas nuevas reciben $0.20 de saldo inicial, suficiente para seis imágenes en el modelo económico sin pagar nada.

¿Puede Cascade generar vídeo a través del mismo servidor?

Sí, mediante un paso obligatorio de confirmación. generate_video devuelve una cotización en la primera llamada sin realizar ningún cobro; el agente debe repetir la llamada con confirm_cost igual a ese importe para iniciar el renderizado. Los precios van desde $0.10 por un clip mudo de 4 segundos en 720p con Veo 3.1 Lite hasta $4.40 para renderizados de máxima calidad en Veo 3.1 con audio; Omni Flash cobra $0.10 por segundo con sonido siempre activo. Los clips tardan entre uno y diez minutos, durante los cuales el agente sondea get_result.

¿Por qué mi servidor MCP muestra un error de autenticación en Windsurf?

Nueve de cada diez veces se debe a la credencial y no a la configuración. Una variable ${env:BB_API_KEY} no configurada se resuelve como una cadena vacía en lugar de generar un error, enviando un token bearer vacío y recibiendo un 401. Comprueba que la variable esté accesible para el proceso de Windsurf (los lanzamientos GUI no leen el perfil del shell) o recurre a ${file:~/.secrets/bb_key.txt}. Si la clave es correcta y las herramientas siguen sin aparecer, verifica que la URL termine en /api/mcp y que una lista de permitidos de equipo no esté bloqueando el ID del servidor.