3行でいうと

  • Claude.aiからは、「+」→「Connectors」→「Manage connectors」→「+ Add custom connector」で、名前を HeyGen、URLを https://mcp.heygen.com/mcp/v1/ と入れ、「Connect」を押してHeyGenの画面で承認します（公式の「MCP: Claude」のページ）。APIキーは要らず、認証はOAuthのみです（公式の「HeyGen Remote MCP」のページ。「MCP: Claude」のページは認証の方式の名前を書いていません）。
  • コーディング用のエージェントからは、Skillsの公式READMEが、Claude Codeの例として claude mcp add --transport http heygen https://mcp.heygen.com/mcp/v1/ を載せています。CLIとAPIキーの経路もあります。
  • 課金の経路が違います。MCP（OAuth）はHeyGenの現在のプランのクレジット、CLIをAPIキーで使うとAPI利用として別に課金、と公式のSkillsの資料にあります。
  • HyperFramesには、HeyGen本体のMCPとは別のホスト型MCP（https://mcp.heygen.com/mcp/hyperframes/、beta）があり、Claude、ChatGPT、Grokで使えると書かれています。
  • 連携の「外し方」は、読んだ公式ページの多くに書かれていません。書かれていないものは、「記載が見つからない」と書き、ホスト側（Claudeなど）の設定を見る形になります。

この記事は、公式の資料を2026年10月25日に読んでまとめたものです。この記事は、実際に使って確かめた記録ではありません。コマンドと設定は、「公式の例の写し」と「この記事の案」を区別して書きます。ページは要約の形で読んだので、システムへ何かを登録する操作（プラグインのマーケットプレイスの追加、シェルスクリプトの実行など）は、必ず公式の原文を見てください。画面の表記は変わります。手元の画面と照らして読んでください。

先に結論

前提：用語をそろえる

入口の一覧：認証、課金、公式が書くこと

入口 認証 課金（公式の記載） 対応クライアントなど
API APIキー（X-Api-Key ヘッダー） クイックスタートに課金の記載なし（API料金の資料は03・04） 自分のプログラム
リモートMCP（https://mcp.heygen.com/mcp/v1/） OAuthのみ。APIキーは不要 現在のHeyGenのプランのクレジットから。概要の冒頭とFAQは「追加の費用はない」趣旨。同じページの比較表は課金を「Web plan + premium credits」と書く。ツールごとの条件あり Claude（Web、Desktop、Code）、Codex CLI、Cursor、Gemini CLI、Lovable、Manus、Superhuman、OpenAI、ほか
CLI（heygen） APIキー、またはブラウザのOAuth Skillsの資料は、キーのCLIをAPI利用として別に課金と書く macOS、Linux。Windowsは未対応でWSLを案内
Skills（heygen-com/skills） MCPのOAuth、またはCLI 優先順位は下の表 Claude Code、Cursor、Codex、Gemini CLIなど12以上
HyperFrames（ローカル） 不要（ローカルで組む）。書き出しの方法で変わる HyperFramesのヘルプ記事に、クレジットの記載なし Claude Code、Cursor、Gemini CLI、Codexなど
HyperFramesのMCP（beta） OAuth（HeyGenのサインイン） 記載が見つからない。「プラン、上限、課金は変わりうる」とある Claude、ChatGPT、Grok

連携1：API（APIキーで、プログラムから動画をつくる）

公式の「Quick start」の順です。

1-1. APIキーを用意する

  1. 「API keys」のページを開く。クイックスタートは、https://platform.heygen.com/api-keys と書いています。（なお、Skillsの公式READMEは、キーの入手先を app.heygen.com/api と書いています。ページ同士で書き方が違うので、画面の案内に従ってください。）
  2. キーを作る。作ったキーは、人に見せず、コードやブログに貼らない。
  3. ターミナルに覚えさせる（クイックスタートの形）。
export HEYGEN_API_KEY="<YOUR_API_KEY>"

クイックスタートからリンクされた「API Key」のガイド（https://developers.heygen.com/docs/api-key）も読みました。要点は次のとおりです。

なお、Skillsの公式READMEは、キーの入手先を app.heygen.com/api（Settings → API）と書き、モーダルを閉じるとキーは再表示できない、と書いています（取得時の要約）。クイックスタートとAPIキーのガイドの platform.heygen.com/api-keys とは書き方が違います。どちらかに決めず、手元の画面の案内に従ってください。

1-2. 動画をつくる（Video Agent）

公式のクイックスタートの例です。ベースURLは https://api.heygen.com、ヘッダーは X-Api-Key です。

