MCP tool reference

Squall MCP Tools

The current MCP server exposes 25 tools across read, edit, and generation workflows. Tool handlers call the same service layer as the web app, so ownership, billing, precondition, and scope checks still apply.

Read tools

Read the production state an agent needs before planning edits or generation.

Requires projects:read

list_projects

List all projects owned by the API key's account.

Required inputs

None

Optional inputs

None

Output

Project summaries.

get_project

Get one project's summary and current workflow step.

Required inputs

project_id

Optional inputs

None

Output

Project summary.

get_project_episodes

List the episodes in a project.

Required inputs

project_id

Optional inputs

None

Output

Episode records.

get_episode

Get one episode record.

Required inputs

episode_id

Optional inputs

None

Output

Episode record.

get_episode_editor

Get the full episode tree in one call: project, episode, outline, script, segments, shots, characters, looks, locations, and jobs.

Required inputs

project_id

episode_id

Optional inputs

None

Output

Episode editor payload.

Prefer this before multi-step episode review because it reduces lookup drift.

get_episode_shots

List the shots in an episode.

Required inputs

episode_id

Optional inputs

None

Output

Shot records.

list_episode_segments

List the video segments in an episode.

Required inputs

episode_id

Optional inputs

None

Output

Episode segment records.

get_scene_assets

Get one scene with its shots, characters, locations, and continuity references.

Required inputs

project_id

episode_id

scene_number

Optional inputs

None

Output

Scene asset payload.

get_project_script

Get a project's full script package.

Required inputs

project_id

Optional inputs

None

Output

Project script payload.

get_project_characters

List a project's characters.

Required inputs

project_id

Optional inputs

None

Output

Character records.

get_character

Get one character record.

Required inputs

character_id

Optional inputs

None

Output

Character record.

get_character_looks

List a character's looks.

Required inputs

character_id

Optional inputs

None

Output

Character look records.

get_project_locations

List a project's locations.

Required inputs

project_id

Optional inputs

None

Output

Location records.

get_location

Get one location record.

Required inputs

location_id

Optional inputs

None

Output

Location record.

get_asset_library

List generated assets available to a project.

Required inputs

project_id

Optional inputs

None

Output

Asset library payload.

get_job

Get one generation job's status and output.

Required inputs

job_id

Optional inputs

None

Output

Generation job status and output.

Use this to poll jobs returned by generation tools.

list_project_jobs

List generation jobs for a project, newest first.

Required inputs

project_id

Optional inputs

None

Output

Generation job records.

Edit tools

Patch authored production data after reading it first.

Requires script:write

update_shot

Overwrite selected fields on one shot.

Required inputs

shot_id

patch

Optional inputs

None

Output

Updated shot record.

Send only changed fields. Dialogue edits go through camera_setup.short_shots[].dialogue_covered. Writes immediately and cannot be undone.

update_location

Overwrite selected fields on one location.

Required inputs

location_id

patch

Optional inputs

None

Output

Updated location record.

Locations are shared across scenes. Text/image-affecting edits mark the existing location image stale; mood and episode assignment edits do not.

Generation tools

Start billed async generation jobs and poll them with get_job.

Requires generation:write

generate_script

Write a full multi-episode script from a premise, as a new project.

Required inputs

story_idea

episode_length_seconds

idempotency_key

Optional inputs

episode_count

screen_ratio

genre

target_platform

language

visual_style

Output

New project id, generation job id and next route.

Creates a new project rather than acting on an existing one. The longest job in the system — poll get_job for phase and completedEpisodes.

generate_shot_clip

Generate a video clip for a single episode shot.

Required inputs

shot_id

idempotency_key

Optional inputs

model

short_shot_number

Output

Generation job id and status.

Idempotency keys prevent duplicate billed jobs on retries.

generate_character_image

Generate a reference image for a character.

Required inputs

character_id

idempotency_key

Optional inputs

character_look_id

reference_image_asset_ids

user_notes

Output

Generation job id and status.

generate_location_image

Generate a reference image for a location.

Required inputs

location_id

idempotency_key

Optional inputs

reference_image_asset_ids

user_notes

Output

Generation job id and status.

generate_shot_background_image

Generate an empty background plate for one short shot.

Required inputs

shot_id

short_shot_number

idempotency_key

Optional inputs

reference_image_asset_ids

Output

Generation job id and status.

generate_episode_music

Generate a background music track for an episode.

Required inputs

episode_id

idempotency_key

Optional inputs

None

Output

Generation job id and status.

Requires the episode to already have an assembled video.

Setup Guide Workflow Examples