Tool guide

Your MCP client discovers the available tools and their input schemas when it connects. This guide explains how the main groups fit together.

Tools that act on a film take a projectId. Start with listProjects to find an existing ID, or createProject to make a film. Workspace-level tools, such as listing projects, don't require one.

Projects

Script and storyboard

Scene tools add, edit, remove, and reorder scenes. A scene includes action, dialogue, and duration. Element tools manage cast, locations, and props. These changes appear in the project's Script and Board tabs.

Use IDs from readBoard when editing a project that may change during the session. Scene tools accept sceneId as well as sceneNumber, and element tools accept IDs in place of names. An ID stays the same when scenes are reordered.

Models and style

Call listGenerationModels to see the available models, prices, and supported settings. Use setVisualStyle, setGenerationDefaults, and setGenerationModel to configure the project and individual generations.

Generation order

1. References: generate character, location, and prop images.
2. Look approval: review the images and approve the references to use.
3. Frames: generate scene images with the approved references.
4. Clips: animate the selected frames.

The tools report missing prerequisites when a render can't start. checkGenerations reports current jobs; waitForGenerations waits for jobs to finish.

Render tools accept an optional idempotencyKey. Reuse that key when retrying the same request after a connection failure to avoid creating a second job. Use a new key when you want another take.

Review references

reviewElementLooks returns reference images for inspection. approveElementLook can approve a reference, unlock it for revision, or mark an element as reference-free when no image is needed.

Decide whether your agent should approve looks itself or show you the images first. A poor reference can affect every scene that uses it.

Control spending and reuse media

Call estimateCost before rendering and use the key's approval mode or a temporary budget to authorize the work. whatsNext includes the remaining approved budget.

Use browseLibrary and searchMedia to find existing media before generating more. Attaching an existing file doesn't start a new generation.

Audio and export

Assign a voice to a character, then generate speech from dialogue attributed to that character. For narration, use a voice-only cast member and add their lines to the relevant scenes.

Use assembleTimeline to arrange the clips, exportFilm to start an export, and checkExport to read its progress and result.

Activity

MCP work appears in the project's activity history. Open the assistant with the bot icon, then click the Activity icon in its header. Use History to look beyond the current browser conversation.

readAgentActivity lets an external agent inspect recorded work, including calls made by the in-app assistant. It can use errors and costs from that history when explaining a failed job or continuing a project.

Structured results and resources

Read tools return text plus structured content with an advertised output schema. Clients can use the structured board, job list, or estimate directly instead of parsing prose.

The server also publishes resources:

Replace {projectId} with the film's ID. Clients that support resource completion can suggest it. Resources use the key's workspace permissions and reading them doesn't create an activity entry.

The separate free-form writing document and in-app script-generation controls are browser features. An external agent writes its own content and applies it through the scene and project tools.