Cấu hình MCP trên Windsurf: Tạo ảnh trực tiếp trong Cascade

Máy chủ MCP trong Windsurf là một hộp công cụ bên ngoài mà agent có thể gọi trực tiếp trong khi trao đổi: bạn khai báo một lần trong mcp_config.json, và Cascade sẽ có thêm các khả năng mà mô hình gốc chưa hỗ trợ. Tạo ảnh là tính năng thiếu hụt rõ ràng nhất. Windsurf dựng cấu trúc trang cài đặt, gắn route và viết test rất mượt mà, nhưng thường để lại ba hình chữ nhật xám ở vị trí đáng lẽ phải có hình minh họa.

Tóm tắt ngắn gọn nếu bạn muốn thiết lập nhanh: Tạo một API key trong hồ sơ BananaBanana, sau đó thêm khối cấu hình này vào ~/.codeium/windsurf/mcp_config.json:

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

Thiết lập biến môi trường export BB_API_KEY=bb_live_YOUR_KEY, tải lại các máy chủ MCP, và mười công cụ sẽ xuất hiện trong Cascade. Giá tạo ảnh chỉ từ $0.03 mỗi ảnh trừ vào số dư trả trước, video từ $0.10, không cần gói đăng ký hàng tháng và không phải tự cấu hình dự án cloud. Một lưu ý trước khi dán mã: trên các bản dựng gần đây, tệp này có thể không còn là tệp mà agent của bạn đọc. Chi tiết sẽ được giải thích bên dưới.

Vì sao nên tích hợp công cụ tạo ảnh cho Cascade?

Bởi vì thời điểm bạn cần một hình ảnh hầu như không bao giờ là lúc thích hợp để rời khỏi trình soạn thảo code. Bạn đang tập trung viết luồng onboarding, trạng thái trống (empty state) cần hình minh họa, và giải pháp truyền thống là mở tab trình duyệt mới, viết prompt, tải xuống, đổi tên, kéo vào public/, rồi tìm lại dòng code đang làm dở.

Chỉ một câu lệnh duy nhất sẽ thay thế toàn bộ quy trình rườm rà đó. Cascade tự viết prompt, gọi generate_image, chuyển tệp vào đúng thư mục và viết thẻ <img> kèm văn bản alt. Bạn chỉ việc xem lại diff.

Còn một lý do quan trọng khác đối với công cụ này. Cascade được thiết kế để xây dựng toàn bộ tính năng chứ không chỉ chỉnh sửa đơn lẻ, nên các tài nguyên cần thiết thường đi theo bộ: ba hình minh họa empty state, sáu ảnh thu nhỏ danh mục, một bộ avatar tạm thời. Tạo thủ công từng ảnh trên trình duyệt sẽ làm gián đoạn luồng làm việc.

Giải pháp thay thế máy chủ từ xa là chạy máy chủ MCP ảnh cục bộ, đòi hỏi tiến trình Node hoặc Python trên máy của bạn kèm theo API key của nhà cung cấp upstream với hạn ngạch và thanh toán tự quản lý. Máy chủ từ xa giúp loại bỏ cả hai vấn đề này. Endpoint chạy trên hạ tầng của chúng tôi với cùng quy trình xử lý như trình tạo web, và thông tin xác thực duy nhất của bạn là chuỗi bb_live_ có thể thu hồi bất kỳ lúc nào trên trang hồ sơ.

Windsurf lưu cấu hình MCP ở đâu hiện nay?

Đây là điểm khiến nhiều lập trình viên bối rối vào tháng 8 năm 2026, và bạn nên kiểm tra trước khi chỉnh sửa tệp. Windsurf hiện đã trở thành một phần của Devin Desktop thuộc Cognition: trang windsurf.com chuyển hướng sang devin.ai/desktop, và URL cũ docs.windsurf.com/windsurf/cascade/mcp chuyển hướng 307 sang docs.devin.ai/desktop/cascade/mcp. Ứng dụng trên máy vẫn mang tên Windsurf, giao thức liên kết sâu vẫn là windsurf://, và thư mục cấu hình vẫn là ~/.codeium/windsurf/. Chỉ có tên thương hiệu là thay đổi.

Thay đổi cốt lõi là hiện có hai agent với hai hệ thống cấu hình khác nhau. Tài liệu Cascade MCP nêu rõ điều này trong hộp cảnh báo ở đầu trang: tệp mcp_config.json áp dụng cho agent Cascade cũ, trong khi agent Devin Local (mặc định trên các tab mới) sẽ đọc cấu hình từ Devin CLI. Đã xác minh ngày 20 tháng 8 năm 2026.

