Налаштування MCP у Windsurf: генерація зображень у Cascade

MCP-сервер у Windsurf — це зовнішній набір інструментів, до якого агент звертається безпосередньо під час діалогу: ви оголошуєте його один раз у mcp_config.json, і Cascade отримує можливості, яких спочатку немає в базової моделі. Генерація зображень — найочевидніша прогалина. Windsurf залюбки побудує структуру екрана налаштувань, прив'яже роути та напише тести, але залишить три сірі прямокутники там, де мають бути ілюстрації.

Коротка інструкція для швидкого старту: створіть ключ у своєму профілі BananaBanana, після чого додайте до ~/.codeium/windsurf/mcp_config.json такий блок:

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

Експортуйте змінну BB_API_KEY=bb_live_ВАШ_КЛЮЧ, перезавантажте MCP-сервери — і в Cascade з'являться десять інструментів. Зображення коштують від $0.03 за одиницю з передплаченого балансу, відео — від $0.10, без підписок і без потреби налаштовувати власний хмарний проєкт. Перед вставкою врахуйте один нюанс: у свіжих збірках цей файл може вже не бути тим, який зчитує ваш агент. Подробиці нижче.

Навіщо додавати Cascade генератор зображень?

Тому що момент, коли вам знадобилося зображення, майже ніколи не є вдалим часом для виходу з редактора коду. Ви заглибилися на три рівні в логіку онбордингу, для порожнього стану потрібен арт, а альтернатива — це вкладка браузера, промпт, завантаження, перейменування, перетягування в public/ і довгий пошук місця, де ви зупинилися в коді.

Одна інструкція замінює весь цей маршрут. Cascade сам формулює промпт, викликає generate_image, зберігає файл у потрібну папку та прописує тег <img> з alt-текстом. Ви лише перевіряєте diff.

Є й другий аргумент, ще важливіший для цього клієнта. Cascade побудований для створення цілих фічей, а не поодиноких правок, тому потрібні йому ресурси надходять наборами: три порожні стани, шість прев'ю категорій, пак тимчасових аватарів. Створювати такі набори вручну у вкладках браузера вкрай незручно.

Альтернатива віддаленому серверу — локальний MCP-сервер зображень, що означає окремий процес Node або Python на вашій машині плюс власний ключ постачальника з квотами та білінгом на вашому акаунті. Віддалений сервер усуває обидві проблеми. Ендпоінт працює на нашому боці на тому ж пайплайні, що й веб-генератор, а єдині ваші облікові дані — це рядок bb_live_, який можна відкликати в будь-який момент на сторінці профілю.

Де Windsurf зберігає конфігурацію MCP зараз?

Ось момент, на якому багато хто плутається в серпні 2026 року, і його варто перевірити перед редагуванням файлів. Windsurf тепер став частиною Devin Desktop від Cognition: сайт windsurf.com перенаправляє на devin.ai/desktop, а старий URL docs.windsurf.com/windsurf/cascade/mcp видає 307-редирект на docs.devin.ai/desktop/cascade/mcp. На диску застосунок, як і раніше, називається Windsurf, схема діплінків залишається windsurf://, а папка налаштувань — ~/.codeium/windsurf/. Змінився лише брендинг.

Але змінилася структура агентів: тепер їх два, і кожен має власну систему конфігурації. У документації Cascade MCP про це прямо зазначено в попередженні вгорі сторінки: файл mcp_config.json застосовується до класичного агента Cascade, тоді як агент Devin Local (типовий для нових вкладок) читає конфігурацію Devin CLI. Перевірено 20 серпня 2026 року.

Тому обирайте файл відповідно до того, з яким агентом ви працюєте.

Класичний Cascade читає ~/.codeium/windsurf/mcp_config.json (або %USERPROFILE%\.codeium\windsurf\mcp_config.json у Windows). Віддалені сервери там налаштовуються через поле serverUrl або url плюс headers — це той самий фрагмент, наведений на початку статті.

Агент Devin Local читає файли конфігурації CLI: ~/.config/devin/mcp_config.json для рівня користувача, .devin/mcp_config.json для проєкту через git і .devin/mcp_config.local.json для персональних ключів (автоматично додається в .gitignore). Назви полів трохи відрізняються:

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

Можна обійтися й без ручного редагування файлів: команда devin mcp add bananabanana https://bananabanana.pro/api/mcp створить запис у локальній області, після чого залишиться додати блок headers. Команди devin mcp list та devin mcp get bananabanana покажуть, що саме завантажив CLI.

В обох випадках робочий ендпоінт — https://bananabanana.pro/api/mcp. Не /mcp (який є сторінкою документації для людей). POST-запит туди поверне HTML і збентежить агента. Наша сторінка MCP-сервера містить ці самі фрагменти та таблицю сумісності для всіх перевірених клієнтів:

