MCP tool reference
The tools the SimpliGen MCP server exposes to AI agents, and the local Control API behind them.
SimpliGen ships an MCP server (@simpligen/mcp) that connects an AI agent to the
running SimpliGen app over a local, token-authenticated connection. The agent
calls MCP tools; the server forwards them to the app's local Control API. See
Connect an agent to set this up.
Tools
| Tool | What it does |
|---|---|
list_capabilities | List every preset the agent can generate with (image or video), its inputs and options, whether it is ready locally, and cloud eligibility and credit cost. |
get_status | Report engine state, whether cloud is connected, the credit balance, the active project, and the characters capability block (enabled flag, installed preset counts for base/edit/i2v, and enhancePresets, the number of installed upscale presets). |
start_engine | Start the local engine if it is not already running. Returns the engine state; when a cold boot outlasts the call, engineStarting is true and get_status reports when it is up. Does nothing if the engine already runs, and never installs a missing one (connector 0.3.0 or newer). |
stop_engine | Stop the local engine and free its VRAM. Cloud generation is unaffected (connector 0.3.0 or newer). |
restart_engine | Restart the local engine, after installing or removing a custom node, or when it is wedged (connector 0.3.0 or newer). |
list_projects | List projects (the containers that hold generations). |
create_project | Create a new project. |
upload_file | Upload a local image or video and get a handle to pass into generate. |
list_loras | List the installed user LoRAs (name, base model, trigger words) so you can pass them into generate. |
generate | Start an image or video generation. Choose local, cloud, or auto. Optionally pass loras: [{ name, weight }] (local backend, presets where inputs.supportsLoras is true; use list_loras for names) and a negativePrompt (extra terms, added after the preset's default negative; on cloud runs the preset default is used as is). options takes the named fields (steps, cfg, seed, resolution, aspectRatio, durationSeconds) and any Advanced Control the preset declares under list_capabilities → options.controls, such as unlock, shift or high_steps, as a top-level key (connector 0.2.0 or newer). Returns a job id. |
get_prompt_guide | Read the prompting guide for a preset (presetId) before writing its prompt: how the model reads a prompt, structure, length, camera and motion wording, negatives, character wording and examples. The reply carries family, generic (true when no model-specific guide exists) and the guide text. Connector 0.6.0 or newer; generate tells agents to call it first. |
get_job | Get a job's status and result, including the output path once it is finished. |
wait_for_result | Wait until a job finishes, fails, or times out. |
list_jobs | List recent generation jobs. |
cancel_job | Cancel a queued or running job. |
prepare_preset | Start downloading a local preset's models so it becomes ready to run. |
get_result_image | Return a finished job's image inline for viewing. Video results return a file path. |
list_recipe_blocks | List the building blocks for authoring a recipe: entry points (create image or video, edit image, upscale) and every preset usable as a step, each with its port contract (inputs it needs, what it produces, which entry points it fits). |
compose_recipe | Author a new recipe from a high-level spec (ordered steps pinned to presets, plus any inputs) and save it as a draft. SimpliGen auto-wires the ports, the step-to-step media chain, and a prompt input per step, then validates. Returns the recipe id plus validation. |
validate_recipe | Dry-run a recipe spec (or a raw config) without saving, and get precise errors to fix before composing. |
list_recipes | List the recipe drafts saved on this device. |
get_recipe | Get a saved recipe and its full config by id. |
publish_recipe | Submit a saved recipe to the Creator Marketplace (queued for human review). Needs a connected account; publishes free unless a one-time token price is set. |
run_recipe | Run an installed recipe (the ones in UGC Studio and Product Studio, or a draft) with its inputs filled. A subject input takes a character or product id, media inputs take upload handles, text and choice inputs take plain values. Same pipeline as clicking Generate in the studio. Returns a run id. |
get_recipe_run | Status of a recipe run: overall status, each step with its status and result, and the final result path once done. |
wait_for_recipe_run | Block until a recipe run finishes (or a timeout passes) and return the final run. |
list_recipe_runs | Recent runs of a recipe with their status and results. |
cancel_recipe_run | Stop a running recipe. No further steps start; a local in-flight step is interrupted. |
list_subjects | Every subject a recipe's subject input can take: characters and products, with their ids. |
list_products | The products saved on this device. |
create_product | Save a product from an uploaded photo (name, description, category) so Product Studio and UGC recipes can use it. Returns the product id. |
remove_product | Delete a product and its photo. |
list_characters | List all active characters in the Character Studio. |
get_character | Get the details and images for a single character by id. |
list_character_features | List all identity features (skin tone, hair, etc.) and their options, for use when creating a character by description. |
list_character_presets | List installed presets available for each character role: base portrait generation, identity editing, image-to-video animation, and enhancement (upscale). Each enhancement preset includes a supportedScales array. |
create_character | Create a new character. Supports three paths: describe (generate a base portrait from feature selections), upload (use your own image as the base), and vision-recreate (agent-described features from a user photo). In generate mode, the tool polls internally until the base portrait is ready and returns the ready character object. In upload mode, the character is ready immediately. |
generate_character_image | Generate a scene image for an existing character by prompt. Accepts an optional presetId to select which identity-edit preset to use for this call. Returns one or more job ids to poll via wait_for_result. |
generate_character_video | Generate an animated video clip for an existing character. Accepts optional framePresetId (identity-edit preset for the frame step) and videoPresetId (i2v preset for the animate step). Returns job ids for both the frame and the animation steps. |
generate_character_frame | Generate a single still frame for a character without animating it. Useful when you want to review or enhance the frame before animating. Accepts an optional presetId. Returns { jobIds: [...] }; use jobIds[0] as the frame job id. |
animate_character | Animate a character from a completed frame or any completed image job. Pass jobId (a job id from any completed generation) or a filePath (absolute local image path). Accepts an optional videoPresetId. Returns a video job id. |
set_character_preset | Set a sticky per-character default preset for image generation (imagePresetId) and/or video generation (videoPresetId). Pass null to clear a default. Subsequent calls to generate_character_image and generate_character_video use these defaults unless overridden per-call. |
enhance_character_media | Upscale or enhance a character image or video. Source can be a completed job (jobId), an uploaded file (filePath handle), or the character base portrait (target: 'base'). Accepts scale (upscale factor), keepResolution (upscale then resize back to source dimensions for a sharper same-size result), and applyAsBase (replace the character base portrait with the upscaled result). Returns a job id. |
regenerate_character_base | Re-generate the base portrait for an existing character in place, optionally switching to a different base preset or updating the identity. No new character is created. Polls internally, auto-accepts the new base, and returns the ready character object. The agent does not need to poll a job id afterward. |
remove_character | Permanently delete a character and its associated data. |
list_films | List the Video Studio films of a project (connector 0.5.0 or newer, as are all the film tools below). |
create_film | Create an empty film: shape, resolution, where it renders, presets per kind of shot. Answers its timeline. |
get_film | Read a film's timeline: tempo, cast, every clip with its number, start and length in seconds and bars, shots and take status, the tracks, markers and export range. |
update_film_settings | Change the film's shape, resolution, where it renders, presets, Subject & style, and the cast and location every clip inherits. |
add_track | Put an uploaded audio file on the timeline: singing, music, dialogue or effects. |
move_track | Move a track's audio, mute it, or set its volume. |
detect_tempo | Set the film's tempo and bar lines from its song. After this, times can be given in bars. |
add_clip | Add an empty clip at a moment, for a length. |
update_clip | Write a clip in one step: shots (prompt, length, spoken or sung line, who says it, framing), cast, location, how it starts (fresh or continue from the clip before; none and frame are also accepted, as fresh and continue), which tracks it hears, preset. |
move_clip | Move a clip to a new start or another video lane. |
trim_clip | Change a clip's length, or where it starts inside its take. |
remove_clip | Remove a clip. |
apply_film_plan | Lay out a whole draft in one step: clips on the bars with their shots, cast and links. Every problem comes back at once; nothing changes unless all of it is valid. |
set_fades | Fade a clip or a track in and out. |
add_marker | Put a named marker on the ruler. |
set_export_range | Export only part of the film, or all of it. |
render_clips | Render the clips that need it, or the ones named. Answers at once with what started, what is held, and the cloud cost. |
wait_for_renders | Wait until no clip is rendering and answer the timeline. |
list_takes | List a clip's takes. |
use_take | Make one of a clip's takes the one it shows. |
export_film | Stitch the film into one video with its music and answer the file path. |
list_locations | List the Library's locations. |
create_location | Save a location from an uploaded picture or a finished image job. |
With the film open in the Video Studio, every change an agent makes appears at once and undoes with Ctrl+Z. See An agent makes a music video for a full walk through.
How it connects
The agent runs the MCP server with npx -y @simpligen/mcp over stdio. The server
authenticates to the app with a pairing token (SIMPLIGEN_TOKEN) and finds the
app's local port automatically. The SimpliGen app must be running. Mint a token
under Settings, in the "Connect an agent" section.
Building a custom integration?
The MCP tools forward to a local HTTP Control API you can call directly from any language. See the Control API reference.
Spend limits
Each token can carry a spend cap. An empty cap means unlimited cloud use, 0
means local generation only, and a positive number caps cloud spend at that many
credits. Local generation is always allowed and never counts against the cap.