HyperFrames MCP Integration for AI Agents

Submit concise product feedback to HeyGen after the user gives feedback or you observe a meaningful terminal failure that did not recover. Set source=user only for feedback the user actually expressed; use source=agent for your own observation. Always include `toolName` and `resourceIds` when a project, session, video, or other resource exists for this issue — a report with no resource ID and no tool name is usually not root-causable later. Include the exact observed error, but never credentials, raw media, unrelated conversation text, or an invented cause or user opinion. For usability or performance complaints (e.g. "too slow", "stuck", "hung"), also include `pipelineStep` (which stage was slow — compose, magic_edit, render_video, or other) and `elapsedSeconds` (how long it actually took), and set `expectedBaseline` when the user states or implies what they expected (e.g. "usually under 2 minutes", "faster in the web app") — these turn a vague "too slow" into a diagnosable report. Do not report expected validation, consent, or billing guidance unless the user says it is a problem. If you know the current host application and surface, provide `reportedClientName` and `reportedClientSurface`; otherwise omit them. Report the host, such as ChatGPT, Codex desktop, Codex CLI, Claude, or Grok, never the model name and never an inferred client. Submit once per issue and do not retry a failed feedback submission in a loop. Submission is best effort and does not confirm durable storage or operator review. Do not automatically report historical failures found while browsing. Follow the client consent policy and briefly tell the user after submitting feedback.

Author or edit a HyperFrames video project. The HyperFrames agent handles captions, blocks, layout, asset attachment, transitions, color, and timing internally based on the natural-language prompt. ### WHEN TO CALL: - The user asks to create, change, or refine a HyperFrames video project. - The user provides a specific topic, narrative, edit instruction, or style direction. ### NEVER CALL WHEN: - The request is vague or doesn't describe what the project should be or change to. Stay in chat and help the user clarify their intent before calling this tool. ### PROJECT LIFECYCLE: - First call (new project): Leave project_id empty. A new HyperFrames project will be created and the prompt will be applied as the initial authoring instruction. - Subsequent calls (editing): Pass the project_id returned from the previous tool call. The prompt is interpreted as an edit applied to the existing project. ### RETURN VALUE: This tool returns immediately while the project runs in the background (typically a few minutes). The response indicates the run has *started*, not that the video is ready — at this point the project is in progress, not done. Compose renders the MP4 automatically as part of the run, so no separate render step is needed; the downloadable MP4 will be available once the project completes. ### MEDIA (user-supplied images and video): - The agent runs in the cloud and does not download, re-host or process files the prompt links to. A scene can show a user-supplied image or a muted video clip only by using its direct, publicly-fetchable absolute https:// file URL (or the URL of an uploaded HeyGen asset) as-is, so the prompt links the file itself. - Share-page links (Google Drive, Dropbox, YouTube, ...) are viewer pages, not media files, and never render. Compose does not edit the user's own footage: it cannot trim, cut or transcribe a linked video. - Audio files linked in the prompt are not used: narration and music come from the agent's own audio pipeline. - A file that only exists on the user's machine — a local path such as /root/.claude/uploads/... (where chat attachments land), C:\Users\... or ~/Downloads/..., or a bare filename like "IMG_1234.mov" — is not reachable. Upload it first with the asset upload tools (`create_asset_upload`, PUT the bytes to the returned upload_url, then `complete_asset_upload`) and pass the returned asset `url` in the prompt. - Inaccessible required media causes generation to fail; it is not silently removed or replaced. ### INPUTS: - prompt: (Required) The user's instruction describing what the project should be or how it should change. - project_id: (Optional) Project ID from a previous tool call to continue editing the same project. - design_source: (Optional) Brand style preset for the HyperFrames agent — file stem of a specimen under the agent's design set. On a NEW project, omitting it defaults to one of the vetted house styles (`claude`, `blockframe`, or `monochrome`, chosen per new project) so the output lands on a coherent branded look. On a follow-up edit (when `project_id` is set), omitting it leaves the project's existing style untouched — only pass a value on an edit to deliberately reskin. Pass a value when (a) the user names a style explicitly ("use blockframe", "make it monochrome"), or (b) a new project's content has a clear register mismatch with the default and one of the presets is obviously the right vibe. Unknown values are tolerated — the agent falls back to inventing — so this is a free-form string, not a fixed enum. Known presets and when to pick each: - `blockframe` — neo-brutalist pop-zine. Cream canvas, thick black borders, hard drop-shadows, bright accent blocks (pink/yellow/green), Anton + Inter + DM Mono. Picks: energetic consumer content — product launches, fashion / music drops, hand-stamped marketing, anything loud and playful. - `claude` — warm editorial paper-and-ink. Cream paper, warm charcoal ink, single clay accent, Newsreader serif display + Hanken Grotesk body. Calm, literary, soft edges, no hard shadows. Picks: Claude / Anthropic-branded work, thoughtful product narratives, essays, anything where "calm and literary" beats "loud." - `mat` — material-tactile portfolio. Deep forest-green canvas with a wood-brown atmospheric glow, single burnt-copper accent, Bricolage Grotesque display + DM Sans body, no shadows / no rounded corners. Picks: industrial design, hardware reveals, premium-product launches, anything that should feel tactile and crafted. - `monochrome` — black-ink-on-cream scholarly monograph. Warm off-yellow cream paper, dark olive-black ink, NO chromatic accent, ultra-light Jost + Lora italic + JetBrains Mono. Generous whitespace, hairline rules. Picks: whitepapers, research notes, year-in-review essays, anything that should read as serious long-form rather than a slide deck. - `signal` — sober editorial briefing. Deep editorial-navy + warm aged-cream dual surface, one restrained antique-gold accent (rules / italics / numerals), Source Serif 4 + DM Sans + IBM Plex Mono. Picks: analyst reports, policy / finance / intelligence briefings, anything in The-Economist or private-intelligence-memo register.

