ブログに戻る
BananaBanana Teamtutorialmcpwindsurf

WindsurfのMCP設定：Cascadeで画像生成を行う方法

WindsurfにリモートMCPサーバーを追加してチャットから画像生成：mcp_config.json、Devinエージェントとの設定分離、注意点、$0.03からの料金。

WindsurfのMCP設定：Cascadeで画像生成を行う方法

WindsurfにおけるMCPサーバーとは、対話中にエージェントが必要に応じて呼び出せる外部ツールボックスです。mcp_config.json に一度設定を記述するだけで、ベースモデルには備わっていない機能をCascadeに追加できます。その中でも画像生成は最も実用的な拡張です。Windsurfは設定画面の構築、ルーティング、テストの作成を軽快にこなしますが、挿絵が入るべき場所には灰色の四角形が3つ残されるだけです。

手短に設定したい場合は、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上で10種類のツールが利用可能になります。画像生成は前払い残高から1枚あたり$0.03〜、動画は$0.10〜で利用でき、月額サブスクリプションや独自のクラウド契約は不要です。貼り付ける前に1点注意があります。最近のアップデート版では、エージェントが参照する設定ファイルが変更されている場合があります。詳しくは後述します。

なぜCascadeに画像生成ツールが必要なのか？

画像が必要になったタイミングで、コードエディタから離れるのは集中力を大きく削ぐからです。オンボーディング画面のロジックを深く掘り下げている最中に空状態のイラストが必要になった場合、従来はブラウザを開き、プロンプトを入力し、ダウンロードして名前を変え、public/ フォルダへ移動させ、元のコード位置を探し直す必要がありました。

エージェントへの指示1つで、この一連の作業が完了します。Cascadeが自らプロンプトを組み立て、generate_image を呼び出し、適切なフォルダにファイルを配置して、alt属性付きの <img> タグを挿入します。あとはdiffを確認するだけです。

もう1つの重要な理由として、Cascadeが単一の変更ではなく機能全体を一括構築する設計になっている点が挙げられます。そのため、必要なアセットは3つの空状態画像、6つのカテゴリサムネイル、仮のアバターセットなど、まとまった単位で発生します。これらをブラウザで手動生成するのは非常に非効率です。

リモートサーバーを使わない場合、ローカルの画像MCPサーバー（マシン上でNodeやPythonプロセスを常駐させ、自前のプロバイダーキーを登録）を動かす必要があります。リモートサーバーならその手間がありません。エンドポイントは当社のインフラ上でWebジェネレーターと同じパイプラインで動作し、必要な認証情報はプロフィール画面からいつでも失効可能な bb_live_ 文字列1つだけです。

アプリのワイヤーフレームが表示されたワイドモニターで、空のフレームに小さな浮遊ブラシが絵を描き込んでいるイラスト

現在のWindsurfはMCP設定をどこに保存しているか？

2026年8月時点で多くの人が戸惑うポイントですので、ファイルを編集する前に確認しておきましょう。WindsurfはCognitionのDevin Desktopへと統合が進んでおり、windsurf.com は devin.ai/desktop へリダイレクトされ、旧ドキュメントURL docs.windsurf.com/windsurf/cascade/mcp は docs.devin.ai/desktop/cascade/mcp へ307リダイレクトされます。ディスク上のアプリ名はWindsurfのままで、ディープリンクのスキームも windsurf://、設定フォルダも ~/.codeium/windsurf/ です。変わったのはブランド表記です。

実質的な変更点は、2つのエージェントと2系統の設定システムが存在する点です。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（自動的にgit除外）です。フィールド名が一部異なります。

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

CLI経由で設定することも可能です。devin mcp add bananabanana https://bananabanana.pro/api/mcp でローカル設定を作成し、後から headers を追加します。devin mcp list や devin mcp get bananabanana で正しく認識されているか確認できます。

いずれの場合も、エンドポイントは https://bananabanana.pro/api/mcp です。/mcp（人間用のドキュメントWebページ）ではありません。誤ってそちらにPOSTするとHTMLが返却されエージェントが混乱します。当社のMCPサーバー案内ページには、動作確認済みクライアントの設定スニペットと対応表が掲載されています。

BananaBananaのMCPドキュメントページにあるWindsurf設定ブロック、serverUrlとAuthorizationヘッダーを含むmcp_config.jsonスニペット

接続後は list_models や get_account が無料で実行できます。テストとしてCascadeに実行させてみてください。get_account は残高、キー名、日次上限額を返すため、生成費用を消費せずに認証の成否を確認できます。

実践例：Cascadeが構築したアプリの空状態イラストを一括作成

このデモを作成した際の実際のシナリオです。Cascadeが社内ツールの骨組みを作成し、3つの空状態がグレーの四角形として配置されました。デザインツールを開く代わりに、エージェントへ統一スタイルの指示文を渡し、一連のアセットを生成させます。

スタイルの指示文が統一感の要となります。空状態のイラストはセットとしての調和が不可欠なため、カラーパレット、線の太さ、余白の比率を各画像で維持する必要があります。基本文を1つ作成し、エージェントに毎回そのまま適用させ、主題のみを変更します。

→ 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 パラメータに対応しており、同一シードと同一スタイル文を組み合わせることでトーンを近づけられます。十数枚にわたって一貫性を維持する必要があるキャラクターやマスコットについては、クライアント設定よりもプロンプティング技術が重要です。詳しくはキャラクター一貫性ガイドをご覧ください。

率直な補足として、この記事のデモ画像は詳細な描写が必要だったため、1枚$0.11のNano Banana Proで生成しました。数週間後にデザイナーが差し替える仮画像であれば、$0.03の nano-banana-2-lite で十分対応可能です。詳細はLiteモデル活用ガイドで解説しています。なお、ツールのデフォルトモデルもLiteに設定されています。