curl -X POST "https://api.heygen.com/v3/video-agents" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A presenter explaining our product launch in 30 seconds"}'

返ってくる形（クイックスタートの例）は、data の中に session_id、status（generating）、video_id（最初は null）です。session_id を控えます。作成中の様子は https://app.heygen.com/video-agent/{session_id} で見られる、とあります。

1-3. 結果を取る

  1. セッションから video_id を取る。video_id が null でなくなるまで繰り返す。
curl "https://api.heygen.com/v3/video-agents/<SESSION_ID>" \
  -H "X-Api-Key: $HEYGEN_API_KEY"
  1. 動画の状態を見る。
curl "https://api.heygen.com/v3/videos/<VIDEO_ID>" \
  -H "X-Api-Key: $HEYGEN_API_KEY"
  1. 完了すると status が completed になり、video_url にMP4が置かれます。failed のときは、failure_code と failure_message を見ます。

1-4. 通知で受け取る（callback_url）

作成のリクエストに callback_url を付けると、動画ができたときにWebhookが届き、ポーリング（繰り返し確認）が要りません。これは、そのリクエストだけの1回限りの通知で、callback_id を付けると通知に同じ値が返ります（公式の「Webhooks」のガイド）。

同じガイドは、リクエストごとではなく、受け取り先（エンドポイント）を登録する方法も書いています。

項目 公式の記載（Webhooksのガイド、確認日 2026-10-25）
登録 POST https://api.heygen.com/v3/webhooks/endpoints。必須は url（公開のHTTPSの宛先）。任意で events（省略かnullで全イベント）と entity_id（1つの資源に絞る）。OAuthのベアラートークンも使える、とある
秘密の値 応答に secret が入り、表示されるのはその1回だけ。通知の検証に使うので、安全に保管する
一覧・更新 一覧は limit（1〜100、既定10）と token。一覧では secret は null。更新では events の配列が丸ごと置き換わる
削除（外し方） エンドポイントを削除すると、そのURLへの配信は止まる。恒久的な削除（permanently）と書かれている。個別の経路名は原文で確認
秘密の入れ替え 新しい secret が発行され、古いものはすぐ無効になる
検証 各通知の signature ヘッダーに、生のリクエスト本文を、エンドポイントの秘密で計算したHMAC-SHA256（16進）が入る。ページは、再整形したJSONではなく生のバイト列で検証するよう書く
再送 2xxを10秒以内に返さないと失敗とみなされ、最大24時間、間隔を空けて再送される。重複することがある
通知の中身 event_type と event_data（video_id を含む）。例として avatar_video.success、avatar_video.fail、video_agent.success。全イベントの一覧は別のページ（読んでいません）

1-5. Video Agentのリクエストの項目（公式のガイド）

項目 必須 公式の説明
prompt 必須 1〜10,000文字
mode 任意 generate（既定、一発で作る）または chat（複数回のやりとり。確認で止まる）
avatar_id、voice_id 任意 省くとエージェントが選ぶ
style_id 任意 GET /v3/video-agents/styles で取る
brand_kit_id 任意 ブランドの色、フォント、ロゴを当てる
brand_glossary_id 任意 ナレーションでの用語の読み方。字幕は元の綴りのまま
orientation 任意 landscape か portrait。省くと自動
files 任意 最大20個。URL、アセットID、base64。形式はpng、jpeg、mp4、webm、mp3、wav、pdf
callback_url、callback_id 任意 完了・失敗のWebhook、通知に添える呼び出し側のID
incognito_mode 任意 trueで、メモリの注入と抽出を止める

1-6. アバターを作るAPIと、同意

公式の「Create Avatar」の要約です。

目的 エンドポイント
アバターを作る（動画、写真、プロンプト） POST /v3/avatars（type で区別）
同意を送る POST /v3/avatars/{group_id}/consent
ルックを作る・見る・直す POST /v3/avatars/looks、GET /v3/avatars/looks/{look_id} など
ルックを消す DELETE /v3/avatars/looks/{look_id}
キャラクターとそのルックをすべて消す DELETE /v3/avatars/{group_id}

1-7. 使用上限・外し方

連携2：リモートMCP × Claude（Claude.ai）

公式の「MCP: Claude」のページの順です。このページが書くのは、ClaudeのWebでの設定です。

条件

手順

  1. Claudeで、「+」→「Connectors」→「Manage connectors」→「+ Add custom connector」を開く。
  2. 名前を HeyGen にする。
  3. URLに、次を入れる。
