Use Filmera from AI agents (MCP)

Filmera exposes its studio — projects, canvas nodes, generation, media, timeline and export — to AI agents through the Model Context Protocol (MCP). Connect it once and your agent can plan shots, generate takes, assemble a cut and export the film, using your Filmera credits.

Endpoint: https://www.filmera.ai/api/mcp (Streamable HTTP)

Every MCP client connects the same way: add https://www.filmera.ai/api/mcp as a connector (or remote MCP server) and sign in. The first time the agent calls a Filmera tool your browser opens the Filmera sign-in, you approve access, and the client keeps the token and renews it on its own.

API keys don't work for MCP. A request to /api/mcp that carries an API key (Authorization: Bearer fk_…) is refused with 401 api_key_not_supported. If you set Filmera up with a key before, remove the Authorization header from your client's config and reconnect — the client then starts the sign-in by itself. API keys still work for the REST API, for scripts and automation.

The agent acts as you: it sees only your projects, and every generation is charged to your credits.

Credits, approval and spending caps

A connected agent spends your Filmera credits at the same prices as the studio — there is no separate budget to set up.

By default, an agent needs your go-ahead in the conversation before it spends. When the agent asks Filmera to generate, nothing runs yet: it gets back the cost (a quote) and tells you what it will make and what it costs. Once you say yes ("go ahead", "진행해"), it asks again with the quote and your reply, and Filmera records those words with the run. If the cost has gone up since the quote — say the agent switched to a pricier model — Filmera hands back a new quote and the agent has to ask you again.

Filmera cannot see your conversation, so this relies on the agent passing along what you actually said. It is not a hard lock. For a hard ceiling, set a spending cap (below).

If you trust an agent to spend on its own, turn the check off for that agent under Settings → API keys (Connected agents) ("Ask me in the chat before this agent spends credits"). It then generates immediately, as the studio does when you click.

If you want a hard ceiling, set a spending cap for a connected agent on the same page. Generation calls stop once that agent has spent its cap. You can disconnect an agent from the same page.

Connect

Inside the studio, the Connect agent button in any project's header walks you through this for Claude, ChatGPT, Gemini, Grok, Claude Code and Cursor, with the server URL and commands ready to copy.

Claude.ai / Claude Desktop

One click: Add Filmera to Claude opens Claude's Add custom connector dialog with the name and URL already filled in. Claude notes that the values came from an external link — check them and click Continue, then sign in when prompted.

By hand: Customize → Connectors → Add custom connector → URL https://www.filmera.ai/api/mcp. Sign in when prompted.

ChatGPT

Custom plugins need Developer mode, available on the web for Plus plans and above. Turn it on in Settings → Security, then open Plugins:

Click + at the top right → Create app → Create MCP app.
Name it Filmera. Under Connection, keep Server URL and paste https://www.filmera.ai/api/mcp. Leave Authentication on OAuth.
Tick the custom-MCP risk acknowledgement and click Create.
Sign in to Filmera when prompted.

Gemini

Gemini has no link that fills in the connector for you, so you paste the URL once.

Gemini web (custom apps). Google currently offers custom apps only in the US, to people 18 or older signed in with a personal Google account, with the app in English and Keep Activity turned on. Work and school accounts can't add them.

On gemini.google.com open Connected Apps (Settings → Connected Apps, or Customize → Connectors).
Under Custom apps click Add a custom app, paste the endpoint above and click Next.
Sign in to Filmera when prompted.

You can add the app only on the web, but it then works in the Gemini mobile app too. To make sure Gemini uses Filmera, type @ in a chat and pick it.

Gemini CLI. Since June 18, 2026 Gemini CLI works only with a paid Gemini API key or a Gemini Code Assist Standard or Enterprise license; Google AI Pro, Ultra and free accounts moved to Antigravity CLI. If you have one of those, run this once: gemini mcp add --transport http --scope user filmera followed by the endpoint above. --scope user adds Filmera for your user account; without it the server only shows up in the folder you ran it from.

gemini mcp add --transport http --scope user filmera https://www.filmera.ai/api/mcp

The first Filmera call opens the sign-in in your browser. If you need to sign in again, run /mcp auth filmera inside Gemini CLI.

On Gemini Enterprise only a team admin can add custom MCP servers, and these steps don't cover that setup.

Grok