同じチャット内から動画生成も可能です。generate_video は初回の呼び出しでは課金されず、まず見積もり額を返します。エージェントがその金額と一致する confirm_cost を指定して再送信して初めてレンダリングが始まります。Veo 3.1 Liteの音声なし720p（4秒）は$0.10〜、Omni Flashは常時音声付きで1秒あたり$0.10（3秒なら$0.30）です。

知っておくべきWindsurfの留意点

設定作業を通じて把握した実用上のポイントを5点挙げます。

大きさの異なる2つの引き出しの間で鍵が浮遊し、手前に南京錠があるイラスト

1. 未設定の環境変数はエラーを出さずに失敗する。 ドキュメント記載の通り、${env:VAR_NAME} は環境変数の値に展開されますが、未設定の場合は空文字列に置き換えられます。エラーや警告は出ません。ヘッダーは単なる Bearer として送信され、サーバーは401を返すため、環境変数の設定漏れではなくサーバー障害のように見えてしまいます。GUI起動のアプリはシェルのプロファイルを読み込まないため、.zshrc でexportしていてもターミナルから起動しない限り反映されません。list_models で認証エラーが出た場合は、まず環境変数を確認してください。

2. ${file:…} の利用が確実（Windsurf専用機能）。 同設定では ${file:/path/to/file} がサポートされており、チルダを含むファイルパスの中身を自動で読み込んで展開します。"Authorization": "Bearer ${file:~/.secrets/bb_key.txt}" と記述すれば環境変数が不要になり、GUI起動時の問題も回避できます。CursorやVS Codeにはない便利な機能です。

3. Cascadeのツール上限は合計100個。 ドキュメントによると、接続されている全MCPサーバーを合わせた上限です。各サーバーの設定画面で不要なツールを個別に無効化できます。当サーバーは10個のツールを提供しています。GitHubなどの巨大なサーバーを併用している場合は、静止画のみを利用するなら generate_speech、edit_video、list_generations などをオフにすると余裕が生まれます。

4. ワンクリックディープリンクはキーを含まない安全仕様。 Windsurfは windsurf://windsurf-mcp-registry?serverName=<name> 形式のリンクをサポートしており、インストール前に確認画面が開きます。設定全体をbase64化して渡す方式とは異なり、共有URLから認証情報が漏洩する心配がありません。当社は現在マーケットプレイス外のため、手動JSON設定を利用します。

5. チームプランではサーバーIDの大文字小文字が厳密に判定される。 管理者がMCPサーバーを1つでも許可リストに追加すると、未許可のサーバーはチーム全体で遮断されます。また、許可されたServer IDは mcp_config.json 内のキー名と大文字・小文字まで一致している必要があります。例えば管理者が bananabanana を許可しているのに設定に BananaBanana と書くと接続できず、原因も明示されません。Enterpriseプランでは独自のMCPレジストリを指定することも可能です。

なお、generate_speech は音声をインライン再生ではなくURLとして返却するため、ファイルを手動で開く必要があります。画像についてはリンクと併せてインラインプレビューが表示されます。

APIキーの代わりにOAuthを利用する場合は？

両方の方式が用意されており、それぞれ対象エージェントが異なります。

Devin CLI（Devin Localエージェント）は完全なOAuthをサポートしています。devin mcp login <name> でブラウザ認証が開き、トークンのローカル保存および自動更新が行われます。動的クライアント登録（DCR）に対応しているため事前登録も不要です。当サーバーはDCRおよびRFC 8707リソース指標に対応したOAuth 2.1認可サーバーとして動作します。

本記事ではAPIキー方式（実際の bb_live_ キーを用いた initialize、get_account、list_models）を検証しました。OAuthを試す際に不整合が生じる場合は、RFC 8707の resource パラメータをオーバーライドする oauthResource の設定を確認してください。当エンドポイントのオーディエンスは https://bananabanana.pro/api/mcp です。

日常利用ではAPIキー方式が扱いやすい利点もあります。キーは無料で複数発行でき、利用履歴（ツール、モデル、費用、プロンプト概要）の確認や、プロフィール画面での1日あたりの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

空状態のイラストは2枚とも1発で意図通りの仕上がりになりました。フラットベクターは破綻が少ない利点があります。写実的な商品写真などを生成する場合は、リトライ用に少し余裕を見ておくことをおすすめします。

既に他のエディタで当サーバーをお使いの場合、上記の設定を行うだけで同じキー、残高、履歴を共有できます。Cursor向けガイドやVS Code向け設定もあわせてご覧ください。準備ができたらキーを発行し、Cascadeで画像生成を試してみましょう。

よくある質問（FAQ）

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サーバーでは外部プロバイダーのAPIキーや利用枠が必要ですが、リモートサーバーでは当社の管理プール側で生成処理を行うため、プロフィールで発行した 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は音声付きで1秒あたり$0.10です。生成には1〜10分程度かかり、その間エージェントは get_result をポーリングします。

WindsurfでMCPサーバーが認証エラーになる原因は？

大半の原因は設定構文ではなく認証情報の未解決です。未設定の ${env:BB_API_KEY} は空文字に展開され、空のBearerトークンが送信されて401エラーとなります。Windsurfプロセスから環境変数が見えているか確認するか、${file:~/.secrets/bb_key.txt} に切り替えてください。キーが正しいにもかかわらずツールが表示されない場合は、URL末尾が /api/mcp になっているか、チームの許可リストによる制限がないかをご確認ください。

tutorialmcpwindsurf