Vì vậy hãy chọn đúng tệp tương ứng với agent bạn đang sử dụng.

Agent Cascade cũ đọc ~/.codeium/windsurf/mcp_config.json (trên Windows là %USERPROFILE%\.codeium\windsurf\mcp_config.json). Các máy chủ từ xa tại đây nhận trường serverUrl hoặc url kèm headers, tương tự đoạn code ở đầu bài.

Agent Devin Local đọc các tệp cấu hình CLI: ~/.config/devin/mcp_config.json cho phạm vi người dùng, .devin/mcp_config.json cho dự án chia sẻ qua git, và .devin/mcp_config.local.json cho các khóa cá nhân (được tự động thêm vào gitignore). Tên các trường có chút khác biệt:

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

Hoặc không cần mở trình soạn thảo: lệnh devin mcp add bananabanana https://bananabanana.pro/api/mcp sẽ tạo mục nhập trong phạm vi cục bộ, sau đó bạn chỉ cần bổ sung khối headers. Các lệnh devin mcp list và devin mcp get bananabanana sẽ hiển thị chính xác những gì CLI đã tải.

Trong cả hai trường hợp, endpoint chính xác là https://bananabanana.pro/api/mcp. Không phải /mcp (đây là trang tài liệu dành cho người đọc), gửi yêu cầu POST đến đó sẽ trả về HTML và khiến agent báo lỗi. Trang tài liệu máy chủ MCP của chúng tôi cung cấp các đoạn mã tương tự và bảng tương thích cho tất cả các client đã xác minh:

Sau khi kết nối, các lệnh gọi list_models và get_account là hoàn toàn miễn phí — hãy yêu cầu Cascade chạy thử một trong hai lệnh để kiểm tra kết nối. get_account trả về số dư, tên key và giới hạn hàng ngày, giúp xác minh xác thực mà không tốn chi phí tạo ảnh.

Trường hợp sử dụng: Tạo bộ ảnh empty state cho ứng dụng Cascade vừa dựng

Đây là tình huống thực tế khi tôi tạo bản demo này. Cascade dựng khung cho một công cụ nội bộ, ba màn hình trạng thái trống hiển thị dưới dạng các khối div xám tạm thời, và thay vì mở phần mềm thiết kế, bạn chỉ cần cung cấp cho agent một câu mô tả phong cách chuẩn để tạo toàn bộ bộ ảnh.

Câu mô tả phong cách là chìa khóa quan trọng. Các hình ảnh empty state chỉ đẹp khi chúng đồng bộ: bảng màu, độ dày nét vẽ và khoảng trống phải nhất quán giữa các hình. Viết câu mô tả một lần, yêu cầu agent sử dụng lại nguyên văn trong mỗi lần gọi và chỉ thay đổi chủ thể chính:

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

Sau đó dùng chính câu mô tả phong cách đó với chủ thể khác cho màn hình «không tìm thấy kết quả»:

Hai hình ảnh này kết hợp rất hài hòa khi dùng làm ảnh giữ chỗ. Nếu cần độ đồng nhất cao hơn, generate_image hỗ trợ tham số seed, và việc lặp lại cùng seed với cùng câu phong cách sẽ cho kết quả gần nhau hơn nữa. Đối với nhân vật hoặc linh vật cần xuất hiện đồng bộ qua hàng chục bức ảnh, kỹ thuật viết prompt quan trọng hơn chính client, như đã nêu chi tiết trong hướng dẫn tạo nhân vật nhất quán.

Hai lưu ý minh bạch: Tôi đã tạo các ví dụ này bằng Nano Banana Pro với giá $0.11 vì chúng được đăng trên bài viết này và cần độ chi tiết cao. Đối với các ảnh giữ chỗ tạm thời mà nhà thiết kế sẽ thay thế sau hai tuần, nano-banana-2-lite với giá $0.03 là lựa chọn rất tiết kiệm, và hướng dẫn bản Lite của chúng tôi giải thích rõ những trường hợp mô hình này đáp ứng hoàn hảo. Đây cũng là mô hình mặc định của công cụ.

Tạo video cũng hoạt động ngay trong đoạn chat. generate_video không bao giờ trừ tiền ở lệnh gọi đầu tiên: nó trả về báo giá ước tính, và agent phải lặp lại lệnh gọi kèm tham số confirm_cost khớp đúng số tiền đó trước khi quá trình kết xuất bắt đầu. Video 4 giây không tiếng độ phân giải 720p trên Veo 3.1 Lite có giá từ $0.10; Omni Flash có giá $0.10 mỗi giây với âm thanh luôn bật sẵn (clip 3 giây có giá $0.30).

Những lưu ý quan trọng về Windsurf cần nắm rõ