Read the current state of a HyperFrames project: whether the agent is still working, waiting for the user's input, idle and ready to render, or has failed. Returns the session-level status, the most recent message from the agent, and a paginated chat history. ### WHEN TO CALL: - The user explicitly asks "is it done?" / "what's happening?" / "what did the agent ask?". - To confirm the compose run (which renders the MP4 automatically) has finished and the downloadable video is ready, rather than assuming completion the moment compose returns. ### NEVER CALL WHEN: - The user hasn't asked — the project canvas widget already tracks state live. ### POLLING CADENCE: This tool performs server-side long polling on first-page calls (no cursor): it waits up to 20 seconds for the compose run to leave an in-progress state before returning. When the run is still in progress after that wait, the response includes `retry_after_seconds=15` indicates how long to wait before calling again; polling faster than that has no effect. If `session_status` hasn't changed after ~5 minutes of polling, a reasonable next step is to ask the user whether to keep waiting or move on. ### SESSION_STATUS VALUES: - `processing` / `pending`: agent is still working; the next poll comes after the wait. - `waiting`: agent is asking the user something — `latest_agent_message` holds the question, and the user's answer is passed to a follow-up `compose` call. - `draft` / `completed`: project is idle and the MP4 render (kicked off automatically by compose) is done. When the CDN preview URL is available, it is returned inline in `widget_data` — no `get_project` call needed. When `widget_data` is absent (preview not yet generated), `get_project` fetches the result for display; a follow-up `compose` call is the next step for further edits. - `error` / `failed`: project failed. The tool's text output is a generic, user-safe message and is what reaches the user. `latest_agent_message` carries the raw internal failure reason and is diagnostic-only (it can contain internal pipeline detail), not for user display. - `deleted`: project no longer exists. ### INPUTS: - project_id: (Required) The project ID returned by `compose`. - limit: (Optional, default 10, range 1-100) Page size for the chat history. - cursor: (Optional) Opaque cursor returned as `next_cursor` in a prior call. Omit on the first call to fetch the most recent page. ### OUTPUT: - session_status: see values above. - latest_agent_message: most recent role=model message (TEXT / ERROR_MESSAGE / PAYWALL). When `session_status=waiting` and the latest message isn't on the most recent page, the tool automatically peeks one page further back to find it. Null when no such message exists in the polled window. On `error`/`failed` this is the raw internal failure reason and is diagnostic-only; the user-facing message is the tool's generic text output, not this field. - latest_agent_message_chat_type: chat_type of `latest_agent_message`. Always one of `text`, `error_message`, or `paywall`, or null. Internal types (`reasoning`, `tool_update`, `suggestions`, `generated_resources`) are filtered out here; see `messages[].chat_type` for the unfiltered chatter. - latest_run_status: most recent run status from any message in the page. - messages: the page (oldest within page first, newest last). - next_cursor: paginate further back through history; null when exhausted.

