JsonCutDocs

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

ToolUse it when
jsoncut_get_authoring_guideStarting a new authoring task or restructuring a project.
jsoncut_list_projectsFinding an existing durable project.
jsoncut_create_projectCreating an editable image or video source.
jsoncut_get_projectReading the complete current source and version.
jsoncut_get_project_outlineNavigating a large project without loading every scene.
jsoncut_get_sceneReading one scene and its local children.
jsoncut_get_project_scopeReading a bounded time, scene, parent, track or kind window.
jsoncut_get_layerReading one exact layer and optionally its bounded markup.
jsoncut_update_projectReplacing a small complete source with optimistic versioning.
jsoncut_edit_projectApplying one bounded structural edit.
jsoncut_author_projectApplying a small validated batch to a flat project.
jsoncut_author_sceneApplying scene-relative edits to long-form work.
jsoncut_patch_project_sourceAppending or replacing complete HTML fragments and named CSS blocks.
jsoncut_set_keyframesCreating typed Studio-editable property motion.
jsoncut_bind_audio_motionMeasuring owned audio and binding energy to a Studio-editable visual layer.
jsoncut_validate_projectStatic structure, JavaScript syntax and output checks; optional sampled runtime check.
jsoncut_review_sceneQueuing a contact sheet for one scene; more frames where more happens.
jsoncut_view_framesUp 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_playbackQueuing a draft video with project audio by default.
jsoncut_review_motionInspecting decoded export frames, optional onion skin and sampled audio levels.
jsoncut_inspect_motionMeasuring 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_projectMoving an owned project to recoverable Studio trash.
jsoncut_render_projectRendering 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_contextReading compact source, cut and reusable-resource context.
jsoncut_get_project_cutReading the current immutable cut.md version.
jsoncut_validate_project_cutValidating a proposed cut without saving it.
jsoncut_set_project_cutSaving the next validated cut version.
jsoncut_check_projectCreating a version-bound technical and visual review.
jsoncut_get_reviewReading one immutable review and its findings.
jsoncut_set_review_statusRecording changes requested or Agent approval. Human approval remains a Studio action.
jsoncut_project_versionsListing the version history, saving a version before larger changes, or restoring one as a new current version.

Media

ToolUse it when
jsoncut_list_mediaDiscovering project or template assets.
jsoncut_upload_mediaUploading a small bounded Base64 file.
jsoncut_create_upload_ticketUploading a large/local file without putting bytes in MCP context; scope temporary for files that should expire after 48 h.
jsoncut_get_upload_statusRecovering the completed media reference, including after a lost PUT response.
jsoncut_abort_uploadDiscarding an owned unfinished transfer.
jsoncut_import_host_fileImporting an authorized host file reference when the client supports file inputs.
jsoncut_get_upload_handoffOpening the target Studio project when no permitted byte channel is available.
jsoncut_register_fontRegistering an uploaded font with its family, weight, style and license.
jsoncut_import_media_urlPinning a public URL after validation.
jsoncut_get_mediaReading metadata and preview information.
jsoncut_inspect_mediaInspecting dimensions, duration, codec or audio information; for owned files shots, busy passages with times to look at, and a filmstrip.
jsoncut_search_footageFinding moments in the project's own footage by what is said or shown; returns file, time range, text and reason.
jsoncut_read_transcriptWhat 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_speechCutting 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_layersOne change on every layer matching kind, role, name or parent (style of all captions)
jsoncut_assemble_scriptRough cut from a script: each line's best take from the files' speech, in the script's order
jsoncut_stabilize_videoTaking the shake out of a video: a stabilized copy on all layers of the file
jsoncut_delete_mediaRemoving unused media.

Voice and captions

ToolUse it when
jsoncut_list_voicesChoosing a voice, delivery tone, language and caption style before a voiceover.
jsoncut_search_soundsFinding 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_effectPlacing a library sound on a cut, entrance or word; its loudest point lands on the moment and it never ducks the music.
jsoncut_add_voiceoverSpeaking a script: one audio clip per paragraph; with captions=true also captions with the script's exact words, timed to the voice.
jsoncut_translate_speechDubbing a clip into another language: each translated line is spoken where the original was, the original is muted.
jsoncut_inspect_audioChecking 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_mixMixing 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_captionsCaptioning 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

ToolUse it when
jsoncut_list_templatesSearching available image and video templates.
jsoncut_get_templateReading a template.
jsoncut_get_template_inputsDiscovering typed inputs before filling anything.
jsoncut_render_templateFilling and rendering one variant.
jsoncut_bulk_render_templateRendering a bounded set of variants.
jsoncut_get_bulk_renderPolling batch state.
jsoncut_cancel_bulk_renderCancelling 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.

ToolUse it when
jsoncut_search_library, jsoncut_get_library_itemFinding 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_componentReusing an owned, pinned visual component.
jsoncut_list_brand_kitsReading approved brand resources.
jsoncut_apply_brand_kitPutting a project on a brand, or preparing one design for several brands via template fields.
jsoncut_list_fontsResolving a registered owned font.
jsoncut_create_batchStarting a bounded production checklist across related projects.
jsoncut_get_batch, jsoncut_update_batchTracking reviews, membership and asset conflicts.
jsoncut_source_mediaFinding attributable stock media for a declared role; retention: temporary imports without keeping it in the project.
jsoncut_search_inspirationGathering 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

  1. Read the authoring guide.
  2. Create one flat project with only meaningful layers.
  3. Apply a bounded authoring batch.
  4. Validate and request a 12-frame review grid.
  5. Correct only visible issues.
  6. Render the final project.
  7. For requested delivery, create a temporary download link and return it with its expiry.

A long-form loop

  1. Create a durable project with editorial scenes.
  2. Page through the project outline.
  3. Read and author one scene using scene-relative time.
  4. Validate and review that scene.
  5. Continue with scopes, individual layers and complete bounded HTML/CSS fragments without sending the entire project through MCP each turn.
  6. 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.