Năm điểm thực tế tôi ghi nhận trong quá trình cấu hình:

1. Biến môi trường chưa đặt sẽ âm thầm thất bại. Tài liệu chỉ rõ: ${env:VAR_NAME} được thay bằng giá trị biến, và nếu chưa đặt, nó sẽ trở thành chuỗi rỗng mà không báo lỗi hay cảnh báo nào. Header gửi đi chỉ là Bearer trơ trọi, máy chủ trả về 401, khiến lỗi trông giống như máy chủ bị hỏng thay vì do thiếu export. Các ứng dụng mở từ GUI không đọc cấu hình shell, vì vậy lệnh export trong .zshrc sẽ không hiển thị trừ khi Windsurf được mở từ terminal. Nếu list_models báo lỗi xác thực, hãy kiểm tra biến môi trường trước tiên.

2. Cú pháp ${file:…} đáng tin cậy hơn và là tính năng riêng của Windsurf. Cấu hình hỗ trợ ${file:/duong/dan/tep}, đọc nội dung tệp đã xóa khoảng trắng, hỗ trợ cả đường dẫn chứa dấu ngã ~. Do đó "Authorization": "Bearer ${file:~/.secrets/bb_key.txt}" hoạt động mà không cần biến môi trường và xử lý triệt để lỗi khi mở từ GUI. Tôi khuyên dùng cách này trên Windsurf. Cursor và VS Code không có tính năng này.

3. Cascade giới hạn tối đa 100 công cụ. Đây là giới hạn tổng cho tất cả các máy chủ MCP đã kết nối. Trong trang cài đặt của từng máy chủ, bạn có thể tắt bớt các công cụ không dùng. Chúng tôi bổ sung mười công cụ. Nếu bạn đã kết nối nhiều máy chủ lớn, hãy tắt những gì không cần thiết: generate_speech, edit_video và list_generations rất dễ tắt nếu bạn chỉ muốn tạo ảnh.

4. Deeplink một chạm không chứa key của bạn, giúp đảm bảo an toàn. Windsurf hỗ trợ liên kết dạng windsurf://windsurf-mcp-registry?serverName=<name> để mở trang xem xét trước khi cài đặt. Ưu điểm: không có cấu hình mã hóa nào, do đó không có rủi ro lộ key qua các URL chia sẻ. Hiện tại chúng tôi chưa có mặt trên marketplace công khai nên sẽ cấu hình thủ công qua JSON.

5. Trong các gói nhóm, ID máy chủ phân biệt chữ hoa/chữ thường. Khi quản trị viên đưa một máy chủ MCP vào danh sách cho phép, tất cả các máy chủ khác sẽ bị chặn đối với cả nhóm, và Server ID được duyệt phải khớp chính xác từng chữ hoa/thường với tên key trong mcp_config.json. Tức là nếu admin duyệt bananabanana mà bạn viết BananaBanana, kết nối sẽ thất bại mà không nêu rõ nguyên nhân.

Một hạn chế về giao diện: generate_speech trả về âm thanh dưới dạng liên kết thay vì trình phát trực tiếp trong Cascade, do đó bạn cần mở tệp riêng. Trong khi đó, ảnh được trả về kèm bản xem trước thu nhỏ ngay cạnh liên kết rất tiện lợi.

Sử dụng OAuth thay vì API Key thì sao?

Cả hai phương thức đều được hỗ trợ và phục vụ cho các agent khác nhau.

Devin CLI (agent Devin Local) hỗ trợ OAuth đầy đủ: lệnh devin mcp login <name> sẽ mở luồng đăng nhập trên trình duyệt, lưu token cục bộ và tự động làm mới qua Đăng ký Client Động (DCR). Máy chủ của chúng tôi là máy chủ ủy quyền OAuth 2.1 hỗ trợ DCR và chỉ báo tài nguyên RFC 8707.

Đối với bài viết này, tôi đã thử nghiệm qua API key (initialize, get_account, list_models với key bb_live_ thật). Nếu thử nghiệm OAuth và gặp sự cố, tùy chọn quan trọng cần lưu ý là oauthResource để ghi đè tham số resource của RFC 8707, vì endpoint của chúng tôi yêu cầu audience https://bananabanana.pro/api/mcp.

Cũng có lý do thực tế để ưu tiên API key: các key hoàn toàn miễn phí và có thể tạo nhiều key, mỗi key có nhật ký sử dụng riêng (công cụ, mô hình, chi phí, tóm tắt prompt) và giới hạn chi tiêu hàng ngày bằng USD tùy chọn trong Hồ sơ → Khóa API MCP. Giới hạn hàng ngày này là lớp bảo vệ hữu hiệu trước khi trao quyền chi tiêu cho một agent tự động.

