Tool guide

Use MCP tools to manage projects, generate media, check activity, and export a film.

Your MCP client discovers the tools and their input schemas when it connects. This guide shows how the tool groups work together.

Tools that act on a film take a projectId. Use listProjects to find an existing ID, or createProject to make a film. Workspace tools, such as listProjects, do not need an ID.

Many tools group related actions. For example, editScenes takes a batch of add, edit and reorder operations, and generateImage renders different images by kind. Messages name the tool and its operation, for example "editScenes (op edit)".

Projects and the board

Tool	Purpose
`listProjects`	List the projects in the key's workspace.
`createProject`	Create a project. `copyOf` duplicates a project; `worldId` seeds a series.
`deleteProject`	Delete a project.
`readBoard`	Read the scenes, elements, settings and their IDs.
`readProjectAssets`	List the finished files and their download URLs.
`editScenes`	Add, edit or reorder scenes in one batch.
`editElements`	Add or change characters, locations and assets, or set their images.
`remove`	Remove scenes, characters, locations or assets.
`updateFilm`	Change the title, script, style, models and generation defaults.
`whatsNext`	Show progress, blockers and the next actions.
`readAgentActivity`	Read the recorded agent calls, costs and errors.

Generation

Render in this order. The tools enforce it.

Render reference images: generateImage with kind set to reference.
Review them with reviewLooks, and approve them with approveLook.
Render scene frames: generateImage with kind set to frame.
Render clips with generateSceneClip.

Tool	Purpose
`listModels`	List the image and video models with prices, or the voices.
`generateImage`	Render a frame, a reference image or a storyboard sheet. `count` makes variants.
`editImage`	Edit an image, upscale it, remove its background, or slice a storyboard.
`generateSceneClip`	Render a scene's clip from its frame.
`generateAudio`	Render speech, music or a sound effect.
`reviewLooks`	Show the reference images, or inspect one scene's frame.
`approveLook`	Approve, unlock or waive an element's look.
`checkGenerations`	Show the renders and their URLs. `waitSec` waits for them to finish.
`cancelGeneration`	Stop a render and refund it.

Pass an idempotencyKey on every render. If your client sends a call again, the same key returns the job that already started. It does not charge again.

Spending

Tool	Purpose
`estimateCost`	Show the balance and the price of the work. It starts nothing.
`approveSpend`	Open a credit budget, or approve one quoted render by its token.

Media and the library

Tool	Purpose
`importMedia`	Import a file from a URL, or upload a local file in 2 steps.
`searchLibrary`	Find media, saved elements, or the folders and tags.
`organizeMedia`	Create folders, move uploads, and add or remove tags.
`addFromLibrary`	Add saved elements, the starter cast or a world to a project.
`saveToLibrary`	Save a project's element to the team library.
`attachMediaToScene`	Set a scene's frame or clip from media or from another scene.

Timeline and export

Tool	Purpose
`editTimeline`	Assemble the clips, add music or other media, and mute lanes.
`exportFilm`	Render the final movie. With `aspectRatio`, export a cropped cut-down instead.

Worlds and templates

Tool	Purpose
`readWorlds`	List the worlds, or read one world in full.
`editWorld`	Create a world, change it, or add library entries to it.
`deleteWorld`	Delete a world, or remove one entry from it.
`readTemplates`	List the film templates, or read one template's inputs.
`saveProjectAsTemplate`	Save a finished project as a team template.
`produceFromTemplate`	Make one film from a template and render it within a budget.

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 past the current browser conversation.

readAgentActivity lets an external agent read the recorded work, including the calls that the in-app assistant made. It can use the errors and costs in that history to explain a failed job or to continue a project.

Resources

The server also publishes resources:

Resource	Contents
`sundream://projects`	Projects in the workspace.
`sundream://projects/{projectId}/board`	The project's board.
`sundream://projects/{projectId}/status`	Progress, blockers, and next actions.
`sundream://projects/{projectId}/assets`	The downloadable file manifest.
`sundream://projects/{projectId}/models`	Models and prices for the project.

Replace {projectId} with the film's ID. Clients that support resource completion can suggest it. Resources use the key's workspace permissions, and a resource read does not create an activity entry.

The free-form writing document and the in-app script controls are browser features. An external agent writes its own content and applies it with updateFilm and editScenes.

Tool guide

On this page