AI Agents
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). |
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. Returns a job id. |
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. |
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. |
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.