Docs
preview MCP tool
Look at the live timeline.
MCP name preview dispatches to renderer preview.
Does not use hosted quota. Local editor operation.
Look at the live timeline. action captureFrame requires timecode in seconds (0 is valid) and captures one composed still. action timeline returns timestamped contact sheets of the composed timeline (optional startTime and endTime in seconds). Editor must be open. Does not use hosted quota. Local editor operation.
Advertised MCP input
This tool is registered with passthrough. The fields below are what listTools advertises. The renderer still validates the child fields for the chosen action or kind. Extra advertised-only values are documented under Reachable behavior.
| Field | Type | Required | Constraints | Default | Description |
|---|---|---|---|---|---|
action | enum("captureFrame", "timeline") | yes | — | — | action for preview |
timecode | number | no | min 0 | — | Required when action is captureFrame. Timeline time in seconds to seek to before capturing. 0 is valid. |
grid | number | no | exclusiveMin 0 | — | Optional captureFrame grid step in scene pixels (top-left origin). |
crop | object | no | strict | — | Optional captureFrame crop rectangle in scene pixels. |
crop.x | number | yes | — | — | Crop left edge in scene pixels (top-left origin) |
crop.y | number | yes | — | — | Crop top edge in scene pixels (top-left origin) |
crop.w | number | yes | exclusiveMin 0 | — | Crop width in scene pixels |
crop.h | number | yes | exclusiveMin 0 | — | Crop height in scene pixels |
startTime | number | no | min 0 | — | Optional start time in seconds for action timeline. |
endTime | number | no | min 0 | — | Optional end time in seconds for action timeline. |
resultStart | integer | no | min 0; max 9007199254740991 | 0 | First character offset to return. Use 0 for the first call. |
resultEnd | integer | no | min 1; max 9007199254740991 | 8000 | Exclusive end offset. resultEnd - resultStart must be at most 8000. Increment resultStart by 8000 to page through large results. |
Reachable behavior
Advertised action values match the renderer children: captureFrame, timeline.
Renderer child fields
These are the authoritative fields for each action. Send them on the same MCP call. Grouped MCP tools use passthrough, so these fields are not all listed in the advertised schema.
action=captureFrame
Renderer tool: previewCaptureFrame.
Seek the live preview to a specific time and capture the current frame from the preview canvas. Optional grid (scene-pixel step) and crop (scene top-left x/y/w/h) annotate absolute coordinates so you can place overlays without guessing. Timeline clip positions use center origin: position.x = topLeftX - sceneWidth/2. Use this as the default way to verify timeline edits; capture several timecodes for motion-heavy changes. This is much faster than rendering a video preview.
| Field | Type | Required | Constraints | Default | Description |
|---|---|---|---|---|---|
timecode | number | yes | min 0 | — | Time in seconds on the timeline to seek to before capturing the frame. |
grid | number | no | exclusiveMin 0 | — | Optional grid step in scene pixels (top-left origin). Draws labeled axes so you can read absolute coordinates from the image. |
crop | object | no | strict | — | Optional crop rectangle in scene pixels (top-left origin). Use with grid to zoom into a UI region. |
crop.x | number | yes | — | — | Crop left edge in coordinate-space pixels (top-left origin) |
crop.y | number | yes | — | — | Crop top edge in coordinate-space pixels (top-left origin) |
crop.w | number | yes | exclusiveMin 0 | — | Crop width in coordinate-space pixels |
crop.h | number | yes | exclusiveMin 0 | — | Crop height in coordinate-space pixels |
action=timeline
Renderer tool: previewTimeline.
Sample the composed timeline as timestamped contact-sheet stills. Omit startTime and endTime for the full duration, or pass both in seconds for a range. Use captureFrame when you need one high-resolution still at a known timecode.
| Field | Type | Required | Constraints | Default | Description |
|---|---|---|---|---|---|
startTime | number | no | min 0 | — | Start time in seconds. Required with endTime, or omit both for the full timeline. |
endTime | number | no | min 0 | — | End time in seconds. Required with startTime, or omit both for the full timeline. |
Result window
Every local MCP tool accepts resultStart and resultEnd so large payloads can be paged.
resultStart— first character offset. Default0.resultEnd— exclusive end offset. Default8000.resultEnd - resultStartmust be at most 8000 characters.- Increment
resultStartby 8000 to read the next window.