# MCP tool reference (/docs/agents/mcp-reference) 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](/docs/agents/connect-an-agent) to set this up. ## Tools [#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 [#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. The MCP tools forward to a local HTTP **Control API** you can call directly from any language. See the [Control API reference](/docs/agents/api-reference). ## Spend limits [#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.