MCP Tool Reference

Session & project

The tools the studio UI normally covers and a headless model cannot. These exist only over MCP — Valmera's in-browser agent gets this context from the page it is running in.

list_projects

List your Valmera projects.

open_project

Open a project and make it the active one for this session. The open project lives on the grant, so a reconnect resumes the same edit.

create_project

Create a new project — from a video you are about to upload, or as a canvas project built purely from images, clips and music with no main video at all.

project_state

Where the project stands: indexing progress, current edit version, assets, and the latest rendered preview.

upload_start

Begin an upload and get the presigned destination for the file.

upload_finish

Complete an upload and kick off indexing. This is the one place that owns upload idempotency, the size cap, a magic-byte content sniff, and the lock that stops a duplicate index job.

index_status

How far the one-time analysis has got: transcript, silences, shots and the labeled frame tiles the agent reads.

export_final

Render the final video from the ORIGINAL upload at source quality. Returns a job to wait on.

wait_for_job

Block on a running job — a render, an export, a pixel repaint — and return its result. This is what makes slow work honest rather than fabricated.

download_url

A time-limited download URL for a finished render.

Reading the footage

Every edit resolves against a precomputed index rather than a guess. No tool in Valmera accepts a timestamp the model invented — these are where real timings come from.

get_video_info

Video metadata plus a summary of the index and the current edit. The first call of any session.

get_transcript

Sentence-level transcript with timestamps for a range of source time.

get_words

Word-level timestamps for a source-time range — the source of truth for cut points inside a sentence.

get_kept_transcript

The transcript the CURRENT edit actually keeps, in program time, with automatic repeated-phrase detection. How you verify nothing repeated survived a tightening pass.

search_transcript

Find where something is said, by substring and fuzzy match over sentences.

get_shots

Shot boundaries — where the footage genuinely changes shot, and so where a transition can land. The picture itself comes from the frame tiles and look_at.

find_silences

Every silence of at least a given length, with midpoints and the surrounding words so cuts can snap cleanly.

get_audio_analysis

Measured musical and energy analysis of the source audio: tempo with a confidence figure, beat grid, and energy over time.

suggest_emphasis

Candidate emphasis words taken from the real transcript — the most vocally stressed words, words with digits, and rare terms.

list_assets

Every file in the project: uploaded clips, images, music and generated media.

get_edl

The current edit decision list as JSON, with its version number. Every element carries the id you need to move or remove it.

look_at

Ask a vision model about frames from a range of the main video — for taste and visual questions the transcript cannot answer.

look_at_asset

Ask a vision model about frames from an uploaded clip or image, to choose which moment of a piece of b-roll to actually use.

Cutting

The keep list defines what survives, in source seconds. Local edits never disturb the rest of the edit, and anything cut can be restored.

cut_silences

One call to remove every detected pause — "cut the dead air", "tighten this up". Cuts snap to word boundaries so nothing sounds clipped.

remove_filler_words

One call to remove every um, uh, er and hmm, plus any custom words you name.

cut_range

Remove one source-time range. A local edit — the rest of the edit is untouched.

restore_range

Put a previously cut range back, without disturbing any other cut.

keep_segments

Replace the whole keep list at once. For wholesale restructuring only; it warns if it re-includes material you had already cut.

beat_align_cuts

Slide each internal cut onto the nearest musical beat, within a tolerance. Never moves the program's first start or last end.

reset_edit

Throw the edit away and start again from the untouched source.

Captions & on-screen text

Captions are the spoken words. Text elements are designed graphics. They are separate systems, and separate tools.

add_captions

Burned captions timed from the real transcript, or from items you supply. 11 presets, 12 bundled fonts, karaoke word-pop, per-word emphasis, entrance animations, 1–16 words per caption.

set_caption_style

Change how existing captions look — preset, size, position, colours, highlight — without touching their text or timing.

set_caption_mutes

Hide spoken-word captions over specific windows, for when a full-frame element is on screen.

add_text

Burn a designed motion-graphics text template over a window of program time: title, subtitle, lower third, callout, big number, quote or chapter.

remove_text

Remove one text element by id.

add_title_card

Cut to a standalone full-frame card showing only this text, then return to the footage.

add_color_screen

Cut to a full-frame solid or gradient colour screen for a beat, then return.

add_corrupt_screen

Cut to a full-frame glitch or datamosh screen for a beat — a hard transition between sections.

Audio

Music, voiceover, sound effects and the speaker's own audio are four separate layers with their own gain. Sound effects are generated from a description or placed from a file you upload; this deployment ships no built-in effects pack. A video file is a legal sound source — hand any clip's key to a music tool and its audio is lifted out for you.

list_music_library

The built-in royalty-free music library, by mood.

add_music

Mix music into the edit. Defaults are context-aware: under speech the track sits low and ducked; with no speech it comes up to the front.

swap_music

Replace the track of an existing music item while keeping its position, level and fit.

set_music_fit

Retime or refit existing music in place — start later, run to the end, fade out, loop, stop ducking.

remove_music

Remove one music item by id.

extract_audio

Take only the sound out of an uploaded video and save it as an audio file — the answer to "use the song from this clip". The picture appears nowhere.

generate_sfx

Create a one-shot sound effect with AI from a description — "a deep cinematic whoosh", "glass shattering" — and place it at a moment in the program. Half a second to 22 seconds long, or omit the length and let it pick one.

add_sfx

Place a sound you uploaded at a moment in the edit — a whoosh on a cut, a click on a beat, an impact on a reveal. It plays once and never ducks; this is not background music.

move_sfx

Retime an existing sound effect, keeping which sound and how loud.

remove_sfx

Remove one sound effect by id.

add_voiceover

Lay an uploaded audio file over the program from any position, optionally ducking everything else under it.