Read the current state of a HyperFrames project: whether the agent is still working, waiting for the user's input, idle and ready to render, or has failed. Returns the session-level status, the most recent message from the agent, and a paginated chat history. ### WHEN TO CALL: - The user explicitly asks "is it done?" / "what's happening?" / "what did the agent ask?". - To confirm the compose run (which renders the MP4 automatically) has finished and the downloadable video is ready, rather than assuming completion the moment compose returns. ### NEVER CALL WHEN: - The user hasn't asked — the project canvas widget already tracks state live. ### POLLING CADENCE: This tool performs server-side long polling on first-page calls (no cursor): it waits up to 20 seconds for the compose run to leave an in-progress state before returning. When the run is still in progress after that wait, the response includes `retry_after_seconds=15` indicates how long to wait before calling again; polling faster than that has no effect. If `session_status` hasn't changed after ~5 minutes of polling, a reasonable next step is to ask the user whether to keep waiting or move on. ### SESSION_STATUS VALUES: - `processing` / `pending`: agent is still working; the next poll comes after the wait. - `waiting`: agent is asking the user something — `latest_agent_message` holds the question, and the user's answer is passed to a follow-up `compose` call. - `draft` / `completed`: project is idle and the MP4 render (kicked off automatically by compose) is done. When the CDN preview URL is available, it is returned inline in `widget_data` — no `get_project` call needed. When `widget_data` is absent (preview not yet generated), `get_project` fetches the result for display; a follow-up `compose` call is the next step for further edits. - `error` / `failed`: project failed. The tool's text output is a generic, user-safe message and is what reaches the user. `latest_agent_message` carries the raw internal failure reason and is diagnostic-only (it can contain internal pipeline detail), not for user display. - `deleted`: project no longer exists. ### INPUTS: - project_id: (Required) The project ID returned by `compose`. - limit: (Optional, default 10, range 1-100) Page size for the chat history. - cursor: (Optional) Opaque cursor returned as `next_cursor` in a prior call. Omit on the first call to fetch the most recent page. ### OUTPUT: - session_status: see values above. - latest_agent_message: most recent role=model message (TEXT / ERROR_MESSAGE / PAYWALL). When `session_status=waiting` and the latest message isn't on the most recent page, the tool automatically peeks one page further back to find it. Null when no such message exists in the polled window. On `error`/`failed` this is the raw internal failure reason and is diagnostic-only; the user-facing message is the tool's generic text output, not this field. - latest_agent_message_chat_type: chat_type of `latest_agent_message`. Always one of `text`, `error_message`, or `paywall`, or null. Internal types (`reasoning`, `tool_update`, `suggestions`, `generated_resources`) are filtered out here; see `messages[].chat_type` for the unfiltered chatter. - latest_run_status: most recent run status from any message in the page. - messages: the page (oldest within page first, newest last). - next_cursor: paginate further back through history; null when exhausted.

Check the render status of a HyperFrames video that was previously submitted via `render_video`, and — when the render is complete — retrieve the presigned MP4 download URL. NOTE: Automatic polling for progress is unnecessary — the render-progress widget that appears in the chat self-polls and shows the finished video on its own. This tool is the path for an explicit user (or upstream-agent) request for the download link, the MP4 URL, the file, or to share/send/provide/read out the video: it returns the `video_url` to surface directly in the reply. The widget is a convenience, not a substitute for the link the user asked for, so in that case the URL belongs in the reply itself — do not redirect the user to the widget. ### WHEN TO CALL: - The user explicitly asks "is my video ready?" / "what's the status of my render?" - The user explicitly asks for the download link, the MP4 URL, or to share/send the video. - An upstream agent prompt instructs you to provide the user with the download link for a finished render — call this tool, then surface the `video_url` in your text reply. - The user wants to check on a render from a previous conversation. ### POLLING CADENCE: When the render is still in progress, the response includes `retry_after_seconds=30` — wait that long before calling again if the user asks you to keep checking. Do not poll faster than `retry_after_seconds` indicates; one poll per minute is plenty. ### INPUTS: - project_id: (Required) The project ID the render belongs to. - video_id: (Required) The video_id returned by `render_video`. ### OUTPUT: - render_status: One of pending / rendering / completed / failed (terminology may vary). - video_url: Presigned MP4 download URL — populated once the render completes. Present this to the user as a download link so they can save the video file. Use the URL exactly as returned (the query params are required signing params).