Після підключення виклики list_models та get_account є безкоштовними — попросіть Cascade виконати один із них для швидкого тесту. get_account повертає баланс, назву ключа та денний ліміт, що дозволяє підтвердити автентифікацію без витрат на генерацію.

Практичний приклад: набір порожніх станів для щойно створеного застосунку

Реальний сценарій, на якому я створював ці демо. Cascade генерує структуру внутрішнього сервісу, три порожні стани з'являються як сірі блоки-заглушки. Замість запуску графічного редактора ви передаєте агенту формулу єдиного стилю та доручаєте згенерувати весь набір.

Формула стилю — ключ до результату. Порожні екрани працюють тільки як єдиний ансамбль: палітра кольорів, товщина ліній і кількість вільного простору мають зберігатися від зображення до зображення. Сформулюйте опис стилю один раз, накажіть агенту повторювати його дослівно в кожному запиті та змінюйте лише об'єкт:

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

Потім той самий опис стилю з іншим об'єктом для екрана «нічого не знайдено»:

Вони чудово поєднуються як пара для тимчасових заглушок. Якщо потрібна ще точніша відповідність, generate_image підтримує параметр seed — повторення однакового сіду з однаковим описом стилю зближує результати. Для персонажів або маскота, що мають зберігати вигляд на десятках зображень, техніка промптингу важливіша за налаштування клієнта, про що детально розповідає наше керівництво з консистентності персонажів.

Два чесних коментарі: я генерував ці приклади на Nano Banana Pro по $0.11, оскільки вони розміщені в цій статті й потребували чіткості. Для тимчасових макетів, які дизайнер замінить через два тижні, nano-banana-2-lite по $0.03 є найраціональнішим вибором, а наш гід по Lite-моделі показує, де її можливостей цілком достатньо. До того ж це типова модель для інструмента.

Відео генерується просто в цьому ж чаті. generate_video ніколи не списує кошти під час першого виклику: повертається розрахунок вартості, і агент зобов'язаний повторити запит із параметром confirm_cost, що дорівнює цій сумі, перш ніж розпочнеться рендер. 4 секунди відео 720p без звуку на Veo 3.1 Lite коштують від $0.10; Omni Flash тарифікується по $0.10 за секунду з постійним аудіо, тобто 3-секундний ролик коштуватиме $0.30.

Нюанси Windsurf, про які варто знати заздалегідь

П'ять практичних моментів, відзначених під час налаштування:

1. Невизначена змінна середовища завершується збоєм без помилки. У документації чітко зазначено: ${env:VAR_NAME} замінюється значенням змінної, а якщо вона не задана — стає порожнім рядком. Жодних попереджень чи повідомлень про помилку. Заголовок надсилається як Bearer , наш сервер відповідає 401, і з боку здається, що з ладу вийшов сервер, а не пропущено export. Застосунки, запущені через GUI, не читають профіль термінала, тому export у .zshrc непомітний, якщо Windsurf не відкрили з консолі. Якщо list_models повертає помилку автентифікації, перевірте змінну насамперед.

2. Конструкція ${file:…} надійніша і є фірмовою рисою Windsurf. Конфіг підтримує синтаксис ${file:/path/to/file}, підставляючи очищений вміст файлу, включно зі шляхами з тильдою ~. Завдяки цьому "Authorization": "Bearer ${file:~/.secrets/bb_key.txt}" працює без змінних середовища та знімає проблему запуску через GUI. У Windsurf я раджу саме її. У Cursor та VS Code такої можливості немає.

3. Cascade обмежений 100 інструментами. Це максимальний ліміт для всіх підключених MCP-серверів сумарно. У налаштуваннях кожного сервера можна вимикати непотрібні інструменти. Ми додаємо десять. Якщо у вас уже налаштовано кілька великих серверів, вимкніть те, чим не користуєтеся: generate_speech, edit_video та list_generations легко вимкнути, якщо вам потрібні тільки картинки.

4. Діплінк в один клік не передає ваш ключ заради безпеки. Windsurf підтримує посилання виду windsurf://windsurf-mcp-registry?serverName=<name>, які відкривають сторінку каталогу перед установкою. Зверніть увагу: вони не містять закодованої конфігурації, тому, на відміну від посилань із base64, немає ризику випадкового витоку ключів через спільні URL. Ми поки що не в публічному каталозі, тому використовуємо ручний JSON.

5. У командних тарифах ID сервера чутливий до регістру. Щойно адміністратор додає до списку дозволених хоча б один MCP-сервер, усі інші блокуються для всієї команди, а дозволений Server ID повинен із точністю до регістру збігатися з назвою ключа у вашому mcp_config.json. Якщо адмін схвалив bananabanana, а ви вказали BananaBanana, підключення не відбудеться, а повідомлення про помилку не пояснить причину.

Ще одне обмеження інтерфейсу: generate_speech повертає аудіо як посилання, а не як вбудований плеєр у Cascade, тому файл потрібно відкривати окремо. Зображення ж повертаються зі зручним прев'ю безпосередньо біля посилання.

