# Work with storyboards and timelines > Read consistent media snapshots, use revision-guarded grouped timeline and storyboard commands, and distinguish editor changes from transfers and rendering. Source: https://kaitoi.io/docs/core/mcp-media/ Section: Kaitoi Core / MCP Written for: AI clients editing attached Studio media workflows. Last reviewed: 2026-10-24 --- The improved MCP can inspect and edit a live Studio timeline or storyboard through grouped attached tools. This changes editable state or playback; it is separate from generating footage or rendering a finished deliverable. ## Carry the right revision through a media edit Read attached storyboard and timeline state consistently, retaining both editor and media revisions across all pages. Use the grouped tool's supported command schema and current guards for edits. Do not mix pages from changing revisions or substitute a new guard onto an old assumed sequence. Transfers require an explicit destination and inspection of what arrived. Rendering is separate work; editing or playback is not exported footage. The example pairs editor revision 7 with storyboard revision 12 on every page of that selected read. Shot 01 and shot 02 thumbnails reappear in their matching timeline clips after an explicit transfer; this is not continuing synchronization. The timeline is a separate destination with its own revision (5 in the example); read its current state before transferring. *Figure: Graph, storyboard and timeline state have distinct edit contracts.* ## Attach and retain both revisions Enable Agent access, attach to the intended Studio session, and read current state. Timeline/storyboard operations use the editor `expected_revision` plus a media-specific revision. Keep both identities distinct from saved bundle versions and execution IDs. `get_timeline_state` reads `scenes`, `tracks`, or `clips`; `get_storyboard_state` reads `scenes` or `frames`. Use the offered `scene_id`, offset and limit. Subsequent pages require both original revisions, so a changed sequence is not silently combined with an older page. If state changes, refresh and reconcile rather than splicing mismatched pages. ## Use the grouped timeline action `studio_timeline_action(command:{action,arguments}, expected_revision, expected_timeline_revision, studio_session)` accepts its closed command schema. Current actions include adding, updating, splitting and selecting clips; setting the playhead; and controlling play/pause/stop. When adding a clip, choose exactly one supported source: `node_id`, `library_file_id`, or `lab_item_id`. Node source output/version selection belongs to that source, not every source type. Inspect timing, scene, track, trim and the actual selected media before another edit. ## Use the grouped storyboard action `studio_storyboard_action` uses the editor and storyboard revisions. Its commands cover open/close, add/update/delete/reorder frames, applying a document, and sending supported work to Timeline. Use the actual schema's frame fields and owned media filenames, not arbitrary remote URLs. `apply_storyboard_document` selects one document, filename or node source and an explicit append/replace mode. Sending to Timeline selects either an existing `target_scene_id` or a `new_scene_name`, not both. Read the resulting receipts and destination state. ## Keep edit, transfer, and render separate **Read:** page timeline/storyboard state with the same editor and media revisions. **Edit:** use the grouped command's closed schema and exact source identity. **Transfer:** choose the intended Timeline destination and inspect what arrived. These actions edit state or playback; they do not generate footage or render a final movie. No live editor command is sent here. ## Recover an uncertain media edit Retain the original action ID and inspect it before repeating a split, insertion, replacement or transfer. Context changes, stale editor revisions, and stale media revisions need fresh reads. A playback command is not a render approval, and an editable sequence is not completed media. See [REST media documents](/docs/core/timelines-and-storyboards/) for server documents and interchange, [Studio Timeline](/docs/studio/timeline/) for render/export controls, and [MCP results](/docs/core/mcp-results/) for retained execution outputs.