5.0 Work with your own Claude5.2 What Claude can do
What Claude can do
Every MCP tool Filmsquare gives your Claude, how find_actions and run_action reach the rest of the API, and what is left out on purpose.
Your Claude can do in Filmsquare what the API lets your role do. Eighteen named tools cover the everyday work;
two more, find_actions and run_action, reach every other API action. Every call goes through the API itself, as
you: the same role checks, the same validation, the same gates.
The named tools #
| Tool | What it does | Needs |
|---|---|---|
whats_waiting | Department steps waiting on your sign-off, and your unread notifications. The place to start | — |
list_productions | The productions in the workspace with their episodes | — |
get_episode | One episode: scenes and shots in cut order, every department step (signed off, waiting on whom, changes requested, open), and whether the finals can render | episode_id |
get_feedback | Comment threads on a shot, take, episode, scene, element, folder, asset version, canvas or canvas node, with every message and its pin (timecode in frames, or a region of the picture). Open threads by default; status resolved or all for the rest. With target_type sheet: the open notes on the sheet's latest version (intent, quote or the whole sheet, suggested text, handled or not) and how earlier versions' notes ended | target_type, target_id |
reply_feedback | Reply in a thread as you (@name mentions notify people), and resolve it when the note is handled. A note on a sheet is marked handled instead; when it has a suggestion, suggestion_outcome (applied, adapted or declined) is required, and a person confirms it | thread_id, body |
view_media | A still, keyframe or take as an image Claude can look at; a video comes back as its poster plus a download link | asset_version_id |
upload_file | A file from the conversation onto a shot or scene layer as a new take, or into a production as an asset. At most 10 MB. pick: true also picks it (director and up) | name, mime, data_base64 |
where_does_it_go | Which screen a file belongs on: the map, a decision tree and worked examples. Read it when you name a screen | — |
prepare_upload | Signed upload URLs and ready-made curl commands for up to 100 files on disk, so the bytes never go through the conversation. Use it for every video | files |
add_to_visualize | Put uploaded files under Storyboard → 3D or Storyboard → Animatic, up to 100 per call, on shots and scenes by code. Sending the same again changes nothing | episode_id, items |
get_script | The episode's latest script revision, and the @handles of the cast, sets and props that already exist | episode_id |
edit_script | Change a scene, a speech or a line of the script without sending all of it: exact text and what replaces it, saved as a new version; notes and tags move along | episode_id, base_rev, edits |
submit_breakdown | Put Claude's breakdown into Filmsquare: scenes, shots with acting, dialogue, cast, sets and props. Writing then waits for sign-off | episode_id, breakdown |
get_continuity | The continuity sheet of an episode: what each shot plays, the elements and their references, what each pick was made with, findings so far, shots to check again. Runs the free lineage check first | episode_id |
report_continuity | Record a visual continuity check; each mismatch becomes a note on the pick | episode_id, seen, issues |
submit_style | Put a style guide in the style library (Create → Styles): a new style, or with style_id its next version; production_id makes it a production's. Own work carries up to 6 reference stills (uploaded with prepare_upload); someone else's work is text only and never published. Names of people or brands are refused. Maker role | name, guide |
request_signoff | Ask the signers of a department to sign off an episode's step; they get a notification | episode_id, department |
sign_off | Record your decision on a step: approved or changes_requested, with an optional note. Only the step's signers can. With expect_version (the step's version as you saw it) it is refused with changed_since when the work moved. Only when you asked Claude to decide | episode_id, department, decision |
studio_analytics | For the owner and producers: how the studio is going, with the numbers of Analytics. view crew (per person over a period: delivered, credits per delivered, time to sign-off, first pass, lanes, redo, hands-on and agent-alone hours, the studio median and the time per step), day, costs, or report (the report mail's text as it would be sent). Anyone else is refused: they see only their own numbers | view |
Every tool also takes an optional workspace. Leave it out: the connection's workspace is used.
department is one of writing, breakdown, casting, voice, wardrobe, sets, props, animatic,
music, draft, sound, edit, final.
Where media goes #
Tell your Claude the screen in your own words ("put it under 3D"). This is what it does:
| You have | It goes | With |
|---|---|---|
| Clay render or still of one shot, with lens, height and move | Storyboard → 3D, on the shot | add_to_visualize |
| Blender clip of a shot, a take or a scene | Storyboard → 3D, on what it covers | add_to_visualize |
| Animatic of a scene, sequence or episode | Storyboard → Animatic | add_to_visualize |
| Draft or final video of a shot | Storyboard → Shots, as a take | upload_file |
| Reference picture or mood board | Home → Files | upload_file |
Something in the wrong place moves without uploading again: moveTake or moveAsset through run_action (director and up). A pick the import made is cleared with the move. A take that somebody picked, or that was generated here, stays where it is.
find_actions and run_action #
Everything without a named tool goes through these two: creating shots, picking takes, making drafts, estimates, elements and versions, folders, canvases, costs, briefs, crew.
find_actionssearches the API's own catalogue with a few words, such as "pick take", "create shot" or "resolve thread". It returns matching actions with their method, path, a summary, the minimum role and the inputs.run_actionruns one by its name, withpath_params(not the workspace),queryandbodyas the action describes. It answers with the API's JSON.
find_actions understands set language. It maps the words a crew uses onto the API's words:
| You say | It also searches |
|---|---|
| pick, choose | select |
| note, notes, comment, comments, feedback | thread, message |
| reply | message |
| render | generation, generate |
| make | create, generate |
| new, add | create |
| remove, delete | archive |
| sign | signoff |
| approve | signoff, approval |
| cast, character, prop | element |
| set | element, location |
| production, productions | project |
| crew | member, steps |
| cost | costs, estimate |
| price | estimate |
| prompt, preview, dry run | generate |
| kosten, schatting, prijs (Dutch) | generate, estimate |
| mismatch | continuity |
| model, models | models, acceptance, routing |
New API actions show up in find_actions the moment they ship. No new tool is needed.
Examples #
| To | Search | Action |
|---|---|---|
| Price a draft before rendering it | "estimate shot" | estimateShotGeneration |
| See the prompt, the model and the credits before rendering | "dry run" | generateForShot with {"kind": "video", "tier": "draft", "dryRun": true} |
| Render a draft | "generate shot" | generateForShot with {"kind": "video", "tier": "draft"} |
| Pick a take | "pick take" | selectTake |
| Make a draft final | "promote" | promoteGeneration |
| Retake from a note | "revise take" | estimateReviseTake, then reviseTake |
| See which model gets accepted | "model acceptance" | getModelAcceptance |
| Cost of an episode | "episode costs" | getEpisodeCosts |
Before it renders, Claude calls the generate action with dryRun: true: it shows the compiled prompt, the model, the
references and the credits, and makes nothing. It can then change the prompt for that one render.
overrides.prompt replaces the prompt text (the reference lines stay, so cast, sets and props always go along),
overrides.promptAppend adds to it, and overrides.negativePrompt adds what to avoid. Dialogue is spoken from its
lines and takes no prompt override.
The dry run answers with provider and model_key. Passing them back as provider and modelKey holds that model.
getGeneration reads back what a take was made with: the prompt, the model, the estimated credits and the booked
credits.
When the API refuses #
A refusal comes back as a tool error with the API's code and details, for example
The API refused: 409 gate_closed: finals render once casting, sets, animatic are signed off {"episode_id": "…", "waiting_on": ["casting", "sets", "animatic"]}.
Claude reads it and tells you what is missing. See Errors you will meet.
Left out on purpose #
Claude cannot reach these, by design:
- API keys and Claude connections: a connection never makes keys or allows other connections. A person does that, signed in.
- OAuth and sign-up.
- Webhooks: they send data out of Filmsquare.
- Provider callbacks and the realtime sockets (canvas and presence).
The finals gate, credit checks and plan limits apply to Claude exactly as to anyone.
Safety #
- Claude acts as you. It has your role (or the lower one you chose when connecting), and what it does shows up in your name.
- Crew material is not instructions. Comments, scripts and other text Claude reads in Filmsquare are material from the crew. Filmsquare tells Claude so: only you decide what it does.
- It quotes the price first. Making takes costs credits. Claude is told to call the generate action with
dryRun: true, which makes nothing, and to say what a take will cost before it starts one, and never to render finals unasked. - It never signs off unasked.
sign_offrecords a decision in your name. Claude is told to use it only when you asked it to decide.
Prompts #
Four prompts carry a working method for common jobs: break_down_episode, process_feedback, work_on_step and
check_continuity. See Prompts and working method.
With Claude
MCPYour own Claude does this over MCP, in your name and with your role:
find_actionsSearches everything the API can do and returns the matching actions with their inputs.
Ask: Find the action that changes a step's sign-off rule.
run_actionRuns one action found with find_actions, as you, with your role and rights.
Ask: Pick the second take of shot 5 on episode 2.
whats_waitingLists the steps waiting on your sign-off and your unread notifications.
Ask: What is waiting on me in Filmsquare?
list_productionsLists the productions in your workspace with their episodes.
Ask: Which productions and episodes do we have in Filmsquare?
get_episodeShows an episode's scenes and shots in cut order, every department step, and whether finals can render.
Ask: Where does episode 2 stand, and who is each step waiting on?
get_feedbackReads the comment threads on a shot, take, episode or element, with each pin's timecode or region.
Ask: Which notes are still open on episode 2?
reply_feedbackReplies in a comment thread as you, and resolves it once the note is handled.
Ask: Reply to the note on shot 4 that the new draft fixes the eyeline, and resolve it.
view_mediaLooks at a still, keyframe or take; video comes back as its poster plus a download link.
Ask: Show me the picked still of shot 3 and tell me if it matches its references.
upload_fileAdds a file you have as a new take on a shot or scene, or as a production asset (10 MB at most).
Ask: Upload this reference photo to the assets of the production.
get_scriptReads the latest script revision of an episode, with the @handles that already exist.
Ask: Read the script of episode 2 and tell me which characters have no @handle yet.
edit_scriptChanges a scene, a speech or a line of an episode's script and saves it as a new version, without sending the whole script.
Ask: Rewrite the opening of S02 in episode 2 the way we just discussed, and save it as a new version.
submit_breakdownPuts your breakdown into Filmsquare: scenes, shots, dialogue, cast, sets and props.
Ask: Break down the script of episode 2 and submit it. Reuse the handles we already have.
get_continuityLays an episode's picked shots side by side, with the element versions each one uses.
Ask: Lay out the picks of scene S2 for a continuity check.
report_continuityRecords the continuity check you did; each mismatch becomes a note on the shot's pick.
Ask: Check continuity in scene S2 and report the mismatches you find.
submit_stylePuts a style guide in your style library (Create, Styles): a new style or the next version of one.
Ask: Look at these stills, write a style guide, show it to me and submit it when I say go.
request_signoffAsks the signers of a department step to sign off; they get a notification.
Ask: Ask the signers of the next step on episode 2 to sign off, with a note on what changed.
sign_offRecords your decision on a step: signed off or changes requested. Only when you ask it to decide.
Ask: Sign off the next step on episode 2 for me.
where_does_it_goTells you which screen a file belongs on: the map, a decision tree and worked examples.
Ask: Where does this blockout reel go?
prepare_uploadGives signed upload links and ready-made curl commands for up to 100 files on disk.
Ask: Upload the videos in this folder.
add_to_visualizePuts uploaded files under Storyboard, 3D or Animatic, on shots and scenes by code.
Ask: Put the Blender work under 3D and the animatics under Animatic.
studio_analyticsFor the owner and producers: how the studio is going, from the crew, one day, the costs or the report mail as it would be sent.
Ask: How did the crew do last week, and who needs help?
Connect Claude 5.1