返回博客
BananaBanana Teamtutorialmcpwindsurf

Windsurf MCP 配置：在 Cascade 中直接生成图像

在 Windsurf 中添加远程 MCP 服务器，直接在对话中生成图像：mcp_config.json、Devin 智能体配置划分、实用技巧与 $0.03 起的价格。

Windsurf MCP 配置：在 Cascade 中直接生成图像

Windsurf 中的 MCP 服务器是智能体在对话中调用的外部工具箱：只需在 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}"
      }
    }
  }
}

执行 export BB_API_KEY=bb_live_YOUR_KEY 导出环境变量，重新加载 MCP 服务器，Cascade 中便会出现十个新工具。图像按预充值余额扣费，单张 $0.03 起，视频 $0.10 起，无需订阅，也无需自行维护云平台项目。复制粘贴前需要注意一点：在较新版本的编辑器中，你的智能体读取的可能已不再是该文件。下文将详细说明。

为什么要在 Cascade 中集成图像生成？

因为在需要插图的瞬间，离开代码编辑器往往是最打断心流的。你正深入编写新用户引导流程，空状态需要配图，而传统流程是：切换浏览器标签页、写提示词、下载、重命名、拖入 public/ 目录，最后再费力找回之前写代码的思路。

一条指令即可省去全部繁琐步骤。Cascade 自行撰写提示词、调用 generate_image、将文件保存至目标文件夹，并编写带有 alt 文本的 <img> 标签。你只需要审核 diff 代码变动。

对于该客户端而言，还有一个更重要的理由。Cascade 的设计理念在于构建完整功能模块而非单行修改，因此所需的静态资源通常成组出现：三个空状态图、六个分类缩略图、一组占位头像。在浏览器标签页中手动生成成套素材极其耗时。

相比于远程服务器，本地部署图像 MCP 服务器需要在本地机器运行 Node 或 Python 进程，并配置自己的上游服务商密钥与计费配额。远程服务器免去了这些维护成本。API 端点运行在我们这一侧，复用 网页生成器 的同款服务管道，你唯一的凭证就是一个可在个人中心随时撤销的 bb_live_ 密钥。

宽屏显示器展示应用线框图且空白相框正被悬浮画笔填充的插画

Windsurf 目前将 MCP 配置存放在哪里？

这是 2026 年 8 月许多开发者感到困惑的地方，建议在修改文件前先理清脉络。Windsurf 现已并入 Cognition 的 Devin Desktop：windsurf.com 重定向至 devin.ai/desktop，旧链接 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 的配置文件。核对时间为 2026 年 8 月 20 日。

因此，请根据你实际使用的智能体选择对应的配置文件。

经典 Cascade 智能体 读取 ~/.codeium/windsurf/mcp_config.json（Windows 上为 %USERPROFILE%\.codeium\windsurf\mcp_config.json）。该文件中的远程服务器接受 serverUrl 或 url 字段以及 headers，即本文开头的代码片段。

Devin Local 智能体 读取 CLI 配置文件：用户级配置为 ~/.config/devin/mcp_config.json，git 协作项目为 .devin/mcp_config.json，个人专用值为 .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 实际加载的内容。

无论哪种方式，API 端点均为 https://bananabanana.pro/api/mcp。请勿填写 /mcp（该路径是人类阅读的文档页面），向其发送 POST 请求会返回 HTML 页面并导致智能体报错。我们的 MCP 服务器文档页面 提供了相同代码片段以及经测试验证的客户端兼容性列表：

BananaBanana MCP 文档页面上的 Windsurf 配置代码块，展示带 serverUrl 与 Authorization 请求头的 mcp_config.json

连接建立后，调用 list_models 和 get_account 均为免费操作。可以先让 Cascade 执行一次作为联通性测试。get_account 会返回余额、密钥名称及每日限额，无需消耗图像生成费用即可确认认证状态。

实战场景：为 Cascade 刚搭建的应用生成一套空状态插画

这是我制作本篇演示时的真实场景。Cascade 搭建了一个内部工具原型，三个空状态默认显示为带灰色背景的占位 div。与其打开设计软件，不如给智能体一句统一的风格描述，让它自动生成整套素材。

风格描述句是保持一致性的关键。空状态插画必须成套协调：调色板、线条粗细和留白比例必须在各图之间保持统一。先拟定一段风格描述，让智能体在每次调用时逐字复用，仅替换画面主体：

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

应用空状态扁平矢量插画：带纸信封飘出的开盖纸箱，由 Windsurf 通过 MCP 图像服务器生成

随后使用完全相同的风格句，仅更换搜索无结果画面的主体：

应用空状态扁平矢量插画：放置在点状网格上的大型放大镜，使用相同风格描述生成以保持风格统一

这两张图作为一组占位素材已经非常契合。如果需要更严苛的一致性，generate_image 支持 seed 参数，固定 seed 并搭配统一风格语句可使结果更为接近。对于需要跨十几张图保持一致的角色或吉祥物，提示词技巧比客户端配置更关键，详情可参考我们的 角色一致性生成指南。

两点客观说明：本例中我使用的是单张 $0.11 的 Nano Banana Pro，因为图片要直接展示在文章中，需要更高细节。对于两周后就会被设计师替换的临时占位图，单张 $0.03 的 nano-banana-2-lite 是极具性价比的选择，我们的 Lite 模型指南 详细分析了该模型的适用边界。这也是工具默认使用的模型，未指定时智能体会默认调用它。

