MCP tool reference
An overview of DemoTake's MCP tools, how handles, results and errors work, and the order agents usually call them in. Every tool's parameters and examples are in the full reference.
DemoTake's MCP server exposes the whole app as tools: finding windows, planning takes, recording, proving results, editing, exporting and running specs. This page is the map. The full reference at /api has every tool with its parameters, results and examples, and each tool has its own anchor, like /api#take_create.
Tool names follow namespace_verb. Some agents follow dotted names literally, so take.create works as an alias for take_create.
Tool groups
| Group | Tools | What they're for |
|---|---|---|
| Targets and permissions | targets_list, browser_tab, targets_inspect, targets_capabilities, permissions_status, licence_status |
Find the window, browser tab or booted iOS Simulator device to record, check what DemoTake can do with it, and whether recording and exporting are available |
| Projects and takes | project_list, project_create, take_list, take_get, take_create, take_plan, take_rehearse, take_rehearse_finish, take_start_scene, take_checkpoint, take_retry_scene, take_log_event, take_relabel_events |
Plan a take's scenes, rehearse, record scene by scene, retry one scene, report steps done with your own tools and who did them |
| Capture | capture_start, capture_pause, capture_resume, capture_stop, capture_status, take_handoff, take_wait |
Start and stop recording the take's target, hand a step to a person, and wait out slow server work without recording it |
| Observe | observe_state, observe_snapshot, observe_wait_for |
Read the UI as a compact text outline, take a snapshot with secrets blurred, wait for the UI |
| Operate (DemoTake Agent only) | pointer_click, pointer_move, pointer_scroll, keyboard_type, keyboard_key, ui_perform_action, ui_focus |
Operate the app through Accessibility, in the background when possible |
| Verify | assert_element, assert_text, assert_state, assert_success, assert_check |
Prove each step worked; results go into the proof manifest |
| Edit | edit_apply, edit_trim, edit_speed, edit_compress_waits, edit_camera, edit_redact, edit_pointer, edit_command, timeline_get |
Non-destructive edits, one at a time or many at once, or in plain words like the command bar |
| Review | edit_suggest_cuts, take_contact_sheet, take_frame, edit_revert, edit_history, preview_frame, preview_clip, review_check |
Footage review: suggested cuts, frames to check, previews of the edited video without exporting, undo by edit id, and the platform review check |
| Export | export_render, export_preflight, export_validate, export_status, export_manifest |
Render outputs that check themselves, and the proof manifest |
| Voiceover and subtitles | voices_list, voiceover_script, voiceover_generate, voiceover_update, voiceover_remove, export_subtitles |
Write and speak a line per scene with the Mac's voices or DemoTake AI voices, and write SRT, WebVTT and transcripts. See Voiceover and subtitles |
| Languages | take_languages_set, translate_take, translation_update, onscreen_text_scan |
Make one take in many languages, translated with DemoTake AI or on the Mac. See Your demo in other languages |
| Interactive demos | interactive_build, interactive_get, interactive_update, interactive_export, interactive_share |
A click-through demo of the take, as an offline website or a link with an embed code. See Interactive demos |
| Share links | share_list, share_embed, share_update, share_analytics |
Embed codes, calls to action and analytics for videos and interactive demos. See Embeds, calls to action and analytics |
| Demo as code | spec_validate, spec_run, take_replay, take_diff, take_to_spec, take_export_package, take_import_package |
demotake.json specs, DemoTest, only-changed regeneration, .take packages. spec_run and take_replay are DemoTake Agent only |
| Control | permissions_request, export_cancel |
Ask for a macOS permission, stop a render |
| One call | demo_create |
DemoTake plans, rehearses, records, verifies and renders on its own |
| Events and help | events_poll, demotake_guide |
Realtime events after a cursor, and the workflow guide |
DemoTake Studio doesn't list the Operate tools, spec_run or take_replay, because it can't operate other apps. In Studio your agent operates the app with its own computer-use tools and reports each step with take_log_event, so DemoTake can still place the pointer and zooms. demo_create needs DemoTake AI and DemoTake Agent. See Connect your agent.
A typical sequence
- permissions_status
- targets_list
- take_create
- take_rehearseoptional
- capture_start
- take_start_sceneper scene
- pointer_clickor your own tools
- assert_text
- take_checkpoint
- capture_stop
- edit_suggest_cuts
- edit_apply
- export_renderwait: true
Here is what one scene looks like as calls:
{ "name": "take_start_scene", "arguments": { "take_id": "take_…", "scene": "Sign in" } }
{ "name": "pointer_click", "arguments": { "take_id": "take_…", "element": { "role": "button", "title": "Sign in" } } }
{ "name": "assert_text", "arguments": { "take_id": "take_…", "text": "Welcome back" } }
{ "name": "take_checkpoint", "arguments": { "take_id": "take_…", "description": "Dashboard visible with 3 projects" } }Handles
The server is stateless: every tool names the handles it works on, and no session is needed. Handles are short prefixed ids you get back from earlier calls.
| Prefix | What it names | Where you get it |
|---|---|---|
take_… |
A take | take_create, demo_create, take_list |
scn_… |
A scene (you can also use its exact title or 1-based index) | take_get, take_create |
exp_… |
An export job | export_render |
ast_… |
An assertion | assert_* |
edt_… |
An edit you can revert | edit_apply and the other edit_* tools |
Both spellings of a handle work everywhere, including inside edit_apply operations: scene or scene_id, target or target_id, take_id or take, job_id or job, overlay_id or overlay, project_id or project, set_id or screenshot_set_id, shot or shot_id. A browser target can also be {"url_contains": "example.com"}: the window whose tab shows that address.
Web apps, hand-offs and platform reviews
For a web app, take_create {browser: {mode: "page", address_bar: "drawn"}, target: {url_contains: "example.com"}} records only the page, without tabs, toolbar or automation bars, and draws a clean address bar from the tab's address. If the tab isn't in front, DemoTake Agent brings it forward or opens it in its own window (browser.tab, or browser_tab beforehand). When a step is the person's to do, such as signing in or pressing Allow, take_handoff pauses the recording and shows them what to do inside DemoTake. take_wait leaves slow server work out of the video. For TikTok, Meta, Google and Apple reviews, review_check checks the take and writes a checklist for the review form. The whole workflow is in Record a platform review video.
After edits, preview_frame shows the exact frame the export will draw at an output time, and preview_clip renders a short, small MP4. Use them instead of exporting to check a crop, a camera move or a caption.
Results
Every tool returns structured content (JSON) plus the same data as text for clients that ignore structured results. Most text results start with a one-line summary, such as Created take_… with 3 scene(s). Results about a take or scene also carry a suggested next step, for example "capture_start, then for each scene: take_start_scene → act → assert_* → take_checkpoint." Agents that follow it rarely call things out of order.
Edits return an edit_id and the new output duration, so edit_revert can undo exactly that change later.
Errors
A tool that fails returns a normal result marked as an error, with a message written for the agent to act on, not a stack trace. For example:
- a window that's minimized: "… is minimized. macOS pauses capture of minimized windows — move it aside instead of minimizing."
- an app-control tool called in DemoTake Studio: "UI control isn't available in DemoTake Studio (Mac App Store). …"
- a bad argument: "Invalid arguments for take_create: …"
If a call needs a permission that's off, DemoTake shows you a Permission Needed window and tells the agent it's waiting for you. Only an unknown tool name is a protocol error.
Progress and events
Long calls report progress. When your client sends a progress token, export_render with wait: true, spec_run, take_replay and demo_create stream notifications/progress while they work, then the result. Clients that listen on the MCP event stream also receive DemoTake's events (scene started, assertion passed or failed, checkpoint created, render progress…) as notifications/message. Clients without notifications can call events_poll with the cursor from the previous call. Hand-offs and waits report handoff_started and handoff_ended (with how they ended), and browser takes report each page change.
Where to go next
- The full MCP reference with every parameter and example.
- The DemoTake skill teaches your agent this sequence.
- Demo specs and CI for
spec_run,take_replayandtake_diffin practice. - Export checks and troubleshooting for what
export_preflightandexport_validatecheck.