On grok.com open Connectors, click New Connector → Custom, paste https://www.filmera.ai/api/mcp and sign in when Grok asks. Grok discovers the Filmera tools on its own; the server has to be reachable on the public internet, which it is. On Grok Business and Enterprise a team admin adds the connector in the console first, then members can use it.

Claude Code

claude mcp add --transport http filmera https://www.filmera.ai/api/mcp

Claude Code opens the browser sign-in the first time it calls Filmera. Run /mcp inside Claude Code to sign in again. Don't add --header "Authorization: …" — API keys are refused on MCP.

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "filmera": {
      "url": "https://www.filmera.ai/api/mcp"
    }
  }
}

Cursor opens the Filmera sign-in on first use. Leave out a headers entry — API keys are refused on MCP.

Codex / other clients

Any MCP client that supports Streamable HTTP and OAuth 2.1 sign-in (with dynamic client registration) works. A client that can only send a fixed API-key header can't connect to MCP — use the REST API from it instead. The server is stateless — no session resume, no SSE stream.

What the agent can do

| Group | Tools | | --- | --- | | Read | get_guide (the agent playbook) · list_projects · get_project (every node's position, and each video and image node's model and settings) · get_timeline · list_models (ids, settings, each model's prompt length cap and its reference limits — how many images, videos and audio clips it takes, how long a clip may be, image sizes) · search_voices (ElevenLabs voices for voice_id) · list_media · list_folders · get_credits · get_node_references · read_node_prompt · view_media · list_presets · compare_prices (credits per model for the same settings) · get_download (direct URL and the app's filename) · list_showcases · get_chat_history (your own messages with the in-app agent in a project, newest first) · list_templates / get_template (the public template gallery — full prompts when a template's prompts are open, the website's preview when it is showcase-only) | | Build | create_project · rename_project · create_image_node · create_video_node · create_audio_node (voice, music or SFX node with its recipe) · update_audio_node (its script, model, voice, references or settings — generated nodes too) · import_media_from_url · upload_media · create_media_folder · rename_media_folder · move_media · organize_canvas · create_section · move_nodes_to_section · move_nodes · resize_section · update_node_prompt · connect_nodes · disconnect_nodes · delete_nodes · set_frame_slots · set_film_meta · create_note · update_note · add_take_from_media (an uploaded file as a new take on a node) · set_take_recipe (record an uploaded take's prompt, model and settings) · set_node_kind · save_preset · apply_preset · add_scene · update_scene | | Several at once | create_ref_nodes (up to 8 image nodes from prompts the agent wrote) · create_video_nodes (up to 8 video nodes) · draft_storyboard (save the scenes it wrote) | | Generate (spends credits) | generate_ref_nodes · generate_video_nodes (both take takes_per_node 1-4) · generate_audio (SFX, score, change voice, clean) · generate_audio_node (a take on an audio node with any audio model — text-to-speech, music, SFX, or ElevenLabs speech-to-speech) · generate_character_voice · generate_retake (new take on an existing node — prompt, model, settings, keyframes or voices) · generate_upscale · generate_vfx (swap actor, replace background, add/remove object, relight, extend shot) | | Edit & finish | assemble_timeline (generated video nodes or video files, in order) · create_timeline · duplicate_timeline · rename_timeline · set_frame_ratio · edit_tracks · edit_timeline · undo_timeline_edit · place_audio_take · set_best_take · extract_last_frame · export_timeline | | Review (Theater, free) | get_take_analysis (a take's full check — shots, dialogue, every flag and note, and the model's raw output) · list_fix_requests · keep_flags / unkeep_flags (mark a flag as intended) · decide_fix (use the new version or keep the old) · undo_fix · set_story_order (the order the Theater plays) | | Wait | get_job_status · wait_for_jobs · check_effects | | Feedback | report_feedback (sends a bug report or a missing-feature note to Filmera's team — see below) | | Manage (all reversible) | rename_media · set_media_flag · trash_media · restore_media · trash_project · restore_project · duplicate_project · share_project (read-only link) · publish_showcase / unpublish_showcase (Community gallery) · duplicate_template (copy a public template into a new project, like its Duplicate button) |

With the check on (the default), the first generate call returns status: "confirmation_required" with the cost and a quote_id — nothing runs. After you agree, the agent calls again with quote_id and user_confirmation (your reply, word for word).

The quote also carries the reference warnings the editor shows next to a clip — references the model will drop because it takes fewer, character voices left out, a character mentioned but not connected — as warnings on each item, with a short code for each in warning_details. create_video_node, update_node_prompt and connect_nodes report the same warnings as soon as they apply.

