VideoGen

@videogen/mcp

あらゆる MCP クライアント（Cursor、Claude Desktop、Windsurf など）に VideoGen API の全機能を公開する Model Context Protocol（MCP）サーバーです。エージェントは、スクリプトから動画を生成し、画像／ナレーション／音楽／アバターを作成し、ファイルをアップロードし、プロジェクトを書き出してリミックスし、実行を管理できます。すべて、ご自身の API キーで認証されます。

VideoGen MCP サーバーについて詳しくはこちらをご覧ください。

ホスト型サーバーは Smitheryでご利用いただけます。

ChatGPT

ホスト型プラグインには、VideoGen のホームサイドバーアプリ（open_home）が含まれています。製品のホーム画面に沿って、一般的な作成プロンプトと提案、最近のプロジェクト、カテゴリ別の例、おすすめのワークフロー、再利用可能なアセット、テンプレートを表示します。閲覧によって生成が始まることはありません。Start を押すと、下書きが ChatGPT の会話に送信されます。プロジェクトやライブラリのリンクを開くと、対応する VideoGen 環境に移動します。

ホームカタログは frontend/ と同じヘルパーから生成され、web/homeCatalog.ts にコミットされます。これにより、スタンドアロンの MCP/npm/Docker ビルドは内部パッケージから独立して保たれます。製品カタログを変更した後は、リポジトリのルートから cd api && node --import tsx scripts/generate-chatgpt-home.ts を実行して更新してください（最新の base/defs/static JS ビルドが必要です）。build:js は、既存のアップロードウィジェットやプレビューウィジェットとともにページをバンドルします。ChatGPT でサイドバー項目が利用可能になる前に、MCP をデプロイし、既存のプラグインを再スキャンしてください。

ホーム固有のチェック（ブラウザーや実際のアカウントは不要です）：

cd mcp
node --import ./test/register.mjs --test src/homeWidget.test.ts test/homeBridge.test.mjs
cd ../api
TSX_TSCONFIG_PATH=../mcp/web/tsconfig.json node --import tsx --test ../mcp/test/homePage.test.tsx

すべてのユーザーが ChatGPT で VideoGen を実行する際は、公開されている ChatGPT Plugins Directory の VideoGen プラグインをご利用ください。これがサポート対象の方法です。

/mcp/chatgpt エンドポイント、ChatGPT Apps のコマースに関する注記、open_uploader ウィジェット、およびこのファイル内の後述のコネクター用チェックリストは、そのプラグインの内部テスト用です。

通信方式は 2 種類あります。内部テスト用の ChatGPT Apps サーフェス（上記を参照）を除き、ツールの機能は同じです。

• ローカル（stdio） — クライアントは @videogen/mcp をサブプロセスとして起動し、VIDEOGEN_API_KEY からキーを読み取ります。
• リモート（Streamable HTTP） — ホスト型のマルチテナント HTTP サーバーです。クライアントはネットワーク経由で接続し、リクエストごとに Authorization: Bearer <api-key> で認証します。サーバーにキーが保存されることはありません。

ホストのサーフェス（リモート）： /mcp（および stdio）は標準サーフェスです。ユーザーのクレジットが不足している場合や、プランの機能が必要な場合、ツールとガイダンスによって get_app_deep_link（OPEN_UPGRADE／OPEN_PURCHASE_CREDITS／OPEN_ENABLE_TOP_UPS）に誘導します。/mcp/chatgpt は、公開プラグイン向けの内部テスト用ChatGPT Apps サーフェスです。コマース関連のディープリンクは省略され、請求に関するエラーは「VideoGen アカウントを管理してください」と書き換えられます。また、文面では「購入」「買う」「アップグレード」「トップアップ」という表現を使いません（OpenAI Plugins のデジタル商品ポリシー）。.cursor/rules/chatgpt-mcp-no-commerce.mdc と mcp/src/hostSurface.ts を参照してください。

これは、ホスト型のドキュメントMCP（https://docs.videogen.io/_mcp/server）とは異なります。ドキュメントMCPでは、クライアントは API ドキュメントを読むことしかできません。このサーバーは実際に API を 実行 します。

仕組み