Check the render status of a HyperFrames video that was previously submitted via `render_video`, and — when the render is complete — retrieve the presigned MP4 download URL. NOTE: Automatic polling for progress is unnecessary — the render-progress widget that appears in the chat self-polls and shows the finished video on its own. This tool is the path for an explicit user (or upstream-agent) request for the download link, the MP4 URL, the file, or to share/send/provide/read out the video: it returns the `video_url` to surface directly in the reply. The widget is a convenience, not a substitute for the link the user asked for, so in that case the URL belongs in the reply itself — do not redirect the user to the widget. ### WHEN TO CALL: - The user explicitly asks "is my video ready?" / "what's the status of my render?" - The user explicitly asks for the download link, the MP4 URL, or to share/send the video. - An upstream agent prompt instructs you to provide the user with the download link for a finished render — call this tool, then surface the `video_url` in your text reply. - The user wants to check on a render from a previous conversation. ### POLLING CADENCE: When the render is still in progress, the response includes `retry_after_seconds=30` — wait that long before calling again if the user asks you to keep checking. Do not poll faster than `retry_after_seconds` indicates; one poll per minute is plenty. ### INPUTS: - project_id: (Required) The project ID the render belongs to. - video_id: (Required) The video_id returned by `render_video`. ### OUTPUT: - render_status: One of pending / rendering / completed / failed (terminology may vary). - video_url: Presigned MP4 download URL — populated once the render completes. Present this to the user as a download link so they can save the video file. Use the URL exactly as returned (the query params are required signing params).

Turn a Claude Design into a HeyGen HyperFrames video project. Author the design as a valid HyperFrames composition and send it as RAW, self-contained HTML (e.g. index.html), NOT a bundled/splash-loader artifact — the importer reads static HTML and cannot see a composition root that a bundle only assembles at runtime. Critical rules (author to these): - Root element carries data-composition-id, data-width + data-height (fixed-px canvas), data-start, data-duration. - Register every timeline on window.__timelines[compositionId]. - Deterministic only: no Date.now()/Math.random(); any media autoplays muted. - Real motion (entrance animations + scene transitions), not a static page. - Preserve the source brand exactly (palette, fonts, copy, real assets); no stock/template substitution. - Fonts: inline every brand font as a base64 data: URI in an @font-face rule — a Google Fonts <link> is NOT sufficient (a linked font falls back to a system face and renders non-deterministically). Inlining the brand font is what preserves fidelity. - Every other asset must be resolvable: reference each image/video/audio as an inline data: URI OR a publicly-fetchable absolute URL — never a bare relative path (e.g. "uploads/logo.png") or a variable pointing at a local file (those arrive empty and render blank). Full guide (skeletons, timeline/shader contract, worked examples): before authoring, call the `get-send-to-hyperframes-guide` tool — it returns the guide as its result (no fetch/search needed). PREREQUISITE — the URL must be the one Claude Design's "Send to" hands over, on https://*.claudeusercontent.com. Any other host is rejected, so uploading the HTML to a file host or pasting a link you produced yourself will NOT work. Without such a URL this tool is not the right path: use `compose` to build the project from a description of the video instead. Given a valid Send-to URL it lints the composition and, if not yet renderable, returns the specific errors to fix and resubmit; on success it returns an openable link to the imported HyperFrames project.

Get the status of a design import started by import-claude-design-from-url. Returns processing | done | failed, plus an openable link to the design when done.

Import an MP4 video into HyperFrames Studio from a URL. HyperFrames Studio is HeyGen's desktop video editor. Call this from Claude Motion's Send to, with the arguments it provides. The video becomes a new HyperFrames project, and the tool returns a link. Show that link to the user: it opens a page that launches the HyperFrames Studio desktop app, or offers to download it if it is not installed. In Studio they can trim the video, add titles, music and sound effects, and keep editing with AI. Sending the same video again (same claude_design_project_id) updates the same link; opening it again adds a new copy of the project in Studio. The link works for 90 days after the last send. If the tool returns an error, show its message to the user as is; it says what to do, such as sending again in a minute or reconnecting HyperFrames. Do not retry on your own.

