Skip to content

Commit b7ae24d

Browse files
jrusso1020jrusso1020
authored
Merge pull request #548 from heygen-com/docs/hyperframes-mcp
docs(guides): add HyperFrames MCP guide
2 parents e25a3b3 + 71881ea commit b7ae24d

1 file changed

Lines changed: 309 additions & 0 deletions

File tree

‎docs/guides/mcp.mdx‎

Lines changed: 309 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,309 @@
1+
---
2+
title: HyperFrames MCP
3+
description: "Author, preview, and render HyperFrames videos directly inside Claude.ai and ChatGPT — no local install required."
4+
---
5+
6+
The HyperFrames MCP is a hosted [Model Context Protocol](https://modelcontextprotocol.io) server that lets you create, edit, preview, and render HyperFrames video compositions from inside Claude.ai or ChatGPT.
7+
8+
<Note>
9+
**In beta.** Features and pricing may change. Found a bug or have feedback? [File an issue on GitHub](https://github.com/heygen-com/hyperframes/issues).
10+
</Note>
11+
12+
## What you can do
13+
14+
- Create compositions from natural-language prompts
15+
- Edit existing compositions conversationally — *"make the title 2x bigger"*, *"add hype-style captions"*
16+
- Preview the result inline in the chat with a video player widget
17+
- Render to `mp4`, `webm`, or `mov` — output URL streamed back to chat
18+
- Revisit compositions you've created previously
19+
- Check your render credits
20+
21+
The agent behind `compose` has 25+ HyperFrames-specific skills baked in — typography, color palettes, motion principles, GSAP effects, audio-reactive animation, captions, voice generation. You don't have to specify any of this directly; describe the video you want and the agent picks the right tools.
22+
23+
<Note>
24+
Looking for the open-source CLI? See the [Quickstart](/quickstart). The MCP is a hosted product for zero-install authoring inside an LLM chat. The CLI gives you full control of rendering and runtime; the MCP gives you instant authoring with cloud rendering.
25+
</Note>
26+
27+
## Setup
28+
29+
### 1. Get a HeyGen account
30+
31+
The MCP requires a HeyGen account for authentication and credits. Sign up at [heygen.com](https://heygen.com) if you don't have one.
32+
33+
### 2. Add the connector
34+
35+
<Tabs>
36+
<Tab title="Claude.ai">
37+
<Steps>
38+
<Step title="Open Settings → Connectors">
39+
In Claude.ai web or desktop: **Settings → Connectors → Add custom connector**.
40+
</Step>
41+
<Step title="Enter the URL">
42+
Paste:
43+
```
44+
https://mcp.heygen.com/mcp/hyperframes
45+
```
46+
</Step>
47+
<Step title="Sign in to HeyGen">
48+
OAuth opens in a new window. Authorize the HyperFrames connector to access your HeyGen account.
49+
</Step>
50+
<Step title="Start a new chat">
51+
Open a new Claude.ai chat. Try:
52+
53+
> Make me a 10-second product intro for [your product] with bouncy captions and a high-energy soundtrack.
54+
</Step>
55+
</Steps>
56+
</Tab>
57+
<Tab title="ChatGPT">
58+
<Steps>
59+
<Step title="Open Apps & Connectors">
60+
In ChatGPT: **Settings → Apps & Connectors → Add MCP server**.
61+
</Step>
62+
<Step title="Enter the URL">
63+
Paste:
64+
```
65+
https://mcp.heygen.com/mcp/hyperframes
66+
```
67+
</Step>
68+
<Step title="Sign in to HeyGen">
69+
Authorize via OAuth.
70+
</Step>
71+
<Step title="Start a new chat">
72+
Open a new chat. Same prompts work as in Claude.ai.
73+
</Step>
74+
</Steps>
75+
</Tab>
76+
</Tabs>
77+
78+
## Available tools
79+
80+
The MCP exposes six tools to the LLM. You don't call them directly — the model picks the right tool based on your message.
81+
82+
| Tool | What it does | Cost |
83+
|---|---|---|
84+
| `compose` | Create a new composition or edit an existing one | Author credits |
85+
| `list_compositions` | List your previously created compositions | Free |
86+
| `get_composition` | Open a specific composition with an inline player | Free |
87+
| `render_video` | Submit a cloud render to mp4 / webm / mov | Render credits |
88+
| `get_render_status` | Poll a long-running render job | Free |
89+
| `get_credits` | Check your remaining credits and tier | Free |
90+
91+
### compose
92+
93+
Authors a new composition or applies an edit to an existing one. The HyperFrames agent handles voice selection, captions, blocks, layout, transitions, color, and timing internally based on your natural-language prompt.
94+
95+
**Triggered by prompts like:**
96+
97+
- "Make a 30-second product intro about [topic]" → creates a fresh composition
98+
- "Change the title font to a bold serif" → edits the most recent composition
99+
- "Add a flash transition before the call-to-action" → applies a structured edit
100+
101+
**Returns:** A composition reference (id, title, thumbnail) plus an inline player widget. Progress notifications stream during the run so you can see what the agent is doing — *"Drafting outline...", "Selecting voice and style...", "Generating HTML...", "Rendering preview frame..."*
102+
103+
### list_compositions
104+
105+
Lists compositions you've previously created. Newest first, paginated.
106+
107+
**Triggered by prompts like:** *"show me my recent videos"*, *"what did I work on yesterday?"*
108+
109+
### get_composition
110+
111+
Fetches metadata for a single composition along with an inline player widget.
112+
113+
**Triggered by prompts like:** *"open that video again"*, *"show me the one I made about [topic]"*
114+
115+
### render_video
116+
117+
Submits a cloud render. Defaults to `mp4` at `30fps`.
118+
119+
**Format options:**
120+
121+
| Format | Codec | Use it for |
122+
|---|---|---|
123+
| `mp4` (default) | H.264 | Broadest compatibility, social media, web |
124+
| `webm` | VP9 | Smaller files; supports alpha channel for transparent overlays |
125+
| `mov` | ProRes | Lossless quality for editing pipelines |
126+
127+
**Frame rate options:** `24`, `30` (default), `60`.
128+
129+
**Returns:** Either the rendered video URL (if the render finishes within 25 seconds) or a `job_id` for polling. Either way, an inline render-progress widget shows live status.
130+
131+
**Triggered by prompts like:** *"render this"*, *"export to webm"*, *"render at 60fps for editing"*.
132+
133+
### get_render_status
134+
135+
Polls an in-progress render. Used internally by the model when `render_video` returns a `job_id` (long renders).
136+
137+
### get_credits
138+
139+
Returns your tier and remaining credits.
140+
141+
**Triggered by:** *"how many renders do I have left?"*, *"what's my plan?"*
142+
143+
## Prompting tips
144+
145+
### Be specific about what you want
146+
147+
The agent has lots of creative latitude — give it enough direction to use it well.
148+
149+
| Less effective | More effective |
150+
|---|---|
151+
| "make a video" | "make a 15-second TikTok hook about home composting with bouncy captions and a warm earthy palette" |
152+
| "add captions" | "add hype-style captions in my brand color #FF6A00" |
153+
| "make it shorter" | "trim to 10 seconds total — cut the third scene" |
154+
| "more energetic" | "swap to a neon-electric palette and tighten all transitions to 200ms" |
155+
156+
### Iterate conversationally
157+
158+
Once a composition exists, the agent loads the current state and applies edits in place. Keep talking to it.
159+
160+
```
161+
You: "20-second product intro for my app, dark theme, hype style"
162+
Agent: [composition + player widget appears]
163+
164+
You: "make the logo bigger and add a pulse animation on the CTA"
165+
Agent: [updated player widget]
166+
167+
You: "render to webm with alpha"
168+
Agent: [render-progress widget, then player widget with download link]
169+
```
170+
171+
### Reference your existing HeyGen assets
172+
173+
If you've uploaded logos, brand voices, fonts, or other assets to your HeyGen account, the agent can use them. Just say *"use my logo"* or *"use my Sarah brand voice."* The agent resolves the asset by name and recency.
174+
175+
### Pick the right format up front
176+
177+
Mention the output format if you have a specific use case:
178+
179+
- *"render to mp4"* — default, social media
180+
- *"render to webm with alpha"* — transparent overlay you'll composite later
181+
- *"render to mov for After Effects"* — ProRes for editing
182+
183+
## Debugging
184+
185+
### Inspect the MCP with MCP Inspector
186+
187+
For developers building integrations or debugging tool responses, the MCP Inspector lets you see exactly what tools are exposed and what they return:
188+
189+
```bash
190+
npx @modelcontextprotocol/inspector npx -y mcp-remote https://mcp.heygen.com/mcp/hyperframes
191+
```
192+
193+
Complete the OAuth flow in the inspector's browser tab. Once authenticated, you can call each tool with custom parameters and see raw responses, including `tool_data` and `widget_data`.
194+
195+
### Watch progress notifications
196+
197+
The MCP emits MCP `notifications/progress` events during long-running `compose` and `render_video` calls. The host (Claude.ai or ChatGPT) displays them inline:
198+
199+
```
200+
You: "make me a 30-second product intro"
201+
Agent: [calls compose]
202+
↳ "Drafting outline..." ← progress notification
203+
↳ "Selecting voice and style..." ← progress notification
204+
↳ "Generating HTML..." ← progress notification
205+
↳ "Rendering preview frame..." ← progress notification
206+
↳ [composition + player widget]
207+
Agent: "Here's your video — [player]"
208+
```
209+
210+
If progress stops mid-flow, the run failed. The agent's next message should explain what went wrong.
211+
212+
### Common issues
213+
214+
<AccordionGroup>
215+
<Accordion title="OAuth keeps failing or loops">
216+
Verify you're using the production URL: `https://mcp.heygen.com/mcp/hyperframes`. The dev URL (`mcp.dev.heygen.com`) only accepts dev accounts.
217+
218+
If OAuth completes but you see "not authorized" errors, your HeyGen account may not have access to the MCP — contact support or check your tier.
219+
</Accordion>
220+
221+
<Accordion title="Render is stuck or never completes">
222+
Renders normally finish in 10-90 seconds depending on length, fps, and format.
223+
224+
If `get_render_status` shows `status: rendering` for more than 5 minutes, something has stuck. Try:
225+
226+
1. Start a new chat thread
227+
2. Run `compose("regenerate this composition")` — the underlying composition may reference an asset that's failing to load
228+
3. If the issue persists, file an issue at [github.com/heygen-com/hyperframes/issues](https://github.com/heygen-com/hyperframes/issues) including the `job_id` from `render_video`
229+
</Accordion>
230+
231+
<Accordion title='"Composition not found" error'>
232+
The `composition_id` is owned by the HeyGen space (account) that created it. If you're signed into a different space, you can't access compositions from another. Run `list_compositions` to see what's available from your current account.
233+
</Accordion>
234+
235+
<Accordion title="Player widget shows blank or loads forever">
236+
Usually a transient connection issue between the widget and `mcp.heygen.com`. Refresh the chat or call `get_composition` again.
237+
238+
If it persists, your composition may reference a media asset that failed to upload — recreate the composition with `compose("regenerate this")`.
239+
</Accordion>
240+
241+
<Accordion title="Out of credits">
242+
The MCP returns an error with an upgrade URL when your credits are exhausted. Visit [heygen.com/pricing](https://heygen.com/pricing) to upgrade your tier.
243+
</Accordion>
244+
245+
<Accordion title="Tool call timed out in the host">
246+
`compose` runs can take 30+ seconds for complex prompts. If your client times out before the response comes back, the underlying run is likely still progressing — wait 30 seconds and run `list_compositions`. The composition is probably already created.
247+
</Accordion>
248+
249+
<Accordion title="Agent ignored part of my prompt">
250+
The agent prefers structural decisions (palette, layout, motion) over fine-grained pixel positioning. If a specific edit doesn't land, try rephrasing more directively:
251+
252+
- Less effective: *"the title is a little off"*
253+
- More effective: *"move the title 40px down and increase its weight to 800"*
254+
255+
For pixel-precise control, use the [open-source CLI](/quickstart) — the MCP is optimized for fast natural-language iteration.
256+
</Accordion>
257+
</AccordionGroup>
258+
259+
### Reporting issues
260+
261+
For bugs or feature requests, file an issue at [github.com/heygen-com/hyperframes/issues](https://github.com/heygen-com/hyperframes/issues). Include:
262+
263+
- The prompt you used
264+
- The `composition_id` and `job_id` (if applicable) — these are visible in the tool response details
265+
- A description of what you expected vs. what happened
266+
- The host (Claude.ai web/desktop, ChatGPT, etc.)
267+
268+
## Limitations
269+
270+
- **Cloud-only rendering.** All renders run on HeyGen infrastructure. Use the [CLI](/quickstart) if you need local rendering.
271+
- **Single-user.** Each composition is owned by one HeyGen account. No team sharing in v1.
272+
- **No binary uploads from chat.** You can reference assets you've already uploaded to HeyGen via the web UI, but the MCP does not currently accept new file uploads through chat. Upload via [app.heygen.com](https://app.heygen.com) first, then reference the asset by name.
273+
- **Aspect ratios:** `16:9`, `9:16`, `1:1`, `4:5`. Other ratios fall back to the closest match.
274+
- **No fine-grained editing tools.** Edits go through the agent. For pixel-precise control, use the [CLI](/quickstart) and a coding agent like Claude Code or Cursor.
275+
- **Widget rendering requires a host that supports MCP widgets.** Claude.ai web/desktop and ChatGPT (Apps SDK) support widgets today. Text-only MCP clients (Claude Code CLI, Cursor, Windsurf) will see a clickable preview URL instead — full text-mode support is on the roadmap.
276+
277+
## How this relates to the open-source framework
278+
279+
[HyperFrames itself is open source](https://github.com/heygen-com/hyperframes) — the HTML composition format, CLI, renderer, and player. You can use HyperFrames locally without the MCP.
280+
281+
The MCP is a HeyGen-hosted product that wraps:
282+
283+
- The HyperFrames composition agent (the LLM that authors compositions)
284+
- HeyGen's cloud rendering pipeline
285+
- HeyGen's voice / TTS / asset libraries
286+
- OAuth, credits, and tier management
287+
288+
| You want… | Use… |
289+
|---|---|
290+
| Zero local install, fast natural-language authoring | The MCP |
291+
| Pixel-precise control, custom rendering, self-hosting | The [CLI](/quickstart) |
292+
| Both | Author with the MCP, then download and refine with the CLI (planned export feature) |
293+
294+
## Next steps
295+
296+
<CardGroup cols={2}>
297+
<Card title="Quickstart" href="/quickstart">
298+
Try HyperFrames locally with the open-source CLI.
299+
</Card>
300+
<Card title="Prompting guide" href="/guides/prompting">
301+
Tips for getting the best results when working with AI agents.
302+
</Card>
303+
<Card title="Catalog" href="/catalog/blocks/data-chart">
304+
Browse 50+ ready-to-use blocks the agent draws from.
305+
</Card>
306+
<Card title="Examples" href="/examples">
307+
Reference compositions you can clone.
308+
</Card>
309+
</CardGroup>

0 commit comments

Comments
 (0)