• 公式の @videogen/sdk をラップし、SDK の認証済みパススルーを通じてライブ API を呼び出します。
• ローカルのトランスポートは VIDEOGEN_API_KEY からキーを読み取ります。リモートのトランスポートは各リクエストの Authorization: Bearer ヘッダーからキーを読み取り、そのチームに紐付けられた新しいサーバーをリクエストごとに作成します（ステートレスのため、リクエスト間でセッション状態は共有されません）。
• キーがマシンの外に出るのは、ローカルでは VideoGen API へのリクエスト時のみです。リモートではリクエストの処理中に限り VideoGen API に転送され、保存されることはありません。
• 長時間実行される操作（ワークフロー、メディアツール、プロジェクトのエクスポート）には、複合ツールを使用します。ホスト型 HTTP トランスポートは実行 ID をすぐに返すため、対応する get_* ツールを使ってポーリングを続けてください。ローカルの stdio トランスポートは、デフォルトで完了まで待機します。

設定

app.videogen.io/api から API キーを取得してください。どちらのトランスポートも同じツールを公開します。リモートサーバーの使用をおすすめします。

リモート（Streamable HTTP）— 推奨

インストールや更新は不要です。Streamable HTTP トランスポートに対応する MCP クライアントからホストされたエンドポイントに接続し、API キーをベアラートークンとして送信してください。

{
  "mcpServers": {
    "videogen": {
      "url": "https://mcp.videogen.io/mcp",
      "headers": {
        "Authorization": "Bearer sk_videogen_live_..."
      }
    }
  }
}

リモートサーバーの仕様：

• POST /mcp で MCP JSON-RPC メッセージを受け付けます（ステートレスのため、リクエストごとに新しいサーバーを作成します）。
• Authorization: Bearer ヘッダーから API キーまたは OAuth アクセストークンを読み取ります。標準の /mcp エンドポイントでは、すべてのリクエストに認証情報が必要で、OAuth を開始するために WWW-Authenticate チャレンジを伴う 401 を返します。内部テスト用の /mcp/chatgpt エンドポイントでは、認証なしでツールを検出でき、保護されたツールの結果で OAuth チャレンジを返します。これは、ChatGPT が標準トランスポートのチャレンジから OAuth を開始しないためです。認証情報は VideoGen API にのみ転送され、保存されることはありません。
• ロードバランサーや Cloud Run の起動プローブ用に GET /health を公開します。
• CORS プリフライト（OPTIONS）を処理するため、ブラウザーベースのクライアントが接続できます。
• 3 種類のアップロード方法に対応します。小さなアセット（画像、ロゴ、短い音声）の場合、upload_file は Base64 エンコードされたコンテンツをインラインで受け取ります（fileData）。大きなファイルの場合、create_file_upload は { fileId, uploadUrl } を返します。クライアントは有効期間の短い事前署名 URL に生のバイト列を PUT し（Authorization ヘッダーは不要）、その後 { fileId, wait: true } を指定して get_file を呼び出し、処理の完了を待ちます。内部テスト用の /mcp/chatgpt サーフェスでは、open_uploader がチャット内のアップロードウィジェットを表示するため、ユーザーはファイルを直接選択したり、すでに添付した写真を渡したりできます（files）。ウィジェット自体が create_file_upload を呼び出し、クライアント側でバイト列を PUT して、結果の vg_file_... ID のみを返すため、事前署名 URL がモデルに公開されることはありません。このサーフェスでは upload_file と create_file_upload はモデルから隠されています（ui.visibility は app のみ）。ファイル名を指定しても ChatGPT の添付ファイルはアップロードされず、サーバーが添付ファイルの URL を取得することもありません。いずれの方法でも、ほかのツールに渡す vg_file_... ID を取得できます。ローカル（stdio）サーバーでは、代わりにローカルの filePath を使ってアップロードします（サーバーが呼び出し元指定の URL を取得することはないため、SSRF の攻撃対象にはなりません）。

ローカル（stdio）— Cursor / Claude Desktop

クライアントが npx で起動するサブプロセスとして実行されます。VIDEOGEN_API_KEY 環境変数から API キーを読み取ります。このキーがマシンの外に出るのは、VideoGen API へのリクエスト時のみです。

{
  "mcpServers": {
    "videogen": {
      "command": "npx",
      "args": ["-y", "@videogen/mcp"],
      "env": {
        "VIDEOGEN_API_KEY": "sk_videogen_live_..."
      }
    }
  }
}

環境変数