If the connection drops and the agent is not sure the generation started, it sends that same call again, unchanged. A run that already started answers status: "already_started" with its original job_ids, and you are not charged a second time; idempotency_in_progress means the first call is still being processed, so the agent tries again a moment later. Agents can also pass their own idempotency_key (any unique string) to get the same protection, and a fresh quote lists recent_jobs already running on the same nodes.

Fewer permission prompts

Every tool in the Read row is marked read-only in the catalog (the MCP readOnlyHint annotation), and the tools that delete or replace something — delete_nodes, assemble_timeline, edit_timeline, undo_timeline_edit, trash_media, trash_project, share_project (turning a link off revokes it) — are marked destructive. Nothing is deleted permanently through the API: trashed media and projects come back with restore_media and restore_project. Clients that honour the annotations run the read-only tools without asking. Clients that ask for every call have their own allow lists: in Claude.ai choose Always allow on a tool the first time it asks; in Claude Code answer Always allow at the prompt, or add the tool names (mcp__filmera__get_project, mcp__filmera__list_media, …) to permissions.allow in your settings via /permissions. Generation tools keep asking — that prompt is on purpose, since they spend your credits.

The agent playbook

Filmera tells a connected agent how to work before it builds anything. The server instructions point it at get_guide, which returns one chapter of the playbook at a time — rules (read the project first, spend only with approval, set every setting explicitly, retake instead of duplicating, keep the canvas tidy), canvas (which tool does what, limits, section naming), prompts (what a reference set needs and how a clip prompt is shaped), workflows (idea to film, reference clip to film, an upscale template, music and voice) and troubleshooting (content blocks, snapped settings, drift, upload and approval errors). The same chapters are published as MCP resources at filmera://guide/<topic> for clients that attach resources on their own.

Four more chapters are Filmera's own film craft, published word for word from the instructions its in-app agents follow: sheets (character model sheets, empty location plates, prop sheets, second looks), video (the timestamped prompt shape, the closing Constraints block, identity locks, first frames), performance (beats, acting, camera, dialogue, sound) and story (breaking a brief into scenes). The agent reads one chapter per call. Clients that support MCP prompts — Claude Code lists them as slash commands — also get write_reference_sheets, write_video_prompts and design_story, which hand the agent the task and the matching craft in one message. The same chapters are a downloadable agent skill for agents that are not connected yet.

Changing a clip's voice

There are two ways, and they trade off differently. generate_audio with op: "voice" keeps the picture untouched and only re-performs the dialogue — cheap, but the lip sync is still the one the clip was generated with. generate_retake with voice_node_ids regenerates the shot with that voice attached, so the model performs and lip-syncs it — a new take on the same node, at video prices.

Either way the voice has to come from somewhere: a character node that has a voice (generate_character_voice), or an audio file you upload — upload_media puts audio on the canvas as a node you can connect. For op: "voice", every speaker in the clip needs a character; when the names in the prompt do not match, pass speaker_voices to say who performs whom.

Generation is asynchronous: a generate call returns immediately with job_ids, and the agent waits on them with wait_for_jobs (it long-polls up to 50 seconds per call) until all_done is true — every job is done, failed or not_found (listed in missing), and polling again would not change any of them. A generate call that fails returns job_ids: [] with all_done: true, error and retryable, so there is nothing to wait for. Clients must send Accept: application/json, text/event-stream (every MCP client does; only hand-written curl calls need care).

Who writes the prompt

Your agent does — every prompt, with its own model. Filmera supplies the craft (the chapters above) and the tools; it does not run its own models to write prompts for a connected agent. create_image_node and create_video_node take one finished prompt, on any plan. create_ref_nodes and create_video_nodes take up to eight the agent wrote, with the same fields per item, and draft_storyboard saves the scenes it wrote. Nothing is charged until a generate tool runs. The prompt length cap is the model's, not the tool's: list_models reports prompt_max_chars for each model, and a prompt over the cap is refused with a model that would fit.

Until 23 October 2026 those three tools took a one-line brief and Filmera wrote the prompt on its servers. An agent that still sends a brief gets status: "needs_prompts" back — nothing is created, and the answer names the chapter to read and the shape to call again with. The in-app agent (the chat in the studio) still writes prompts for you as before.

Pointing at a reference by name

Inside a node prompt, write @Name to point at another node on the canvas:

