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. |
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_delete_project | Moving an owned project to recoverable Studio trash. |
jsoncut_render_project | Rendering a durable project. |
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. |
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. |
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. |
jsoncut_delete_media | Removing unused media. |
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. 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_list_components, jsoncut_get_component | Reusing an owned, pinned visual component. |
jsoncut_list_brand_kits | Reading approved brand resources. |
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. |
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–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.