remove_voiceover

Remove one voiceover by id.

set_audio_gain

Change the loudness of an existing music, sound-effect or voiceover item without re-adding it.

set_volume

Volume automation on the original footage's audio — the speaker — over a source-time span, down to a silent floor.

set_master_loudness

Normalize the final mix to the loudness target streaming platforms expect, on preview and export.

Motion, speed & framing

Zooms and speed are the two levers that make a talking head watchable. Framing decides which platform the result belongs on.

add_zoom

Zoom on a range of the finished edit — punch, ease, push-in or pull-out — aimable at any point of the frame.

remove_zoom

Remove one zoom by id.

add_zoom_path

A zoom that moves: keyframed travel between points, for following a cursor across a screen recording or gliding between two subjects.

remove_zoom_path

Remove one travelling zoom by id.

punch_in_on_emphasis

One call to write punch zooms onto the most vocally stressed words that survive the current cut. Stress is measured from the audio, not guessed from the text.

set_speed

Speed up or slow down a source-time range, from 0.25x to 4x. Voices keep their natural pitch and everything downstream re-anchors.

remove_speed

Remove one speed span by id; that footage returns to normal speed.

set_frame

Set the output aspect ratio for every render: source, 16:9, 9:16, 1:1 or 4:5, by crop, pad or blurred pad.

auto_reframe

Convert the frame and aim the crop at the real subject — samples frames across the kept footage and asks a vision model where the subject actually is.

add_aspect_shift

Change aspect ratio mid-video, smoothly — go vertical for one section and back.

remove_aspect_shift

Remove one mid-video aspect change by id.

set_transitions

Transitions at scene changes — junctions where the footage genuinely changes shot, or where an insert splices in. Applying an effect at every jump cut inside one continuous take is the wrong default, so it is not the default.

set_fades

Fade from black at the start and to black at the end, picture and sound together.

Colour & finish

Grades apply to the whole program; stylize effects are windowed. The two compose.

set_color_grade

Apply a grade preset to the whole video: vibrant, warm, cool, black and white, vintage or cinematic.

set_grade_custom

Continuous exposure, contrast, saturation, temperature and tint, applied after the preset so the two compose.

add_stylize

Layer a windowed finishing effect: film grain, vignette, glow, chromatic aberration, dream blur, VHS, flash or camera shake.

remove_stylize

Remove one stylize effect by id.

apply_look

One call for a whole aesthetic — composes caption preset, grade, custom grade, transitions, fades and stylize into a single version.

Bringing media in

Inserts interrupt the program; overlays sit on top of it. Both accept anything in the project — uploaded, fetched from a link, or generated.

insert_media

Splice a clip or image into any position in the finished edit. Mid-take positions split the take around it.

remove_insert

Remove one insert by id; the surrounding timing is restored exactly.

add_overlay

Draw an image or video over the program picture for a window of time — picture-in-picture, a corner logo, or a full-frame cover.

move_overlay

Reposition, retime or resize an existing overlay.

remove_overlay

Remove one overlay by id.

fetch_url

Download media from a link the user gave you — a video, a song or an image — and save it as a project asset.

generate_video

Generate a short video clip with AI from a text prompt, or animate an existing image.

generate_image

Create an image with AI from a prompt, or by restyling a frame of the video.Requires an image provider key; hidden from the registry when unconfigured.

search_stock

Search a stock library for b-roll you do not have, at the project's aspect ratio.Requires a stock provider key; hidden from the registry when unconfigured.

add_stock_media

Download one stock search result into the project, choosing the smallest rendition that still covers the output frame.Requires a stock provider key; hidden from the registry when unconfigured.

Repair & censoring

Two different jobs that are often confused. Erasing removes something so it is gone; censoring puts a visible mark over something on purpose.

find_burned_text

Measure where text is burned into the footage — subtitle bands, watermarks, handles, on-screen labels — by reading the actual frames rather than estimating a rectangle.

erase_burned_text

Truly remove burned-in captions or watermarks: measures every matching region and repaints the pixels, reconstructing the background behind them.

erase_region

Truly remove whatever is inside one rectangle, repainting the background so the object is gone rather than covered.

remove_erase

Undo an erase and put the original pixels back. Every erase re-derives from the untouched original, so undo is exact and repaints never compound.

blur_region

Put a visible censor over a rectangle — blur, mosaic or a black bar — for when you want the censor to be seen. It follows the footage through later cuts and reframes.

remove_blur

Remove one censor region by id, or all of them.

Screen recordings & web demos

A headless browser can record a page, or drive a product and record itself using it — with a visible cursor and real click timings the edit can be cut against.

record_website

Record a live web page as video at the project's aspect: opens the URL, holds the top, smooth-scrolls to the bottom.

record_website_demo

Record a browser actually using a site — a visible cursor, real clicks and typing, captured with true timestamps.

showcase_demo

Place a screen recording and cut it like a product video in one call: splices the clip in, then puts a zoom on each click.

enhance_cursor

Make the mouse pointer bigger and steadier — it finds the real cursor in the frames rather than assuming where it was.

remove_cursor_enhance

Put the original pointer back, re-derived from the untouched source.

set_screen_frame

The floating rounded window on a gradient — the standard treatment for a screen recording or app demo.

remove_screen_frame

Remove the floating window; the picture goes back to full-bleed.

Rendering & asking

The loop that makes the editing agentic rather than fire-and-forget.

render_preview

Render the current edit as a fast preview from the proxy and get a visual self-check back — the agent looks at the frames it just produced.

ask_user

Ask one specific question and wait for the answer. Reserved for taste calls no tool can settle.

Frequently Asked Questions

Point Your Model at It

Create a free Valmera account, add the MCP endpoint to your client, and this whole registry is available in the conversation.