変数	必須	デフォルト	説明
VIDEOGEN_API_KEY	ローカルのみ	—	VideoGen API キー（ローカルサーバー用）です。リモートサーバーでは、代わりにキーが Authorization ヘッダーで送信されます。
VIDEOGEN_BASE_URL	いいえ	https://api.videogen.io	上流 API のベース URL を上書きします（例：ローカル開発用）。どちらのトランスポートにも適用されます。未設定の場合、リモートサーバーではデプロイ環境（dev/prerelease/prod）に応じて上流 API が解決され、ローカル実行ではデフォルトで公開 prod API が使用されます。
VIDEOGEN_OAUTH_ISSUER	いいえ	—	リモートサーバーのみ。OAuth 2.1 の完全な issuer URL です。設定されている場合（または下記の変数から導出される場合）、サーバーは OAuth 保護リソースメタデータ（RFC 9728）と resource_metadata 401 チャレンジを公開し、MCP クライアントが認可サーバーを検出してアカウント連携を実行できるようにします。上流 API（VIDEOGEN_BASE_URL）がトークンの検証に使用する issuer と一致している必要があります。
VIDEOGEN_OAUTH_SUPABASE_PROJECT_URL	いいえ	—	リモートサーバーのみ。Supabase プロジェクトのベース URL です。issuer は ${url}/auth/v1 として導出されます。VIDEOGEN_OAUTH_ISSUER が設定されている場合は無視されます。
VIDEOGEN_OPENAI_APPS_CHALLENGE_TOKEN	いいえ	—	リモートサーバーのみ。公開プラグイン向けの内部テスト用 OpenAI Plugins / ChatGPT Apps ドメイン検証トークンです。設定されている場合、GET /.well-known/openai-apps-challenge はその値を text/plain としてそのまま返します。未設定の場合、そのパスは JSON-RPC 以外の 404 を返します。

ツール

ホストされている50個のツールについては、呼び出し可能なツールのリファレンスと完全な入出力 JSON スキーマをご覧ください。スキーマのスナップショットは MCP tools/list から取得しています。最新の定義を確認するには、接続先サーバーで検出を実行してください。

ワークフロー（動画のエンドツーエンド生成）

script_to_video、voiceover_to_video、slideshow_to_video、storyboard_to_video、list_workflow_runs、get_workflow_run、cancel_workflow_run

メディアツール

generate_image、generate_video_clip、text_to_speech、generate_sound_effect、generate_music、generate_avatar、vectorize_image、remove_image_background、remove_video_background、upscale_image、upscale_video、image_3d_effect、list_tool_executions、get_tool_execution、cancel_tool_execution

プロジェクト

list_projects、get_project、export_project、get_project_export、remix_project、list_project_remix_actions

ファイル

upload_file、create_file_upload、get_file、list_files、open_uploader

open_uploader は、（リモートサーバーのみの）internal-testing /mcp/chatgpt サーフェス上のウィジェットです。チャット内ファイルピッカー（MCP UI リソースとして配信される React コンポーネント）を表示し、ChatGPT ユーザーがリンクを貼り付けずにファイルを添付できます。チャットにすでに添付されている写真は files として渡してください。MCP Apps UI を表示しないクライアントでは何も実行されません。そのようなクライアントでは、代わりに upload_file / create_file_upload を使用してください。ChatGPT ユーザーは公開 VideoGen プラグインを使用してください。

エンティティ

list_entities、create_entity、get_entity、update_entity、archive_entity、add_entity_reference、remove_entity_reference

ACTOR / PRODUCT / VISUAL_STYLE エンティティを作成し、アップロードした画像の参照を関連付けてから、vg_enti_... ID をワークフローと generate_avatar（actorEntityId）に渡します（storyboard_to_video では、シーンごとに productEntityIds / actorEntityIds / visualStyleEntityId を指定します）。

リソースとアカウント

list_tts_voices、list_languages、get_me、get_app_deep_link

ガイダンス（エージェント向けドキュメント）

MCP リソースおよびミラーツールとして公開される運用マニュアル（API 認証情報は不要です）：

リソース URI	ミラーツール
guidance://getting-started	get_getting_started_guidance
guidance://async-tasks	get_async_tasks_guidance
guidance://workflows	get_workflows_guidance
guidance://tools-vs-workflows	get_tools_vs_workflows_guidance

複雑なセットアップ、ポーリング、ワークフロー／リミックス／エクスポート、またはツールとワークフローのどちらを使うかの判断を行う前に、対応する get_*_guidance ツールを呼び出してください。多くのホストではリソースが自動的に添付されないため、ツールを使うのが確実です。内容は docs.videogen.io の公開ドキュメントに基づいていますが、MCP ツールの使用方法（ホスト環境での待機時間上限を含む）に合わせて記述されています。