Về phân quyền: cấu hình Devin CLI hỗ trợ thiết lập quy tắc cho từng công cụ qua định dạng mcp__<server>__<tool>, rất phù hợp với máy chủ trả phí:

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

Các lệnh truy vấn thông tin miễn phí sẽ chạy mượt mà, trong khi các tác vụ kết xuất tốn phí sẽ yêu cầu xác nhận trước.

Chi phí tạo media demo trong bài viết này là bao nhiêu?

Mức giá tiêu chuẩn cho mỗi lần tạo, đúng với các con số mà list_models trả về cho agent:

Cả hai hình ảnh empty state đều thành công ngay lần đầu tiên nhờ phong cách vector phẳng dễ tạo. Đối với các bức ảnh sản phẩm chân thực, bạn nên dự trù thêm ngân sách cho một vài lần tạo lại.

Nếu bạn đã dùng máy chủ này trên trình soạn thảo khác, cấu hình Windsurf ở trên là phần mới duy nhất: cùng một key, số dư và lịch sử tạo. Các bài hướng dẫn cho Cursor và VS Code của chúng tôi cũng đề cập đến máy chủ này trên các client đó. Sẵn sàng bắt đầu chưa? Hãy tạo API key và yêu cầu Cascade tạo bức ảnh đầu tiên cho bạn.

Câu hỏi thường gặp (FAQ)

Windsurf có hỗ trợ máy chủ MCP từ xa với Authorization header không?

Có. Các máy chủ HTTP từ xa trong mcp_config.json chấp nhận trường serverUrl (hoặc url) và đối tượng headers tùy chọn. Cascade hỗ trợ các giao thức stdio, Streamable HTTP và SSE. Cả hai trường đều hỗ trợ nội suy ${env:VAR} và ${file:/path} để tránh lộ key dưới dạng văn bản thô. Đã xác minh theo tài liệu chính thức ngày 20 tháng 8 năm 2026.

Agent Windsurf của tôi thực sự đọc tệp cấu hình nào?

Tùy thuộc vào agent bạn sử dụng. Agent Cascade cũ đọc ~/.codeium/windsurf/mcp_config.json. Agent Devin Local (mặc định cho tab mới) đọc các tệp của Devin CLI: ~/.config/devin/mcp_config.json, .devin/mcp_config.json hoặc .devin/mcp_config.local.json cho key cá nhân. Nếu không thấy máy chủ sau khi chỉnh sửa, hãy kiểm tra sự phân chia này trước tiên.

Tôi có cần tài khoản cloud riêng để tạo ảnh trong Windsurf không?

Không. Các máy chủ MCP ảnh cục bộ cần API key của bên thứ ba kèm hạn mức và hóa đơn riêng. Máy chủ từ xa chạy việc tạo ảnh trên cụm hạ tầng do chúng tôi quản lý, nên bạn chỉ cần key bb_live_ từ hồ sơ của mình. Tài khoản mới được tặng $0.20 số dư ban đầu, đủ để tạo 6 ảnh trên mô hình tiết kiệm mà không cần nạp tiền.

Cascade có thể tạo video qua cùng máy chủ này không?

Có, với bước xác nhận chi phí bắt buộc. generate_video chỉ trả về báo giá ở lệnh gọi đầu tiên và không trừ tiền; agent phải gửi lại lệnh gọi kèm tham số confirm_cost khớp đúng số tiền đó để bắt đầu kết xuất. Giá từ $0.10 cho clip 4 giây không tiếng 720p trên Veo 3.1 Lite đến $4.40 cho bản kết xuất Veo 3.1 chất lượng cao kèm âm thanh; Omni Flash có giá $0.10 mỗi giây kèm âm thanh mặc định. Quá trình tạo video mất từ 1 đến 10 phút, trong lúc đó agent sẽ thăm dò trạng thái qua get_result.

Vì sao máy chủ MCP báo lỗi xác thực trong Windsurf?

Trong 9 trên 10 trường hợp, nguyên nhân là do khóa xác thực chứ không phải do cú pháp cấu hình. Biến ${env:BB_API_KEY} chưa đặt sẽ trở thành chuỗi rỗng mà không báo lỗi, gửi đi bearer token trống và nhận phản hồi 401. Hãy đảm bảo tiến trình Windsurf nhìn thấy biến này (mở từ GUI không nạp shell profile) hoặc chuyển sang dùng ${file:~/.secrets/bb_key.txt}. Nếu key đã chuẩn, hãy kiểm tra URL có đuôi /api/mcp và danh sách cho phép của nhóm không chặn Server ID.