@Anneke stands by the @Workroom window, the pearl catching the light

Filmera attaches those nodes as references and numbers them for the model at generation time. Write the name, not a number — @Image1 and friends are refused, because the numbering depends on the final attachment order and a hand-written number silently points at the wrong picture once that order changes. Names are matched loosely, so @ANNEKE, @Anneke and @anneke all find a node titled "Anneke". If a name matches nothing, or matches two nodes, the tool says so in its reply and leaves your text alone.

The numbers themselves are worth understanding, because they are not simply the order you connected things. References are numbered in the order they are sent to the model: locked keyframes first, then a first-frame anchor, then character sheets, then the connected reference nodes in their own order — and the sheets take numbers too, so three connected nodes are not always @Image1–@Image3. Connections keep the order you make them in (connect_nodes uses the order of the list you pass, and adding one later puts it at the end). To see exactly which number each reference has on a given node, call get_node_references.

Revising a shot

A node's prompt and settings freeze the moment it generates — they are the recipe that produced the takes, so update_node_prompt refuses to rewrite them. That does not mean an agent has to start a new node to change something.

generate_retake runs an already-generated node again with a revised prompt, and optionally a different model, different settings, or different pinned first/last frames. The result arrives as another take on the same node, and the earlier takes stay where they are — the same thing the Retake button does in the app. Use it for "again but slower", "warmer light", "try the other model", "start from this frame instead". Start a fresh node only when it is genuinely a different shot, otherwise the canvas fills up with variants of one idea and nothing says which is current.

read_node_prompt is how an agent gets the recipe to revise: the node summaries in get_project are abridged, so a rewrite built from them loses detail. It returns the ★ take's exact prompt, model and settings, free of charge.

Audio nodes work the other way round: their recipe — script, model, voice, references, tuning — stays editable after generating, because each take is made from the recipe as it is at that moment. update_audio_node changes it (only the fields you pass), and the next generate_audio_node run makes a take with the new recipe while earlier takes stay.

When an agent tries to rewrite a generated node's prompt, the refusal tells it which of the two applies. A small tweak to the same shot is sent straight to generate_retake; a prompt describing something else is sent to a new node. When the new prompt sits between the two — the same character in a different framing, say — the tool asks the agent to check with you first, because a take and a node are not interchangeable: takes are versions of one shot, nodes are different shots.

Organising the canvas

The simplest way is to organise as you build: create_image_node, create_video_node, create_ref_nodes and create_video_nodes take an optional section — a title such as "Characters" or "Scene 1", or a section id. The node goes into that section in a grid of four columns; if no section has that title yet, one is created below everything else on the canvas. create_video_nodes uses its scene_name when you leave section out. Nodes created without a section fill rows of six and then start a new row, so the canvas never runs off to the right.

organize_canvas lays the whole canvas out in one call. Reference images go into numbered sections stacked in a column on the left — 00 · CLIENT PHOTOS (your uploads), 01 · CHARACTERS, 02 · ENVIRONMENTS, 03 · PROPS and 06 · FRAMES (extracted stills) — in the order the videos attach them. Video nodes go into 04 · VIDEO SEQUENCES in a column to the right, in timeline order and centred on the references, and audio goes into 05 · AUDIO below the video. Boxes fit their nodes and are coloured (characters pink, props red, environments green, video blue). Sections you made yourself are moved as a block into the matching column, notes stay where they are, and nothing is deleted; running it again on an organised canvas changes nothing. dry_run: true shows the plan without moving anything, and rename_nodes: true also numbers the titles ("01 · Mina", "GEN 1 · Opening — 8s"). create_section takes a color too.

create_section draws a titled group box, sized to enclose whatever nodes you pass it — the same Section tool that is in the app, so a project can carry the Characters / Environments / Props / Clips structure the media folders have. move_nodes_to_section puts existing nodes in one (or takes them out with section_id: null); the box grows to fit and nothing moves on screen. To rename a section, call update_node_prompt with just a title.

get_project reports every node's x, y, w and h in absolute canvas coordinates, and move_nodes puts nodes anywhere in that same space — so an agent can read a canvas that has piled up and lay it out properly: a row of shots, their references stacked above each one, a grid per scene.

Where a node lands decides which section it is in, exactly as dragging it would: drop it inside a section's box and it joins (the box grows to stay around it); move it off and it leaves. Moving a section itself moves everything inside it. resize_section changes a group box without moving its contents — it will not shrink past the nodes it holds, and tells you the size it actually got.