クリエイティブ MCP ツールは、低レベルの開発者向け API リクエスト形式ではなく、ユーザーの意図を表します。style には、媒体、質感、配色、そしてシンプルな構図の制約を含む、完全で厳密なビジュアルスタイルの段落を指定してください。出力サイズには aspectRatio（単位は { width, height }。例：{ width: 16, height: 9 }）を使用してください。ワークフローでスタイルを省略すると、アプリの Realistic の外観（Photorealistic photograph, natural lighting）が使われます。watercolor のような短いラベルは指定しないでください。スタイルで画像をシンプルに保たないと、画像モデルはフレームいっぱいにテキスト、グラフ、図を詰め込みます。remix_project では、厳選された edits（CAPTIONS、TRANSITIONS、CONVERT_IMAGES_TO_VIDEOS、ZOOM）を指定できます。CONVERT_IMAGES_TO_VIDEOS は静止画から AI 動画クリップを生成します（高コストです）。ZOOM は低コストの Ken Burns カメラモーションです。watermarkMode と endScreenMode は公開されていません。MCP は常に AUTO を送信します（Free プランの出力には VideoGen のウォーターマークが含まれ、VideoGen Pro では削除されます）。

ワークフロー、メディア生成、エクスポートの各ツールは、処理を開始して内部でポーリングします。ホスト環境（Streamable HTTP）サーバーでは、Cloudflare のプロキシタイムアウトを超えないよう待機時間に上限が設けられているため、時間のかかる生成処理は 524 ではなく、実行中のスナップショットを返します。ポーリングを続けるには、get_tool_execution、get_workflow_run、または get_project_export を使用してください。

generate_avatar には、audioFileId と actorEntityId による ACTOR エンティティの指定が必要です。avatarQuality には LOW、STANDARD、HIGH、MAX を設定できます。script_to_video、slideshow_to_video、および CHANGE_NARRATOR では、同じ任意のアクターフィールドを指定できます。

すべてのツールのパラメーターと REST エンドポイントとの対応については、ツールの完全なリファレンスを参照してください。

開発

pnpm build           # bundle to dist/ (dist/index.js, dist/http.js, and the widget)
pnpm typecheck       # type-check
pnpm lint:fix        # lint

# Smoke test the local (stdio) server:
VIDEOGEN_API_KEY=sk_videogen_live_... node dist/index.js

# Smoke test the remote (HTTP) server:
PORT=8080 node dist/http.js
#   Health:  curl http://localhost:8080/health
#   MCP:     curl -X POST http://localhost:8080/mcp \
#              -H 'Authorization: Bearer sk_videogen_live_...' \
#              -H 'Content-Type: application/json' \
#              -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

VIDEOGEN_BASE_URL を設定すると、どちらのトランスポートでも上流 API を上書きできます（例：開発中にローカル API を指定します）。

デプロイ（リモートサーバー）

リモートサーバーは、api／backend／external／frontend とともに、標準のモノレポ CI/CD を通じて Cloud Run にデプロイされます。

• イメージ： ci-cd/docker/mcp/Dockerfile — 最小限のマルチステージ Node ビルドです（ffmpeg／gcloud／VPC ツールは含みません。サーバーは、環境ごとの VideoGen 開発者向け API（dev.api.videogen.io／prerelease.api.videogen.io／api.videogen.io。いずれも利用可能です）に対して、送信 HTTPS リクエストのみを行います）。
• サービスレジストリ： mcp は ci-cd/utils.ts の CLOUD_RUN_SERVICES に登録されています。
• ビルド設定： ci-cd/config.build.ts の CLOUD_RUN_SERVICE_TO_BUILD_CONFIG_MAP.mcp。
• デプロイ設定： ci-cd/config.deploy.ts の mcp — CPU 1 個／2 GiB、同時実行数 80、リクエストタイムアウト 60m（ツール呼び出しはワークフロー／エクスポートをロングポーリングします）、allowUnauthenticated: true（認証は GCP IAM ではなく、呼び出し元の API キーを使ってリクエストごとに行われます）。
• 生成されるパイプライン： ci-cd/cloudbuild/mcp.build.yaml と、GitHub のビルド／デプロイワークフローマトリックス内の mcp エントリーは、CI/CD ジェネレーターによって生成されます。ビルド／デプロイ設定を変更した後は、これらを再生成してください（手動で編集しないでください）。