List the user's HyperFrames video projects, newest first. Projects are the videos the user has created in HeyGen via the HyperFrames connector — each one represents an in-progress or finished video project. ### WHEN TO CALL: - The user asks to see their videos, projects, drafts, or recent work ("show me my videos", "what projects do I have", "list my drafts", "what have I been working on"). - You need to find a project_id before calling another HyperFrames tool (`get_project`, `compose`, or `render_video`). - Paginating through a previous result via `next_cursor`. ### NEVER CALL WHEN: - The user wants to author a new project — that's the `compose` tool. - The user already gave you a specific project_id — call `get_project` directly. ### INPUTS: - limit: (Optional, default 20, range 1-100) Page size. - cursor: (Optional) Opaque pagination cursor returned as `next_cursor` in a prior `list_projects` response. Omit on the first call. ### OUTPUT: - A list of ProjectRef entries (project_id, title, status, timestamps, thumbnail/preview URLs) plus a `next_cursor` for further pagination. The text response summarises the count and surfaces `next_cursor` so you can decide whether to paginate.

Fetch a single HyperFrames video project by ID and render it inline using the HyperFrames player widget. Returns the project metadata plus a player that loads the current preview. ### WHEN TO CALL: - The user asks to view, open, or play a specific project by ID or by reference ("show me project abc123", "open my latest project", "play that video again"). - After `list_projects`, when the user picks one they want to look at. - After `compose` or `render_video` calls, to re-display the result. ### NEVER CALL WHEN: - You don't have a project_id — call `list_projects` first. - The user wants to edit the project — that's the `compose` tool. ### INPUTS: - project_id: (Required) Project ID. Must be a real ID owned by the caller's HeyGen space; bogus IDs return a clear error. ### OUTPUT: - A ProjectRef (project_id, title, status, timestamps, thumbnail/preview URLs) and a `hyperframes-player` widget configured to play the project. Both the thumbnail_url and the preview HTML are regenerated server-side at request time, so re-calling this tool always returns fresh media.

Render an existing HyperFrames project to a downloadable MP4 video. This is a paid action that kicks off a cloud render workflow; the render runs in the background and typically completes in a few minutes. The render-progress widget displayed in the chat self-polls for completion and shows the finished video, so polling is not required just to learn when it finishes. When the user (or an upstream agent) explicitly asks for the download link/URL after the render has finished, `get_render_status` returns the `video_url` to surface directly in the reply. The widget is a convenience, not a substitute for the link — when the user has asked for the URL, the correct response is to provide it; do not redirect the user to the widget in that case. ### WHEN TO CALL: - The user explicitly asks to render, export, finalize, or download the video. - The user wants the final MP4 (not just a preview.) - The most recent `compose` run for this project has finished. ### NEVER CALL WHEN: - The user is still iterating on the project. Use `compose` for further edits before rendering. - A project has not been created yet. Call `compose` first. - The user is just asking what the project looks like — they already see the inline preview. - A `compose` run is still in flight for this project (session status `waiting` or `processing`). The render will be rejected. The project canvas widget in the chat shows the agent's current state — if it indicates the agent is still working or waiting for the user, wait for completion (or, if waiting, get the user's answer and call `compose` again with it) before attempting to render. ### INPUTS: - project_id: (Required) The project ID returned by `compose` (or a previous render call).

Returns the full Claude Design "Send to HyperFrames" authoring guide as text: the composition contract, worked skeletons/examples, timeline + shader-transition patterns, and the determinism and fidelity rules (inline base64 fonts, preserve brand substance, etc.). **Scope — only for the "Send to HyperFrames" authoring flow:** call this when you are authoring a Claude Design composition to import via `import-claude-design-from-url`. Do NOT call it for other HyperFrames work (compose, render, or editing an existing project) — it is not relevant there. When it IS applicable, **call it FIRST, before authoring** — read the returned guide and author to it, rather than guessing the contract from memory or web search. Takes no arguments; returns the guide text directly (no URL to fetch).