视频同样支持在当前对话中生成。generate_video 在首次调用时绝不扣费，而是返回预估报价；智能体必须使用与该报价完全一致的 confirm_cost 参数发起确认请求后才会启动渲染。Veo 3.1 Lite 720p 4 秒无声视频 $0.10 起；Omni Flash 按每秒 $0.10 计费且始终带音频，3 秒片段仅需 $0.30。

部署前值得了解的 Windsurf 细节

在配置过程中整理出的五条实用经验。

两个大小不同的开放式档案抽屉之间悬浮着一把钥匙和一把挂锁的插画

1. 未设置的环境变量会静默失效。 官方文档明确指出：${env:VAR_NAME} 会被替换为对应环境变量的值；若变量未定义，则直接替换为空字符串，既不报错也不警告。此时请求头变成裸 Bearer ，服务器返回 401，表面上极易误判为服务器故障而非环境变量缺失。通过图形界面启动的应用不会读取终端 shell 配置文件，因此在 .zshrc 中的 export 在 GUI 启动下不可见。若 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，将无法连接且错误信息不会直说明原因。企业团队还可以将 Windsurf 指向自建 MCP 注册中心而非默认市场。

另外提一点体验细节：generate_speech 目前返回音频 URL 而非支持 Cascade 内联播放的组件，需要手动打开文件。而图像生成则会在链接旁附带内联缩略图，交互体验明显更好。

为何使用 API 密钥而非 OAuth？

两种认证方式均已支持，它们分别适用于不同的智能体。

Devin CLI（即 Devin Local 智能体）具备完整的 OAuth 支持：执行 devin mcp login <name> 会在浏览器中开启授权流程，并在本地存储与自动刷新令牌，支持动态客户端注册（DCR）无需事先手动登记。我们的服务器是兼容 DCR 和 RFC 8707 资源指示符的 OAuth 2.1 授权服务器。Cascade 文档同样表明其支持各类传输协议下的 OAuth。

本文主要测试了 API 密钥方案（使用真实 bb_live_ 密钥测试 initialize、get_account、list_models）。如果尝试 OAuth 遇到问题，关键配置项为 oauthResource，它用于覆盖 RFC 8707 的 resource 参数，因为我们的 API 端点受众为 https://bananabanana.pro/api/mcp。

日常使用中推荐密钥还有另一个实际考量：密钥创建完全免费且可多开，在「个人中心 → MCP API 密钥」中每个密钥都配有独立的使用日志（工具、模型、花费、提示词摘要）及可选的每日 USD 消费限额。在让自动化智能体调用扣费工具前，配置消费限额是极其实用的安全防线。

在权限控制方面，Devin CLI 配置支持通过 mcp__<server>__<tool> 匹配规则针对具体工具设置权限，与付费服务器配合非常契合：

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

免费查询操作静默执行，而任何触发实际渲染的操作都会先请求人工确认。

本文演示素材花费了多少？

均按常规单次生成价格计费，与 list_models 返回给智能体的数值完全一致：

素材模型价格
空状态插画（收件箱）Nano Banana Pro, 1K$0.11
空状态插画（无结果）Nano Banana Pro, 1K$0.11
封面 + 2 张概念插画Nano Banana Pro, 1K$0.33
文档页面截图浏览器截取，非生成$0.00
总计$0.55

两张空状态插画均一次生成成功，一方面是运气，另一方面扁平矢量风格容错率较高。对于写实风格的产品渲染图，建议预留少量重试预算。

如果你已在其他编辑器中使用过该服务器，Windsurf 上的配置完全一致：共用密钥、余额与生成历史。我们在 Cursor 实战指南 与 VS Code 配置教程 中介绍了对应客户端的使用方式。准备就绪了吗？立即创建密钥，让 Cascade 为你生成第一张插画。

常见问题

Windsurf 是否支持带 Authorization 请求头的远程 MCP 服务器？

支持。mcp_config.json 中的远程 HTTP 服务器接受 serverUrl（或 url）字段及可选的 headers 对象。Cascade 支持 stdio、Streamable HTTP 和 SSE 传输模式。serverUrl 和 headers 均支持 ${env:VAR} 与 ${file:/path} 变量插值，避免密钥明文暴露。配置已于 2026 年 8 月 20 日根据官方文档验证。

我的 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 初始余额，无需付费即可在基础模型上免费生成 6 张图片。

Cascade 是否可以通过同一个服务器生成视频？

可以，且具备强制二次确认机制。generate_video 首次调用仅返回费用预估且不扣款；智能体必须在随后的请求中传入与该金额一致的 confirm_cost 参数才会正式开始渲染。价格从 Veo 3.1 Lite 720p 4 秒无声视频的 $0.10，到顶级带音频 Veo 3.1 渲染的 $4.40 不等；Omni Flash 始终附带声音，价格为每秒 $0.10。视频生成通常需要 1 到 10 分钟，在此期间智能体会持续轮询 get_result。

为什么 MCP 服务器在 Windsurf 中提示认证错误？

绝大多数情况下是密钥问题而非配置语法错误。未设置的 ${env:BB_API_KEY} 会被静默替换为空字符串，请求携带空 bearer 令牌导致 401 错误。请确认 Windsurf 进程能否读取该变量（GUI 启动默认不加载 shell 配置文件），或直接改用 ${file:~/.secrets/bb_key.txt}。若密钥正确仍无工具显示，请检查 URL 是否以 /api/mcp 结尾，以及团队白名单是否拦截了该 Server ID。

tutorialmcpwindsurf