GCP の手動設定（初回のみ）

CI/CD で Cloud Run サービスのビルドとデプロイを行いますが、初回のみ GCP で手動で行う必要がある手順がいくつかあります。

1. カスタムドメイン／DNS。 サービスには、生成された *.run.app URL ですぐにアクセスできます。mcp.videogen.io でサービスを提供するには、Cloud Run のドメインマッピングを作成する（または既存のロードバランサーの背後に追加する）とともに、対応する DNS レコードを追加してください。ドメインの名前解決ができるようになったら、上記のクライアント設定の url を更新してください。
2. 初回デプロイの確認。 初回のデプロイが正常に完了したら、GET https://<service-url>/health が 200 を返すことと、有効なベアラートークンを指定した POST /mcp でツールの一覧が返されることを確認してください。

ChatGPT コネクター（OAuth）チェックリスト（内部テスト用）

このチェックリストは、公開されている VideoGen plugin をテストする VideoGen のエンジニア向けです。ユーザーは ChatGPT プラグインディレクトリからこのプラグインをインストールします。

ある環境（例：DEV → https://dev.mcp.videogen.io/mcp）向けにリモート MCP サーバーをデプロイした後、次の手順を実施してください。

1. ディスカバリーと認証モードを確認します。
   • GET https://<mcp-host>/.well-known/oauth-protected-resource/mcp が 200 を返し、resource が /mcp で終わり、authorization_servers が MCP オリジン（パスなし。Cursor の回避策）と一致することを確認します。
   • GET https://<mcp-host>/.well-known/oauth-protected-resource/mcp/chatgpt が 200 を返し、resource が /mcp/chatgpt で終わり、authorization_servers が Supabase Auth の issuer（…/auth/v1）と一致することを確認します。
   • GET https://<mcp-host>/.well-known/oauth-authorization-server が 200 を返し、issuer が MCP オリジンと一致し、authorize/token/register エンドポイントが Supabase Auth 上にあることを確認します。
   • npx -y @modelcontextprotocol/[email protected] --cli https://<mcp-host>/mcp/chatgpt --transport http --method tools/list で約35個以上のツールが一覧表示されることを確認します（noauth の open_uploader と、oauth2 の API ツールを含む）。
   • /mcp への匿名の POST はすべて、initialize と tools/list を含め、HTTP 401 と WWW-Authenticate を返すことを確認します。これにより、Cursor／Claude が直ちに OAuth を開始します。
   • /mcp/chatgpt に対する匿名の tools/call get_me が、ツール結果内の _meta["mcp/www_authenticate"] チャレンジを含む HTTP 200 を返すことを確認します（ChatGPT 用）。
2. ChatGPT アプリ（例：VideoGen (DEV)）で、MCP URL に https://<mcp-host>/mcp/chatgpt（/mcp ではありません）を設定します。正確な OAuth コールバック URL（https://chatgpt.com/connector/oauth/{callback_id}）を、その環境の Supabase Auth OAuth クライアントのリダイレクト許可リストにコピーします。
3. ChatGPT コネクタービルダーでは、DCR を優先してください（Supabase は registration_endpoint を通知しますが、CIMD／client_id_metadata_document_supported は通知しません）。ChatGPT がアプリ用のクライアントを DCR で登録した後、その正確な client_id を core/src/logic/oauth/trustedOAuthClientIds.ts の TRUSTED_OAUTH_CLIENT_IDS に追加し、同意画面で検証済みとして扱われるようにします。
4. ChatGPT の「設定」→ アプリ → Refresh → Scan Tools の順に操作し、表示されたら OAuth プロンプトを完了します。
5. 新しい会話を開始し、ツールメニューからアプリを選択して、読み取りツール（例：get_me）を呼び出します。メタデータを変更した後は、古いチャットを再利用しないでください。

STANDARD_TESTS は、mcp-http（pnpm --filter @videogen/api mcp:test -- --transport http --env <env> --server-mode remote）を通じて /mcp/chatgpt に対する匿名の ChatGPT ディスカバリーを自動的に実行します。これは、認証済みの完全なスモークテストの前に Inspector CLI を実行し、open_uploader が noauth を、API ツールが oauth2 を通知することを検証します。このスキームのチェックは、このメタデータを反映して再デプロイされていないホストでは失敗します。