Настройка 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:ИМЯ_ПЕРЕМЕННОЙ} заменяется на значение переменной, а если она не задана — превращается в пустую строку. Без ошибок и без предупреждений. Заголовок отправляется как Bearer , наш сервер отвечает 401, и со стороны кажется, что сломался сервер, а не пропущен экспорт. Приложения, запущенные через графический интерфейс, не читают профиль шелла, поэтому экспорт в .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-серверы суммарно. В настройках каждого сервера можно отключать ненужные функции. Мы добавляем десять. Если у вас уже подключено несколько крупных серверов (у одного GitHub их десятки), отключите то, чем не пользуетесь: 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, подключение не состоится, и сообщение об ошибке не объяснит причину. Enterprise-команды также могут перенаправить Windsurf на собственный реестр MCP вместо дефолтного каталога.

Еще одно ограничение интерфейса: generate_speech возвращает аудио в виде ссылки, а не встроенного плеера, поэтому файл придется открывать отдельно. Изображения же выводятся с компактным превью прямо рядом со ссылкой, что гораздо удобнее.

Что насчет OAuth вместо API-ключа?

Оба способа доступны, и они относятся к разным агентам.

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

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

Есть и практическая причина предпочесть ключ. Ключи бесплатны, их можно создать несколько, для каждого доступен журнал вызовов (инструмент, модель, стоимость, превью промпта) и опциональный дневной лимит в USD в разделе Профиль → API-ключи MCP. Такой лимит стоит настроить в первую очередь, прежде чем давать автономному агенту доступ к расходу средств.

Что касается прав доступа: конфигурация Devin CLI позволяет задавать правила для конкретных инструментов через селекторы mcp__<сервер>__<инструмент>, что очень удобно для платных сервисов.

{
  "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. В serverUrl и headers работает подстановка ${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?

Нет. Локальным MCP-серверам нужен ключ внешнего провайдера с квотами и биллингом на вашей стороне. Удаленный сервер выполняет генерацию через наш пул ключей, поэтому нужен только ключ bb_live_ из вашего профиля. Новые пользователи получают стартовые $0.20 на баланс, чего хватает на шесть картинок на базовой модели без пополнения счета.

Может ли Cascade генерировать видео через этот же сервер?

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

Почему MCP-сервер показывает ошибку авторизации в Windsurf?

В девяти случаях из десяти дело в ключе, а не в конфиге. Неустановленная переменная ${env:BB_API_KEY} подставляется как пустая строка без выброса ошибки, запрос уходит с пустым bearer-токеном и получает ответ 401. Убедитесь, что переменная доступна процессу Windsurf (запуск через GUI не считывает профиль терминала), либо перейдите на ${file:~/.secrets/bb_key.txt}. Если ключ указан верно, но инструменты не появляются, убедитесь, что URL заканчивается на /api/mcp и сервер не заблокирован списком разрешений команды.