Як щодо OAuth замість API-ключа?

Обидва шляхи доступні та стосуються різних агентів.

Devin CLI (тобто агент Devin Local) має повноцінну підтримку OAuth: команда devin mcp login <name> відкриває авторизацію в браузері, зберігає токени локально та оновлює їх автоматично завдяки динамічній реєстрації клієнтів (DCR). Наш сервер є повноцінним сервером авторизації OAuth 2.1 з DCR та індикаторами ресурсів RFC 8707.

Для цієї статті я тестував варіант з API-ключем (initialize, get_account, list_models зі справжнім ключем bb_live_). Якщо ви тестуєте OAuth і виникають труднощі, ключовий параметр — oauthResource, який перевизначає параметр resource за RFC 8707, оскільки наш ендпоінт очікує аудиторію https://bananabanana.pro/api/mcp.

Є й практична причина віддати перевагу ключу: вони безкоштовні, їх можна створити кілька з власним журналом використання (інструмент, модель, вартість, прев'ю промпту) та опціональним денним лімітом у USD у розділі Профіль → API-ключі MCP. Такий ліміт — чудовий захист перед наданням автономному агенту доступу до витрат.

Щодо дозволів: конфігурація Devin CLI підтримує правила для окремих інструментів за допомогою селекторів mcp__<server>__<tool>, що ідеально підходить для платних серверів:

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

Безкоштовні запити виконуватимуться без зупинок, а операції рендеру запитають підтвердження.

Скільки коштували медіафайли для цієї статті?

Стандартні ціни за генерацію, точно ті самі значення, які list_models повертає агенту:

Обидва порожні стани вдалися з першої спроби. Для фотореалістичних зображень продуктів варто закладати невеликий запас на повторні генерації.

Якщо ви вже використовуєте цей сервер в іншому редакторі, конфігурація Windsurf вище — єдина відмінність: ключ, баланс та історія генерацій залишаються спільними. Наші гайди для Cursor та VS Code описують налаштування для цих редакторів. Готові спробувати? Створіть ключ та доручіть Cascade згенерувати перше зображення.

FAQ

Чи підтримує Windsurf віддалені MCP-сервери із заголовком Authorization?

Так. Віддалені HTTP-сервери в mcp_config.json приймають поле serverUrl (або url) і опціональний об'єкт headers. Cascade підтримує транспорти stdio, Streamable HTTP та SSE. В обох полях працює підстановка ${env:VAR} та ${file:/path}, що запобігає зберіганню ключа у відкритому вигляді. Конфігурацію перевірено за офіційною документацією 20 серпня 2026 року.

Який файл конфігурації насправді читає мій агент у Windsurf?

Це залежить від агента. Класичний агент Cascade читає ~/.codeium/windsurf/mcp_config.json. Агент Devin Local (типовий для нових вкладок) читає файли Devin CLI: ~/.config/devin/mcp_config.json, .devin/mcp_config.json або .devin/mcp_config.local.json для особистих ключів. Якщо сервер не з'являється після редагування, перевірте саме цей розподіл.

Чи потрібен власний хмарний акаунт для генерації зображень у Windsurf?

Ні. Локальним серверам потрібні ключі сторонніх провайдерів з власними лімітами та рахунками. Віддалений сервер виконує генерацію через нашу керовану інфраструктуру, тому вам потрібен лише ключ bb_live_ з вашого профілю. Нові користувачі отримують $0.20 вітального балансу, чого вистачає на 6 зображень на базовій моделі без поповнення рахунку.

Чи може Cascade генерувати відео через цей самий сервер?

Так, з обов'язковим етапом підтвердження. generate_video під час першого виклику надає розрахунок вартості й нічого не списує; агент повинен повторити виклик із параметром confirm_cost, що відповідає цій сумі, щоб розпочати рендер. Ціни стартують від $0.10 за 4-секундний беззвучний ролик 720p на Veo 3.1 Lite до $4.40 за максимальну якість Veo 3.1 зі звуком; Omni Flash коштує $0.10 за секунду з постійним аудіо. Рендер триває від 1 до 10 хвилин, протягом яких агент періодично опитує get_result.

Чому MCP-сервер показує помилку автентифікації у Windsurf?

У дев'яти випадках із десяти річ у ключі, а не в конфігурації. Невизначена змінна ${env:BB_API_KEY} підставляється як порожній рядок без повідомлення про помилку, надсилаючи порожній bearer-токен і повертаючи 401. Перевірте, чи доступна змінна процесу Windsurf (запуск через GUI не зчитує профіль термінала), або скористайтеся ${file:~/.secrets/bb_key.txt}. Якщо ключ вказано правильно, перевірте, щоб URL закінчувався на /api/mcp і список дозволів команди не блокував Server ID.