Seeing the results

view_media returns the picture itself in the tool result, so an agent can look at what it generated instead of describing it from the prompt. Give it a node id (its selected take, or take_index for a specific one) or a file id; video takes come back as their poster frame. Audio has no picture, so for an audio take the result reports its duration and URL instead. It sends a downscaled copy for viewing and the full-resolution URL alongside — useful because agent sandboxes often cannot fetch media URLs directly.

Editing the cut

assemble_timeline lays whole clips end to end. For anything finer, the agent reads get_timeline — every clip with its position, length, source in/out points and the gaps between clips — then sends a batch of edits to edit_timeline: trim a clip's source in/out (with ripple: true the clips after it on the same track move up so no gap opens), move it in time or to another track, split it, delete it (optionally closing the gap behind it), close every gap on a track with close_gaps, set per-clip volume and mute, or place a clip in the frame with set_transform (scale and offset — a small picture-in-picture over a background on a lower track — or fit: "fill" to cover the frame, for example a landscape clip on a 9:16 cut; Filmera works out the scale). get_timeline also says whether each clip is a video or an image, and the timeline's frame shape. Times are seconds on a 24 fps grid, and the same rules the editor uses apply: minimum clip length, source bounds, and audio detached on V2 gets cut with its video.

Music and sound go on with add_audio in the same batch: any audio file in the media pool — one you uploaded with upload_media or import_media_from_url, or a generated one — on an audio track, with its own start, in/out points and volume. place_audio_take does the quick version (a whole take, on a timeline you name with timeline_id); it accepts the file id, a take id or an audio node id, and says which timeline it used.

Two things make this safe to hand to an agent. It can pass preview: true to see the resulting timeline without writing anything, and expected_version from the read, which refuses the write if you or another agent changed the timeline in the meantime. undo_timeline_edit walks back the last batch, up to 20 steps.

assemble_timeline places each clip's ★ best take (set_best_take). When the cut is right, export_timeline renders it and returns job_ids; wait_for_jobs on those hands back output_url once the file is ready.

Close the Edit page while an agent reshapes a timeline. The editor keeps its own copy of the cut and saves it after your next change, which would overwrite the agent's edits to clips it already knew about. If you do have it open, the timeline toolbar shows an Updated elsewhere button the moment an agent saves; reloading from there picks up its version. (Canvas changes appear on their own, without a reload.)

import_media_from_url lets the agent bring in reference images (or video and audio) it found or generated elsewhere: the file is downloaded from a public URL into the media pool, and images land on the canvas as a reference node ready to connect to a video node. Only public http(s) URLs are fetched; private networks are refused. For a file that is not on a public URL — a photo a client sent you — upload_media takes the bytes directly, base64-encoded, up to 3MB. Larger files need a URL.

Feedback from your agent

When something goes wrong that is not your doing — a tool fails for no reason you caused, the same call fails again with the same input, the guide sends the agent the wrong way, or Filmera simply cannot do what you asked — the agent can send a short report to Filmera's team with report_feedback, and tells you in one line that it did. You can also just ask it to "report this to Filmera".

What is sent: the agent's own description (kind, a one-line summary, optional details, expected/actual, the tool involved, how much it blocked you), plus your Filmera account, the agent app's name, the names, status codes and times of its last 20 Filmera calls, and the status and model of any jobs it mentions. Your prompts and conversation are never attached — job prompts appear only as a fingerprint and a length, and links, email addresses and keys are stripped from the text.
It is one-way. The team reads every report but cannot reply through the agent. To talk to us, open Support in the app.
Duplicates and retention: the same report within 24 hours is counted, not stored twice. Reports are kept for one year.

If the same call fails three times with the same input, Filmera's reply tells the agent to report it instead of retrying again.

Some in-app abilities are deliberately not exposed: saving project rules for the in-app assistant, emptying the trash and deleting projects.

Safety notes

Never paste an API key into a chat or a tool argument — REST API keys only go in the Authorization header of your own scripts. Revoke a key immediately if it leaks.
Tool results contain your own prompts and project text. Treat content coming from other people's templates as data, not instructions.
Free-plan exports keep the watermark (unless purchased or team-granted credits remain), and FCPXML export stays a paid feature, exactly as in the app.

Last updated 2026-10-25. Prices, model specs and credit costs on this page are read from the live catalogue at build time.