https://mcp.heygen.com/mcp/v1/
  1. 「Connect」をクリックする。HeyGenの認可ページが開くので、アクセスを承認する。
  2. Claudeに、動画を頼む。公式のページの例は、次の1文です。
Generate a video using HeyGen MCP about the difference between Skills and MCP.
  1. Claudeが、アバターを選び、台本を書き、レンダリングする、とあります。完成した動画は、HeyGenの「Projects」にも出ます。

Always Allow

HeyGenのコネクタを「Always Allow」にすると、許可の確認が出なくなる、とあります。確認をなくすと、AIが確認なしに生成を実行できる、という点は、03の読みと同じです（生成にはクレジットがかかる。公式のMCPのページは、使った分が現在のプランのクレジットから引かれる、と書いています）。

渡るもの、権限

外し方

この「MCP: Claude」のページ、およびMCPの概要のページには、コネクタの削除やOAuthの取り消しの手順は、書かれていません。記載が見つからないので、Claude側の「Manage connectors」の画面と、HeyGen側のアカウントの設定を、手元で探す形になります。

うまくいかないとき（公式のMCPの概要の、ツールごとの注記）

症状 公式の記載
HTTP 400 要求した音声エンジンが、非対応、プランで不許可、または言語・地域と合わない
HTTP 403（ai_vendor_access_restricted） ワークスペースのベンダー方針で、そのモデルが止められている
HTTP 409（resource_not_ready） 動画の編集用ドキュメントが準備中。あとで再試行
HTTP 429（rate_limit_exceeded） 指数的に間隔を空けて再試行。音声は、1メンバーあたり1分30回
HTTP 503 一時的な失敗。再試行
create_model_video MCP経由では5〜15秒。長いものはHTTP APIが要る
create_avatar_looks OAuth接続ではワークスペースのクレジットを使い、無料枠のMCPからは使えない
convert_model_speech OAuthでは有料プランが要る

連携3：リモートMCP × そのほかのクライアント（Claude Code、Codexなど）

公式のMCPの概要の、共通の手順

  1. エージェントの、ConnectorsまたはMCP servers の設定を開き、「Add custom connector」を選ぶ。
  2. 名前を HeyGen にして、サーバーのURLを入れる。
  3. 「Connect」を押して、HeyGenにサインインし、アクセスを承認する。
  4. エージェントに、動画づくりを頼む。

対応のクライアントとして、Claude（Web、Desktop、Code）、Codex CLI、Cursor（Cursorのマーケットプレイス経由）、Gemini CLI、Lovable、Manus、Superhuman、OpenAI、「ほか」が挙げられています。各クライアントの画面の詳細は、このページには書かれていません。

Claude Codeの場合

「MCP: Claude」のページには、Claude CodeとClaude Desktopの設定は書かれていません。一方、Skillsの公式READMEに、Claude Codeの例が載っています（取得時の要約。原文で確認してください）。

claude mcp add --transport http heygen https://mcp.heygen.com/mcp/v1/

これは公式READMEの記載を写したものです（再取得でも同じ形で読めました。ただし要約経由なので、実行前に原文を確認してください）。READMEは、APIキーが設定されていないときにスキルがMCPを自動で見つける、最初の呼び出しでブラウザのOAuth同意の流れが始まる、と書いています（OpenClawの例の続きに書かれた文です）。Claude Codeの画面でOAuthがどこに出るかは、書かれていません。

OpenClawの場合（公式READMEの記載）

OpenClawの設定ファイル ~/.openclaw/openclaw.json に、heygen というMCPサーバーとして https://mcp.heygen.com/mcp/v1/ を登録する形が、READMEに載っています。再取得で読めた形は次のとおりです（要約経由です。既存の設定ファイルがある場合は、追記の仕方を含め、原文で確認してください）。

json { "mcp": { "servers": { "heygen": { "url": "https://mcp.heygen.com/mcp/v1/" } } } }また、OpenClawのプラグイン（MCP対応つき）の導入コマンドも、READMEにあります（openclaw plugins install clawhub:@heygen/openclaw-plugin-heygen）。

外し方

記載が見つからない。Claude Code側のMCP登録の外し方は、今回、HeyGenの公式ページにもAnthropicの資料にも当たっていないので、この記事では書きません。

次の記事（その2）

CLI（heygen コマンド）、Skills、HyperFrames、組み合わせの案は、08「HeyGenをClaudeなどのAIとつなぐ手順（その2）」にあります。

気をつけること

出典