MCP tools and workflows
Choose the smallest MCP workflow for projects, media, templates, review and rendering.
The V2 MCP server exposes focused tools rather than mirroring every HTTP endpoint. It does not include Studio sessions, billing, internal operations or V1 API JSON jobs.
Project authoring
| Tool | Use it when |
|---|---|
jsoncut_get_authoring_guide | Starting a new authoring task or restructuring a project. |
jsoncut_list_projects | Finding an existing durable project. |
jsoncut_create_project | Creating an editable image or video source. |
jsoncut_get_project | Reading the complete current source and version. |
jsoncut_get_project_outline | Navigating a large project without loading every scene. |
jsoncut_get_scene | Reading one scene and its local children. |
jsoncut_get_project_scope | Reading a bounded time, scene, parent, track or kind window. |
jsoncut_get_layer | Reading one exact layer and optionally its bounded markup. |
jsoncut_update_project | Replacing a small complete source with optimistic versioning. |
jsoncut_edit_project | Applying one bounded structural edit. |
jsoncut_author_project | Applying a small validated batch to a flat project. |
jsoncut_author_scene | Applying scene-relative edits to long-form work. |
jsoncut_patch_project_source | Appending or replacing complete HTML fragments and named CSS blocks. |
jsoncut_set_keyframes | Creating typed Studio-editable property motion. |
jsoncut_bind_audio_motion | Measuring owned audio and binding energy to a Studio-editable visual layer. |
jsoncut_validate_project | Static structure, JavaScript syntax and output checks; optional sampled runtime check. |
jsoncut_review_scene | Queuing a contact sheet for one scene; more frames where more happens. |
jsoncut_view_frames | Up to six full-size frames of the saved project or a media file at chosen times, each as its own image, optionally a region enlarged. |
jsoncut_review_playback | Queuing a draft video with project audio by default. |
jsoncut_review_motion | Inspecting decoded export frames, optional onion skin and sampled audio levels. |
jsoncut_inspect_motion | Measuring the saved project's motion at every frame of a window of up to 12 seconds: position and size jumps and opacity pops, with one annotated image. It does not decode video media or listen to audio. |
jsoncut_delete_project | Moving an owned project to recoverable Studio trash. |
jsoncut_render_project | Rendering a durable project: video, audio only (wav, mp3, m4a, opus), a range (rangeStart, rangeEnd), a loudness target, transparent video on request (mov with prores, webm), or handoff: a ZIP with FCPXML, Premiere XML, media, SRT and a report (overlay: true adds text and graphics as transparent ProRes 4444). |
jsoncut_get_project_context | Reading compact source, cut and reusable-resource context. |
jsoncut_get_project_cut | Reading the current immutable cut.md version. |
jsoncut_validate_project_cut | Validating a proposed cut without saving it. |
jsoncut_set_project_cut | Saving the next validated cut version. |
jsoncut_check_project | Creating a version-bound technical and visual review. |
jsoncut_get_review | Reading one immutable review and its findings. |
jsoncut_set_review_status | Recording changes requested or Agent approval. Human approval remains a Studio action. |
jsoncut_project_versions | Listing the version history, saving a version before larger changes, or restoring one as a new current version. |
Media
| Tool | Use it when |
|---|---|
jsoncut_list_media | Discovering project or template assets. |
jsoncut_upload_media | Uploading a small bounded Base64 file. |
jsoncut_create_upload_ticket | Uploading a large/local file without putting bytes in MCP context; scope temporary for files that should expire after 48 h. |
jsoncut_get_upload_status | Recovering the completed media reference, including after a lost PUT response. |
jsoncut_abort_upload | Discarding an owned unfinished transfer. |
jsoncut_import_host_file | Importing an authorized host file reference when the client supports file inputs. |
jsoncut_get_upload_handoff | Opening the target Studio project when no permitted byte channel is available. |
jsoncut_register_font | Registering an uploaded font with its family, weight, style and license. |
jsoncut_import_media_url | Pinning a public URL after validation. |
jsoncut_get_media | Reading metadata and preview information. |
jsoncut_inspect_media | Inspecting dimensions, duration, codec or audio information; for owned files shots, busy passages with times to look at, and a filmstrip. |
jsoncut_search_footage | Finding moments in the project's own footage by what is said or shown; returns file, time range, text and reason. |
jsoncut_read_transcript | What is said in the project's footage, in seconds of the timeline as it is now, for placing overlays and cuts on spoken moments. |
jsoncut_clean_speech | Cutting pauses, filler sounds and repeated words out of spoken footage: shows what would go and the new length first, then saves it as one version. |
jsoncut_patch_layers | One change on every layer matching kind, role, name or parent (style of all captions) |
jsoncut_assemble_script | Rough cut from a script: each line's best take from the files' speech, in the script's order |
jsoncut_stabilize_video | Taking the shake out of a video: a stabilized copy on all layers of the file |
jsoncut_delete_media | Removing unused media. |
Voice and captions
| Tool | Use it when |
|---|---|
jsoncut_list_voices | Choosing a voice, delivery tone, language and caption style before a voiceover. |
jsoncut_search_sounds | Finding a sound effect (whoosh, hit, riser, click, pop, crowd, ambience, jingle …) by English or German words, with its length and the moment it hits. |
jsoncut_add_sound_effect | Placing a library sound on a cut, entrance or word; its loudest point lands on the moment and it never ducks the music. |
jsoncut_add_voiceover | Speaking a script: one audio clip per paragraph; with captions=true also captions with the script's exact words, timed to the voice. |
jsoncut_translate_speech | Dubbing a clip into another language: each translated line is spoken where the original was, the original is muted. |
jsoncut_inspect_audio | Checking sound: loudness per track and mix (LUFS, true peak), speech, words and findings with ready fix patches, plus a sound sheet image. A quiet or peaking mix is fixed with an update_canvas action carrying audioMaster (targetLufs, ceilingDb). |
jsoncut_auto_mix | Mixing in one step: applies every measured sound repair (music under speech, levels) and sets the master to a loudness target (-14 LUFS by default, -1 dBTP ceiling). |
jsoncut_add_captions | Captioning speech already in the project (auto leaves music and effects out) or one clip, in timeline time. |
Voice, caption and dub calls generate inside the call. If one does not answer in time, its error names a request_key: call the same tool again with it to receive the saved result instead of generating twice.
Templates
| Tool | Use it when |
|---|---|
jsoncut_list_templates | Searching available image and video templates. |
jsoncut_get_template | Reading a template. |
jsoncut_get_template_inputs | Discovering typed inputs before filling anything. |
jsoncut_render_template | Filling and rendering one variant. |
jsoncut_bulk_render_template | Rendering a bounded set of variants. |
jsoncut_get_bulk_render | Polling batch state. |
jsoncut_cancel_bulk_render | Cancelling unfinished batch work. |
Reusable resources and production batches
Use jsoncut_get_primitive_catalog before inventing a common icon, control,
entry/exit motion or text effect. It exposes the same stable Studio catalogs,
including exact SVG from the built-in Lucide library. Common controls are
returned as editable grouped-layer recipes rather than fictional one-click
presets. kind: "libraries" lists the code-layer libraries (three.js, D3,
TopoJSON, World Atlas) with versions and seek-safe examples for add_custom;
a Lottie .json upload is placed with add_media and kind: "lottie". The
jsoncut://v2/registry resource is generated from the deployed tool schemas
and includes compact request examples, so clients can discover the current V2
contract without relying on a copied tool count.
| Tool | Use it when |
|---|---|
jsoncut_search_library, jsoncut_get_library_item | Finding a native Library item with its exact version, editable properties and HTML example; insert it with insert_library_item in jsoncut_author_project or jsoncut_author_scene. |
jsoncut_list_components, jsoncut_get_component | Reusing an owned, pinned visual component. |
jsoncut_list_brand_kits | Reading approved brand resources. |
jsoncut_apply_brand_kit | Putting a project on a brand, or preparing one design for several brands via template fields. |
jsoncut_list_fonts | Resolving a registered owned font. |
jsoncut_create_batch | Starting a bounded production checklist across related projects. |
jsoncut_get_batch, jsoncut_update_batch | Tracking reviews, membership and asset conflicts. |
jsoncut_source_media | Finding attributable stock media for a declared role; retention: temporary imports without keeping it in the project. |
jsoncut_search_inspiration | Gathering style evidence without assuming asset-reuse rights. |
Render lifecycle
jsoncut_get_render can wait briefly and can return image, frame and contact-sheet artifacts directly to a visual Agent. It does not attach MP4 files to the conversation. jsoncut_cancel_render cancels unfinished work. jsoncut_render_inline is reserved for a disposable one-shot source.
Diagnose a failed custom layer
get_render returns errorCode, errorRetryable and, for custom-code failures,
errorDiagnostic. The diagnostic identifies the failure category and, when available,
the layer, source frame and project time. A CUSTOM_CODE_ERROR needs a source correction;
repeating the same snapshot will not fix it. Messages exclude raw exception text,
internal paths, credentials and storage URLs.
Static validation does not execute custom code. For an additional runtime check:
{"project_id":"YOUR_PROJECT_ID","runtime_check":true,"runtime_frames":[450]}Pass this to jsoncut_validate_project, then poll runtimeCheck.renderId using
jsoncut_get_render. Omit runtime_frames to sample up to 24 frames around
custom-layer boundaries and midpoints. These are source-project frame numbers,
not output-frame-rate indices. The check uses the normal renderer and render
permissions/credits; it creates a temporary PNG/grid, not a complete video.
valid: true only confirms static validation. Sampled runtime success does not
guarantee untested frames or full playback.
Deliver the finished file
When the user requests the finished file, call jsoncut_get_download_link after the render completes:
{"render_id":"YOUR_RENDER_ID","expires_in_hours":1}Return its absolute url and expiresAt to the user. The link works without a Studio login and remains behind the JsonCut API. Anyone holding the link can access that single export until expiry or revocation, so do not create one just to check status or review private work. The lifetime is 1 to 24 hours, capped at the original export deadline. Revoke it with jsoncut_revoke_download_link and the returned shareId.
MCP OAuth authentication is not automatically shared with a client's separate file-download tools. Use the temporary link instead of passing credentials or the protected artifactUrl. Where the host supports file downloads, it can fetch the file; otherwise provide the clickable link. This does not bypass network restrictions or automatically save a file on the user's computer. If only the link expires while the export is still available, create a new link without re-rendering.
For API-key connections, creating links requires operations:read and renders:create; revoking them requires operations:cancel. Standard MCP OAuth grants include these scopes. Existing MCP and export plan requirements still apply.
cut.md and reviews are optional Agent workflow artifacts. They never block ordinary rendering. Passing reviewId to jsoncut_render_project explicitly requests a review-attested output and therefore enables strict current project/cut-version checks. Omit it for a normal render. MCP Agents can record agent-approved; human-approved remains a Studio/API-only decision.
A short video loop
- Read the authoring guide.
- Create one flat project with only meaningful layers.
- Apply a bounded authoring batch.
- Validate and request a 12-frame review grid.
- Correct only visible issues.
- Render the final project.
- For requested delivery, create a temporary download link and return it with its expiry.
A long-form loop
- Create a durable project with editorial scenes.
- Page through the project outline.
- Read and author one scene using scene-relative time.
- Validate and review that scene.
- Continue with scopes, individual layers and complete bounded HTML/CSS fragments without sending the entire project through MCP each turn.
- Render the complete pinned project version.
Scenes are optional. Do not wrap every element in a scene or group merely because the tools support hierarchy.
Visual review loop
Tools have concise display titles such as Review motion; the stable jsoncut_… identifiers below remain valid for existing clients.
jsoncut_review_playback queues a draft MP4 with project audio by default; it does not watch or certify the result. Poll jsoncut_get_render, then call jsoncut_review_motion on the completed render:
{"render_id":"YOUR_RENDER_ID","start":1.2,"end":1.6,"sample_count":8,"mode":"onion-skin"}Use mode: "grid" for an overview, then inspect short windows around transitions and animated text. Onion skin adds colored pixel differences alongside the original frames; it supports windows up to two seconds and an optional crop in exported-video pixels. Times are local to the export, not necessarily the original project. The tool returns decoded timestamps and actual image content, with a maximum of 12 samples and a 128 MiB input export. Temporary review files are removed automatically.
jsoncut_review_scene remains useful for scene layout. Neither sampled frames nor overlays prove complete playback, smoothness or audio synchronization. The presence of an audio stream is not a listening test. Only set full_playback_confirmed after complete playback in a capable client or explicit human confirmation; otherwise leave it false and disclose uninspected intervals. Inspect the final export too when its settings differ from the draft.