MCP Tool Reference

Complete reference for the 147 tools exposed by the Nodaro MCP server.

Scopes

Each tool requires one or more OAuth scopes. Grant the relevant scopes when authorizing the connector; missing scopes cause tools to be omitted entirely (they never appear in the tool list).

Scope Controls
workflows:read list_projects, get_project, list_workflows, get_workflow, get_workflow_json, export_workflow, list_components, get_component_inputs
workflows:write create_workflow, delete_workflow, update_workflow_json, import_workflow
workflows:execute run_workflow, all generation verbs (image/video/audio/Suno/character/location/object), run_component, run_app, delete_app_run, analyze_prompt, generate_prompt, enhance_prompt, reduce, forced_alignment, video_analysis, resolve_shot_sequence, render_shot_sequence, create_explainer, create_launch_video
jobs:read list_jobs, get_job, diagnose_run
assets:read browse_gallery, browse_uploads, list_favorites, get_asset, display_asset, get_app_run, list_characters, get_character, list_locations, get_location
assets:write favorite_asset, create_character, update_character, approve_portrait, recaption_character, create_location, update_location, approve_main_image, recaption_location, approve_object_main_image, recaption_object, upload_image_widget, upload_audio_widget, upload_video_widget, request_image_upload, request_audio_upload, request_video_upload, prepare_image_upload, prepare_audio_upload, prepare_video_upload
credits:read check_balance, credit_transactions
apps:read list_apps, get_app_inputs
pipelines:read get_pipeline_stage_chat, get_pipeline_status, pipeline_pending_approvals
pipelines:execute branch_pipeline, start_pipeline
pipelines:approve chat_pipeline_stage, apply_chat_proposal
presets:read list_node_presets, get_node_preset

Ungated (always visible): ping, list_models, start_film_director, start_video_director, start_workflow_editor, get_node_skill, get_picker_catalog, list_shot_shapes, get_shot_shape, list_brand_presets, get_recipe

Job cards

Generation tools render an inline tool card in MCP-Apps hosts (claude.ai): live progress, then the finished result. Media tools (generate_image, generate_video, generate_music, …) have media-specific cards. All remaining job tools — entity motion clips (generate_*_motion), render_shot_sequence, create_explainer, create_launch_video, run_component, and the text-output tools (image_to_text, generate_script, transcribe, suno_lyrics, suno_style_boost, forced_alignment, video_analysis) — share the universal job card, which auto-detects the output: video/image/audio players, inline text with a Copy button (scripts, lyrics, transcripts, alignment JSON), or a component’s stacked outputs.

Result-text contract: job tools respond with "<label> started (id <jobId>)" plus card-first guidance. Clients without card support poll get_job with the job id (run_app returns an execution id — poll get_app_run instead). The result is always also saved to your Nodaro library.

The “mcp” project

All workflow tools that create or modify workflows operate inside a single project named “mcp”. This project is created automatically on first use — agents do not need to set it up.

Scope of the boundary:

Tool Scope
list_projects, get_project Sees all of your projects (read-only discovery)
list_workflows, get_workflow, get_workflow_json Only sees workflows in the mcp project
create_workflow, delete_workflow, update_workflow_json, import_workflow Only touches the mcp project
export_workflow Can read any of your workflows (use it to pull work from a personal project into the mcp project via export → import)
run_workflow Only runs workflows in the mcp project

This isolation keeps agent-managed workflows out of your personal projects.

Project tools

list_projects

Returns all projects in your account, ordered by name.

Scope: workflows:read
Input: none

Response shape:

{
  "data": [
    {
      "id": "uuid",
      "name": "mcp",
      "description": "Workflows managed via MCP",
      "workflowCount": 3,
      "createdAt": "2026-01-15T10:00:00.000Z"
    }
  ]
}

get_project

Returns a single project by UUID or by name (case-sensitive exact match).

Scope: workflows:read

Input:

Field Type Notes
project_id string A project UUID or a project name

Example: { "project_id": "My Feature Film" } resolves by name.
Example: { "project_id": "550e8400-e29b-41d4-a716-446655440000" } resolves by UUID.

Response shape:

{
  "data": {
    "id": "uuid",
    "name": "My Feature Film",
    "description": null,
    "workflowCount": 12,
    "createdAt": "2026-03-01T09:00:00.000Z"
  }
}

Workflow tools

list_workflows

Lists workflows in the mcp project, newest first.

Scope: workflows:read

Input:

Field Type Notes
limit integer (1–100) Default 20
cursor string ISO created_at from a prior response’s next_cursor; use for pagination
include_sub_workflows boolean Default false. When false, hides workflows with parent_workflow_id (child sub-workflows owned by another container). Pass true to surface them.

By default, list_workflows returns only top-level workflows — child sub-workflows (those owned by a parent container via parent_workflow_id) are hidden so the list reflects what you would see in the editor’s project view. Set include_sub_workflows: true if you need to enumerate every workflow in the mcp project regardless of nesting.

Response shape:

{
  "data": [
    {
      "id": "uuid",
      "project_id": "uuid",
      "name": "My Workflow",
      "description": null,
      "version": 1,
      "thumbnail_url": null,
      "created_at": "2026-05-01T12:00:00.000Z",
      "updated_at": "2026-05-01T12:00:00.000Z"
    }
  ],
  "next_cursor": "2026-04-30T08:00:00.000Z"
}

Pass next_cursor as cursor in the next call to get the next page. When next_cursor is null, you’ve reached the last page.

get_workflow

Returns metadata for a single workflow in the mcp project.

Scope: workflows:read

Input:

Field Type Notes
workflow_id UUID string Must be in the mcp project

create_workflow

Creates a new workflow in the mcp project. You can seed it with an initial node graph or leave it empty.

Scope: workflows:write

Input:

Field Type Notes
name string (1–200) Required
description string (max 2000) Optional
nodes array of objects Optional; React Flow node objects
edges array of objects Optional; React Flow edge objects
settings object Optional; workflow-level settings

Response: Returns the new workflow’s id and name in structured content.

delete_workflow

Deletes a workflow from the mcp project. This is permanent.

Scope: workflows:write

Input:

Field Type Notes
workflow_id UUID string Must be in the mcp project

Returns an error if the workflow doesn’t exist in the mcp project.

get_workflow_json

Returns the full React Flow graph for a workflow in the mcp project: nodes, edges, settings, name, and updated_at.

Scope: workflows:read

Input:

Field Type Notes
workflow_id UUID string Must be in the mcp project

Response shape:

{
  "name": "My Workflow",
  "nodes": [ ... ],
  "edges": [ ... ],
  "settings": {},
  "updated_at": "2026-05-10T15:30:00.000Z"
}

Save updated_at and pass it as expected_updated_at to update_workflow_json to enable optimistic concurrency control.

update_workflow_json

Updates a workflow in the mcp project: its node graph (nodes + edges), its settings, and/or its thumbnail_url. All content fields are optional — pass only thumbnail_url, for example, to set the preview image without re-sending the graph.

Scope: workflows:write

Input:

Field Type Notes
workflow_id UUID string Must be in the mcp project
nodes array of objects Optional; replaces the current nodes. Must be sent together with edges.
edges array of objects Optional; replaces the current edges. Must be sent together with nodes.
settings object Optional; if provided, replaces current settings
thumbnail_url string (URL) or null Optional; sets the workflow’s thumbnail image, or null to clear it. Must be an already-hosted image URL.
expected_updated_at string (ISO 8601) Optional; enables optimistic concurrency
expected_version integer Optional; integer CAS from get_workflow_json (preferred over expected_updated_at)

Optimistic concurrency: Pass the updated_at value from a prior get_workflow_json call as expected_updated_at. If the workflow has been modified since you read it, the call returns a conflict error:

“Workflow was modified since you last read it. Fetch the latest JSON with get_workflow_json and retry.”

This prevents accidental overwrites when two agents or sessions edit the same workflow concurrently. Omit expected_updated_at to skip the check and overwrite unconditionally.

export_workflow

Exports a workflow as a portable JSON bundle. Unlike other workflow tools, export_workflow is not restricted to the mcp project — it can read any of your workflows. Use it to pull an existing personal workflow into the mcp project via export → import.

Scope: workflows:read

Input:

Field Type Notes
workflow_id UUID string Any of your workflows
with_assets boolean Default false. When true, bundles character, object, and location entity data alongside the node graph

Two export modes:

Response: A JSON string in the WorkflowExport format (version 1). Pass the full string directly to import_workflow.

import_workflow

Imports a workflow from a JSON bundle produced by export_workflow. Always imports into the mcp project. If the bundle includes asset data (with_assets: true), new character, object, and location records are created under your account with fresh IDs; node references are remapped automatically.

Scope: workflows:write

Input:

Field Type Notes
workflow_json string The full JSON string from export_workflow

Response: Returns the new workflow’s id and name in structured content.

run_workflow

Runs a saved workflow from the mcp project. Returns an execution_id and registers an async task for progress tracking.

Scope: workflows:execute

Input:

Field Type Notes
workflow_id UUID string Must be in the mcp project
inputs object Optional; per-node input overrides keyed by node id

Response: { executionId: "...", name: "..." } — use executionId with the jobs/executions tools or the SDK to poll for completion. MCP clients that support the tasks/* API and widget rendering will show live progress inline.

Prompt tools

AI assistance for writing prompts for generation nodes. All three delegate to POST /v1/prompt-helper/wizard (the same endpoint as the SDK client.promptHelper and the CLI nodaro prompt commands) and reserve credits per call.

Scope (all three): workflows:execute

analyze_prompt

Turns a rough idea into guided questions with options for a target node type (e.g. generate-image, image-to-video, generate-music). Pair with generate_prompt.

Input:

Field Type Notes
nodeType string Required. Target node type.
prompt string (max 5000) Optional. The rough idea. Omit to build from scratch.
provider / style / aspectRatio / duration / llmModel — Optional.

Response: { jobId, questions } — each question is { category, label, options[], selected, allowCustom, multi? }.

generate_prompt

Builds a single optimized prompt from analyze_prompt selections.

Input:

Field Type Notes
nodeType string Required.
selections array Required. One { category, value, isCustom } per answered question.
originalPrompt string (max 5000) Optional. Woven into the result.
provider / style / aspectRatio / duration / llmModel — Optional.

Response: { jobId, prompt, recommendedModel? }.

enhance_prompt

One-shot “improve this prompt” — rewrites a rough idea into one optimized prompt with no questions round-trip.

Input:

Field Type Notes
nodeType string Required.
prompt string (max 5000) Optional. The rough idea to improve.
provider / style / aspectRatio / duration / llmModel — Optional.

Response: { jobId, prompt, recommendedModel? }.

Image generation tools

Scope (all): workflows:execute

Tool Description
generate_image Text-to-image generation. Accepts prompt, model, aspect_ratio, resolution, quality, negative_prompt, reference_image_urls (up to 14 URLs or asset ids for identity/style/composition guidance — the response text confirms how many were attached), and optional structured fields. Advanced callers can also pass connected_references (the editor’s structured wired-reference shape) + reference_order — labeled/ordered references the route assembles into @image_N directives and {image:N} token resolution. Also accepts presetId (from list_node_presets) to apply a built-in or saved preset’s config server-side; any explicit field above overrides the preset, and prompt may be omitted when the preset supplies one.
modify_image Image-to-image transformation — apply a style, change colors, swap backgrounds. Accepts image_url, prompt, and strength controls.
image_to_image Structural image-to-image (i2i) using a dedicated i2i model. Distinct from modify_image in that it uses models optimized for structural transfer. Supports multi-reference composition via reference_image_urls (up to 13).
edit_image Targeted edits: remove background, upscale, inpaint, or use Nodaro’s nano-banana-edit model.
generate_mask Generate or refine a segmentation mask for inpainting workflows.
image_collage Composite 2–30 images into one 2K/4K image with a smart (justified) or grid layout — no image is ever cropped (smart floats the output height; grid letterboxes). Accepts images[] (url or asset_id), layout, resolution (default 4K), aspect_ratio (any W:H, default 4:3), gap, background_color.
image_to_text Extract a text description (caption/transcription) from an image using a vision model.
generate_script Generate a short video script from a prompt (LLM-backed; outputs scene-by-scene copy).
save_image_defaults Persist preferred model, aspect_ratio, and quality values so they become the defaults for subsequent generate_image calls in the same session.

Video generation tools

Scope (all): workflows:execute

Tool Description
generate_video Text-to-video generation. Accepts prompt, model, duration, aspect_ratio, resolution, sound, negative_prompt, seed, and optional structured fields. Advanced callers can also pass connected_references + reference_order (structured wired-reference shape) for labeled/ordered references on reference-capable models (Seedance 2, Gemini Omni, VEO 3.x, Kling 3 Omni, Grok i2v, HappyHorse Ref2V). Also accepts presetId (from list_node_presets { nodeType: "generate-video" }) to apply a built-in or saved preset’s config server-side; any explicit field above overrides the preset, and prompt may be omitted when the preset supplies one. To animate from a still or use start/end frames, use animate_image.
animate_image Image-to-video animation — bring a still image to life. Accepts image_url / image_asset_id, optional prompt, model, duration, aspect_ratio, sound, and end_frame_url (start/end-frame animation). Advanced callers can also pass connected_references + reference_order for labeled/ordered identity references.
extend_video Extend an existing video clip forward in time. Accepts video_url, prompt, model, duration.
loop_video Create a seamless looping clip from a short video segment. Accepts video_url and optional loop-trim parameters.
modify_video Video-to-video transformation — apply a style or prompt transformation to an existing clip.
relight_video Relight & switch/composite a clip from its own pixels (Beeble SwitchX). Accepts video_url/video_asset_id + prompt and/or reference_image_url, alpha_mode (auto/fill/select/custom), mask_url, alpha_keyframe_index, max_resolution (720/1080), seed.
trim_video Trim a video to a start/end timestamp. Accepts video_url, start, end.
combine_videos Concatenate multiple video clips with optional transitions. Accepts video_urls[], transition, transition_duration.
assemble_narrated_video Fit N ordered (clip, voice) blocks into one narrated MP4 — a shorter voice is centered over its clip with silence padding, a longer voice slows the clip to fit (capped, holding the last frame beyond the cap); audio is never cropped. Accepts blocks[] (1–60, each video_url/video_asset_id + optional audio_url/audio_asset_id), voice_volume (default 100), clip_audio_volume (default 40), max_slowdown (default 1.5), trim_start_frames, trim_end_frames.
merge_video_audio Merge a video track and an audio track into a single output file.
add_captions Burn subtitles/captions onto a video. Accepts video_url and caption style options.
extract_frame Extract a single frame from a video at a given timestamp. Returns an image URL.
lip_sync Drive lip-sync on a video or portrait image from an audio track. Accepts video_url / image_url + audio_url, plus model (kling-avatar, kling-avatar-pro, infinitalk, omnihuman-1-5, seedance-2(-fast), latentsync, wav2lip, video-retalking, sadtalker), prompt, resolution, and (omnihuman-1-5) seed / fast_mode.
speech_to_video Generate a talking-head video from a portrait + speech audio.
motion_transfer Transfer the motion pattern from one video onto a target image or video.
face_swap Swap a face in a source image/video with a reference face.
video_upscale AI upscale a video to a higher resolution (powered by Topaz via KIE).
video_analysis Scene-by-scene analysis of a video for AI re-creation — ≤8s scenes with prompt-ready visualResolved descriptions, mode-tagged audio, and castable entity slots. Exactly one source: video_asset_id / video_url / youtube_url (max 10 minutes, no live streams). See video_analysis below.

Seedance 2 (model: "seedance-2") accepts resolution: "4k" and aspect_ratio: "adaptive" (plus "21:9") on generate_video / animate_image — both fields are free strings, forwarded to the route unaltered. The cheaper variants are resolution-capped: seedance-2-fast and seedance-2-mini are 480p / 720p only (no 1080p, no 4K). Frame inputs and references coexist — when any reference (image / video / audio) is wired alongside image_url / end_frame_url, the frames become prompt-directed Image N references rather than pinned endpoints; the resolver decides the mode, so there is no toggle. Reference videos are billed unit × (input + output) duration — the per-second -ref rate (see the Generate Video node pricing) is scaled by the probed input-video duration plus the output duration, so longer source clips reserve more.

video_analysis

Scope: workflows:execute

Analyze a video into a scene-by-scene breakdown built for AI re-creation. Scenes are cut at natural boundaries, each at most 8 seconds (one image/video generation per scene). Every scene carries visualResolved — a self-contained, prompt-ready visual description and the field downstream consumers read — plus shot type, camera movement, a mode-tagged audio track (speech quoted verbatim; music/sfx as generation-ready descriptions; silence), and recurring people/objects/places extracted as castable entity slots so they can be re-cast with your own characters. Returns a job_id — poll get_job; the full analysis JSON (meta + slots + scenes[]) is in the job’s output_data.

Input:

Field Type Description
video_asset_id uuid, optional Nodaro video job id or uploaded-asset id.
video_url string, optional Direct URL of a video file.
youtube_url string, optional YouTube video URL (youtube.com / youtu.be).
llm_model enum, optional Analysis model: gemini-3-flash (default) or gemini-3.1-pro.
analysis_focus string ≤2000, optional Steer the analysis (e.g. “focus on the product shots and on-screen text”).

Pass exactly one of video_asset_id / video_url / youtube_url — passing zero or more than one returns a tool error naming what was provided. Maximum duration is 10 minutes (600s) for any source; YouTube live streams are rejected.

Pricing — duration-bucketed credits per model. The bucket is the smallest of 60s / 180s / 360s / 600s that fits the video’s probed duration. The values below are the shared pricing formula’s current outputs:

Model ≤60s ≤180s ≤360s ≤600s
gemini-3-flash (default) 1 1 2 3
gemini-3.1-pro 2 3 7 11

Audio generation tools

Scope (all): workflows:execute

Tool Description
generate_music Text-to-music generation (Suno v4/v5 via KIE). Accepts prompt, genre, mood, duration, model. Also accepts presetId (from list_node_presets { nodeType: "generate-music" }) to apply a built-in or saved preset’s config server-side; any explicit field above overrides the preset, and prompt may be omitted when the preset supplies one.
generate_speech Text-to-speech. Accepts text, voice_id, model. Supports ElevenLabs v3 (default) and KIE v2 models. Also accepts presetId (from list_node_presets { nodeType: "text-to-speech" }) to apply a built-in delivery preset (speed/stability/style) server-side; explicit fields override it, and text is always required (presets tune delivery, not content).
text_to_audio Text-to-sound-effect (ElevenLabs SFX). Accepts prompt and optional duration. Also accepts presetId (from list_node_presets { nodeType: "text-to-audio" }) to apply a built-in or saved preset’s config server-side; any explicit field overrides the preset, and prompt may be omitted when the preset supplies one.
voice_clone Instant voice clone from a reference audio clip (ElevenLabs). Returns a voice_id for use with generate_speech.
voice_design Design a new synthetic voice from text descriptors (ElevenLabs /v1/text-to-voice/design). Accepts text, voice_description, model (default eleven_ttv_v3; eleven_multilingual_ttv_v2 is the legacy model), loudness, guidance_scale, seed, quality, should_enhance. Returns a voice_id.
voice_changer Transform the speaker identity in an audio clip to a target voice.
voice_changer_pro Detect each speaker in a multi-speaker clip and recast each to a chosen voice, preserving words and timing (Cloud only). A null entry in ordered_voices is a keep-slot — that speaker keeps their original voice while later speakers are still recast.
voice_remix Re-stylize or re-arrange an existing audio clip.
dubbing Dub a video or audio clip into a target language with voice preservation.
transcribe Speech-to-text transcription. Returns a transcript + optional timestamps.
audio_isolation Isolate and clean the primary voice from a mixed clip (removes background music/noise). Returns one clean voice track.
separate_audio Separate ANY audio into vocals + instrumental, or full stems (drums/bass/other/guitar/piano), via Demucs. Works on non-Suno audio.
apply_audio_fx Apply a creative audio effect — scenario reverbs (room/hall/church/cave/arena/outdoor…) to place a voice in a space, plus telephone/megaphone/echo/custom (delay+EQ).
trim_audio Trim an audio file to a start/end timestamp.
download_youtube_audio Download the audio track from a YouTube URL. Returns an audio asset URL.

Suno music tools

All Suno tools require workflows:execute.

Tool Description
suno_generate Generate a new song from a prompt or lyrics using Suno v4/v5.
suno_lyrics Generate song lyrics from a prompt.
suno_extend Extend an existing Suno song clip.
suno_cover Generate a cover version of a song.
suno_upload_extend Upload an audio clip and extend it with Suno.
suno_music_video Generate a music video from a Suno song clip.
suno_mashup Blend two audio clips into a mashup.
suno_replace_section Replace a section of a Suno song with new generated audio.
suno_style_boost Apply a style transfer / boost to a Suno song.
suno_add_instrumental Add an instrumental track to a Suno song.
suno_add_vocals Add a vocal layer to an instrumental track.
suno_separate_stems Separate a song into vocal + instrumental stems.
suno_convert_wav Convert a Suno output to WAV format.

Character tools

Character tools surface the caller’s saved characters from Character Studio so an LLM client can pick the right asset URL to pass as a reference image into a subsequent generation call.

list_characters

Scope: assets:read

Lists the caller’s characters with summary fields, ordered by most recently updated.

Input: { limit?: integer } — default 50, max 100.

get_character

Scope: assets:read

Returns full asset detail for one character including every expression / pose / motion / angle / lighting variant with its URL.

Input: { id: uuid }

create_character

Scope: assets:write

Creates a new character row with identity fields. No portrait — call generate_character (kind="main") afterwards.

Input: name, description, gender, style (realistic/anime/3d-pixar/illustration), base_outfit, seed_prompt, identity_lock (off/soft/strict — face-preservation strength for Studio assets, default strict)

update_character

Scope: assets:write

Patches an existing character. Only the fields you supply are written. Supports optimistic concurrency via expected_updated_at.

approve_portrait

Scope: assets:write

Approves a completed generate_character job as the character’s canonical portrait. Fires an LLM caption inline to populate canonical_description.

Input: { character_id: uuid, candidate_job_id: uuid }

recaption_character

Scope: assets:write

Re-runs the LLM caption against the character’s current portrait and persists the new canonical_description.

Input: { id: uuid }

generate_character

Scope: workflows:execute

Generates either a fresh portrait (kind: "main") or an asset variant (kind: "asset") for a named character. The single tool covers two routes: POST /v1/generate-character (main portrait) and POST /v1/generate-character-asset (variants — expressions, poses, head angles, body angles, lighting, custom).

Input (main): kind, name, description, gender, style, base_outfit, model

Input (asset): kind, name, asset_type, variant, attach_to_character_id, attach_to_column, attach_name, source_image_url

generate_character_motion

Scope: workflows:execute

Animates a character into a motion clip via image-to-video. When attach_to_character_id is set, the source frame is auto-resolved from the character row and the resulting clip is appended to the motions[] bucket.

Input: motion_prompt, name, attach_to_character_id, source_image_url, description, motion_description, provider

Location tools

Eight tools for the location lifecycle — identity edits, establishing-shot generation, atmospheric motion clips, and LLM-captioned approval. Mirrored on the SDK at client.locations.

list_locations

Scope: assets:read

Summary list (name, main image URL, asset counts, identity copy).

Input: { archived?: boolean }

get_location

Scope: assets:read

Full detail including all asset arrays + reference photos + pendingJobs.

Input: { id: uuid }

create_location

Scope: assets:write

Create a new row with name + optional description / category / style.

Input: name, description, category, style

update_location

Scope: assets:write

Update identity fields (name, description, category, style, styleLock, canonicalDescription). Supports optimistic concurrency via expected_updated_at.

approve_main_image

Scope: assets:write

Approve a completed generate_location candidate as the location’s main image. Fires the LLM caption inline.

Input: { location_id: uuid, candidate_job_id: uuid }

recaption_location

Scope: assets:write

Re-run the LLM caption against the current main image.

Input: { id: uuid }

generate_location

Scope: workflows:execute

Generate a main image (kind: "main") or a variant asset (kind: "asset" + asset_type + variant).

generate_location_motion

Scope: workflows:execute

Animate the location’s establishing shot into an atmospheric motion clip (image-to-video). Pass refine_from_video_url to route through video-to-video for iterating on an existing clip.

Object tools

Four tools for the object (prop / product / vehicle / etc.) lifecycle — main-image approval, LLM recaption, motion clips, and verb-style generation. Mirrored on the SDK at client.objects.

generate_object

Scope: workflows:execute

Generate a main image or variant asset for an object. Parallel to generate_character / generate_location.

approve_object_main_image

Scope: assets:write

Approve a completed generate_object candidate as the object’s main image. Fires the LLM caption inline.

Input: { object_id: uuid, candidate_job_id: uuid } + optional expected_updated_at

recaption_object

Scope: assets:write

Re-run the LLM caption against the current main image.

Input: { id: uuid }

generate_object_motion

Scope: workflows:execute

Animate the object’s main image into a motion clip (image-to-video). Provider defaults to "kling-turbo", aspect ratio defaults to "1:1". Pass refine_from_video_url to use video-to-video refinement.

Input: motion_prompt, source_image_url (required), name, attach_to_object_id, provider, aspect_ratio, refine_from_video_url

Creature tools

Four tools for the creature / animal lifecycle — main-image approval, LLM recaption, motion clips, and verb-style generation. Mirrors the Object tools with the Animal/Creature delta (free-text species / category / style).

generate_creature

Scope: workflows:execute

Generate a creature/animal main image (kind: "main") or a variant asset (kind: "asset" + asset_type + variant). Parallel to generate_object; species (free text, e.g. "dragon", "wolf") is the creature delta vs objects.

Input (main): kind, name, description, species, category, style, source_image_url, model

Input (asset): kind, name, asset_type (angles/poses/variations/custom), variant, species, category, style, source_image_url, model

approve_creature_main_image

Scope: assets:write

Approve a completed generate_creature candidate as the creature’s main image. Fires the LLM caption inline.

Input: { creature_id: uuid, candidate_job_id: uuid } + optional expected_updated_at

recaption_creature

Scope: assets:write

Re-run the LLM caption against the current main image.

Input: { creature_id: uuid }

generate_creature_motion

Scope: workflows:execute

Animate the creature’s main image into an ambient motion clip (image-to-video). Provider defaults to "kling-turbo", aspect ratio defaults to "1:1". Pass refine_from_video_url to use video-to-video refinement.

Input: motion_prompt, source_image_url (required), name, canonical_description, category, style, attach_to_creature_id, attach_name, provider, aspect_ratio, refine_from_video_url

Scope: assets:read

Browse your gallery or the public gallery. Renders an interactive grid widget in compatible clients.

Input: scope ("mine" default / "public"), limit, cursor, kinds[], query

browse_uploads

Scope: assets:read

Browse assets you’ve uploaded (source files — distinct from generated outputs). Use to retrieve existing upload URLs to feed into generation tools.

Input: kind, limit, cursor

list_favorites

Scope: assets:read

List your favorited gallery items, most recent first.

Input: limit, cursor

get_asset

Scope: assets:read

Fetch metadata for a single asset (job) by id, including output URL, prompt, provider. Visible for your own jobs (any status) and any user’s public completed jobs. For a failed job it returns the failure reason plus a retryable flag — retryable: false (e.g. a content-policy block) means the same request will fail again, so change the input rather than re-running.

Input: { job_id: string }

display_asset

Scope: assets:read

Render an asset visually in chat (the user sees the media, not JSON). Renders image, video, and audio assets inline via the universal job-auto widget; image assets also surface Animate / Edit / Recreate follow-up buttons and click-to-zoom fullscreen. For purely-programmatic metadata (no rendering) prefer get_asset.

Input: { job_id: string }

get_app_run

Scope: assets:read

Fetch status of a workflow / published-app execution by id. Returns per-node states and output URLs produced so far. Used by widgets to poll progress.

Input: { execution_id: string }

favorite_asset

Scope: assets:write

Mark or unmark a gallery asset as a favorite.

Input: { job_id: string, favorited: boolean }

Jobs tools

list_jobs

Scope: jobs:read

List your recent jobs with status, job type, and output URL. Supports cursor pagination.

Input: limit, cursor, status, job_type

get_job

Scope: jobs:read

Fetch full metadata for a single job by id, including output_url, status, progress, provider, and output_data.

Input: { job_id: uuid }

diagnose_run

Scope: jobs:read

Diagnose why a workflow run or single job failed. Pass a workflow execution id or a job id; the tool tries the execution first and falls back to the job. For an execution it walks node_states, surfacing each failed node with its error message, provider, and the credits actually charged. Each failure gets a best-effort class — content_policy, validation, rate_limited, timeout, post_processing, provider_error, or unknown — and a remediation hint. Classes are heuristic (derived from the stored error string, not the error type), so treat them as guidance. Reserved credits are auto-refunded except for post_processing (post-delivery) failures; check creditsActual per node.

Input: { id: string } (a workflow execution id or a job id)

Apps tools

list_apps

Scope: apps:read

List published apps. Supports scope: "public" | "mine" and ordering by recency.

Input: scope, limit, cursor

get_app_inputs

Scope: apps:read

Returns the typed input schema for a published app (the same schema the published-app page renders). Use this before run_app to learn the available input keys and their types.

Input: { slug: string }

run_app

Scope: workflows:execute

Run a published app by slug. inputs is a FLAT object keyed by the schema input keys (from get_app_inputs). Returns an execution_id.

Input: slug, inputs?

delete_app_run

Scope: workflows:execute

Soft-delete (archive) a published-app run. The run can be restored or permanently deleted from the Nodaro web UI at /archived-runs.

Input: { slug: string, runId: uuid }

Component tools

list_components

Scope: workflows:read

List your saved workflow components (reusable sub-graphs). Ordered by most recently updated.

Input: limit, cursor

get_component_inputs

Scope: workflows:read

Returns the typed input schema for a saved component. Use before run_component to learn available input keys.

Input: { component_id: uuid }

run_component

Scope: workflows:execute

Execute a saved component by id. inputs is a FLAT object keyed by the component’s input schema keys. Returns an execution_id.

Input: component_id, inputs?

Models and credits tools

list_models

Scope: none (always visible)

Browse AI models available on this Nodaro instance. Returns grouped JSON with per-model capability sheets (aspect ratios, resolutions, qualities, durations, features, per-variant credit pricing) and a recommendations array. Models with model-family prompting guidance (e.g. Seedance 2.0) also carry a promptTips array — short prompting rules worth applying before calling generate_video / animate_image.

Input: kind (image/video/audio), mode, family, featuredOnly

check_balance

Scope: credits:read (cloud edition only)

Returns your current credit balance split by pool (subscription_credits vs topup_credits).

Input: none

credit_transactions

Scope: credits:read (cloud edition only)

Lists recent credit transactions (deductions and top-ups) with amounts, model identifiers, and timestamps.

Input: limit, cursor

list_node_presets

Scope: presets:read

List saved node presets — reusable named node configurations. Returns names, ids, and descriptions for discovery; fetch the full config data via the REST API / SDK (GET /v1/node-presets, GET /v1/node-presets/factory).

Input:

Field Type Notes
nodeType string Filter to one node type, e.g. "generate-image". Required when source includes factory.
source enum custom / factory / all Which presets to return. Default custom (your own saved presets).

get_node_preset

Scope: presets:read

Fetch ONE preset’s full saved configuration by id — the provider/model, prompt, aspect ratio, resolution, quality, and negative prompt it ships. Use it to apply a preset faithfully: get the id from list_node_presets, then either read these fields and pass them to the matching generate_* tool, or pass presetId directly to generate_image. Works for built-in (factory) and your own custom presets. Returns isError when the id resolves to neither.

Input:

Field Type Notes
nodeType string Required. Node type, e.g. "generate-image".
presetId string Required. Preset id from list_node_presets (factory slug like generate-image/location-board, or a custom uuid).

Upload tools

All upload tools require assets:write. Three upload strategies are provided — prefer the one suited to your client environment.

Widget uploads (preferred for Claude.ai web)

Tool Description
upload_image_widget Opens an in-chat file picker for images. Supports max_files (1–10). Auto-announces the resulting URL(s) back to the chat.
upload_audio_widget Opens an in-chat file picker for audio.
upload_video_widget Opens an in-chat file picker for video.

Browser-handoff uploads (works everywhere)

Tool Description
request_image_upload Returns an upload_page_url the user opens in their browser to drop the file, plus the deterministic public_url. Works in all MCP clients including Claude.ai web/Android.
request_audio_upload Browser-handoff for audio.
request_video_upload Browser-handoff for video.

Presigned-URL uploads (CLI clients with unrestricted bash)

Tool Description
prepare_image_upload Returns a presigned R2 PUT URL. Stream the file via curl -X PUT --data-binary @file -H 'Content-Type: <mime>'. Use in Cursor / Cline / Claude Desktop / Claude Code only — fails on Claude.ai web/Android.
prepare_audio_upload Presigned upload for audio.
prepare_video_upload Presigned upload for video.

Pipeline tools

Pipeline tools appear only when your authorization grants the relevant pipelines:read / pipelines:execute / pipelines:approve scopes (the enterprise Story-to-Video pipeline engine; Cloud/Business).

Tool Scope Description
branch_pipeline pipelines:execute Create a branch of an existing pipeline from a given stage.
start_pipeline pipelines:execute Start a new Story→Video pipeline from a prompt. Mode "auto" runs end-to-end unattended; "manual"/"guided" pause at approval gates.
chat_pipeline_stage pipelines:approve Send a chat message to the Showrunner Refinement Director for a stage awaiting approval (guided mode). Returns the assistant reply and an optional proposed_change JSON Patch.
apply_chat_proposal pipelines:approve Accept a proposed edit from a prior chat_pipeline_stage reply and advance the stage to approved.
get_pipeline_stage_chat pipelines:read List all chat turns for a pipeline stage ordered by turn number.
get_pipeline_status pipelines:read Get current pipeline state: status, current_stage, credit counters, mode, failure_reason. Poll after start_pipeline to track an Auto run.
pipeline_pending_approvals pipelines:read List stages currently awaiting approval with their output snapshots.

Shot-sequence tools

Tools for authoring narrated, time-coded motion-graphics videos (HyperFrames methodology on the Remotion engine). The execution tools (forced_alignment, resolve_shot_sequence, render_shot_sequence) require workflows:execute. The catalog discovery tools (list_shot_shapes, get_shot_shape) are ungated.

list_shot_shapes

Scope: none — always visible (all editions, free).

Return the catalog of all registered shot-sequence blueprints (id, roles, description, defaultDurationFrames). Blueprints are text/shape only and carry no pricing or credit information. Use before authoring a ShotSequenceBrief to pick the right blueprint for each beat role. Zero credits.

Input: none

get_shot_shape

Scope: none — always visible (all editions, free).

Return detailed information for one blueprint: its metadata (roles, description, defaultDurationFrames), a JSON-schema descriptor of the params it accepts, and a filled worked example. Unknown id returns an error with the list of known ids. Zero credits.

Input: id (string) — blueprint id, e.g. "titlecard-reveal". Call list_shot_shapes to browse all ids.

list_brand_presets

Scope: none — always visible (all editions, free).

Return the catalog of all 8 brand-token presets (id, label, mood, description, palette summary, fonts). A brand preset is a named palette+font pairing (e.g. midnight-violet, editorial-cream) passed as the brand param to the video director so every blueprint accent and text style stays consistent across the video. Use before authoring a brief that specifies a brand to pick the right preset id. Zero credits.

Beyond the font family, a preset’s fonts.headingType / fonts.bodyType can each carry a weight (100–900), a casing ("uppercase" / "lowercase" / "none"), and a tracking (letter-spacing, in em, -0.2 to 0.5) — independent levers for headings vs. body text. Precedence: an explicit value on the element itself wins, otherwise the brand’s headingType/bodyType applies, otherwise the blueprint’s own hardcoded default. Two edge cases to know before authoring: letter-spacing is never applied to Arabic text (it breaks cursive letter joining — Hebrew is unaffected since it doesn’t join), and a weight only renders if that weight is actually loaded for the chosen font family — requesting an unloaded weight silently snaps to the nearest one that is loaded. See Brand Typography Ramp for the full model.

Input: none

forced_alignment

Scope: workflows:execute

Align a known transcript to an audio clip (ElevenLabs forced alignment), returning per-word start/end timings. Returns a job_id; the alignment array is in output_data.alignment. Use the result to drive element reveals in resolve_shot_sequence.

Input: audio_url or audio_asset_id, transcript

resolve_shot_sequence

Scope: workflows:execute

Bake an authored shot-sequence brief together with forced_alignment word timings into a render-ready plan. Pure and synchronous — returns the plan inline (no job). Feed the plan directly to render_shot_sequence.

Input: brief (a ShotSequenceBrief), audio_url, alignment (from forced_alignment)

render_shot_sequence

Scope: workflows:execute

Render a resolved shot-sequence plan to an MP4 on Nodaro’s Remotion engine. Returns a job_id; in hosts with interactive tool cards (claude.ai), progress and the finished video render inline in the tool card. The video is also saved to your Nodaro library.

Input: plan (a resolved ShotSequencePlan from resolve_shot_sequence)

Video Director tools

One-shot tools that author + render a narrated motion-graphics video in a single call (author → speech → alignment → resolve → render). The director writes the VO script and shot-sequence brief for you. These tools are the motion-graphics (typography + shapes) path — for a bare “explainer” ask with no stated visual style, the tool descriptions instruct the LLM to confirm the method with the user first; illustrated/animated-footage explainers route to get_recipe → video-explainer instead. See Video Director for credit costs, honest Phase-1 limits, and the full brief format.

start_video_director

Scope: none — always visible (all editions, free).

Returns the motion-director doctrine: pick a genre and arc, draft the VO as cue phrases, build a ShotSequenceBrief, then drive the Phase-0 pipeline yourself. Idempotent, non-destructive, zero credits.

Input: none

create_explainer

Scope: workflows:execute (Cloud only)

Author and render a narrated, time-coded concept-led explainer video in one call. Costs 20 credits (9 authoring + 3 speech + 3 alignment + 0 resolve + 5 render). Returns a job_id.

Input: topic (string, 1–8000 chars) — what the explainer should cover.

create_launch_video

Scope: workflows:execute (Cloud only)

Author and render a narrated product-launch video. Pass brief describing the product. Passing url without brief returns a deferred-capability message (real-UI capture is not yet supported). Costs 20 credits. Returns a job_id.

Input: brief (string, 1–8000 chars), url (string, optional — not yet supported)

Utility tools

reduce

Scope: workflows:execute

Summarize or reduce a list of text items using an LLM. Useful for post-processing arrays of generated captions or descriptions into a single coherent output.

ping

Scope: none (always visible)

Returns "pong" plus the authenticated Nodaro user id and the calling MCP client name. Use to verify the connector is wired up correctly.

Input: none

start_film_director

Scope: none (always visible)

Returns the Film Director skill — a multi-step prompt that instructs the LLM to drive a 10-stage director workflow (script → characters → storyboard → animation → audio → final cut) and assemble an editable Nodaro workflow on your canvas in real-time.

Input: none

start_workflow_editor

Scope: none (always visible)

Returns the Workflow Editor skill — a step-by-step guide instructing the LLM how to create, edit, and run Nodaro workflows via MCP tools.

Input: none

get_node_skill

Scope: none (always visible)

Returns documentation for a specific node type — accepted inputs, outputs, and configuration options — so the LLM can correctly populate that node when building or editing a workflow.

Input: { node_type: string }

get_recipe

Scope: none (always visible)

Discover and load multi-step Nodaro content recipes — curated, terminal-verb-anchored playbooks (e.g. video-explainer) that walk the LLM through a full multi-tool flow. Call with no argument to list available recipes (name, description, trigger phrases); pass recipe to load that recipe’s full instructions; add file to read a bundled reference file inside it. Pure content delivery, no side effects — the actions a recipe instructs the LLM to take are scope-gated by their own tools. The video-explainer recipe is for explainers told through generated animated footage; for kinetic-typography/motion-graphics explainers use start_video_director instead. When the user hasn’t specified a style, the recipe itself asks (see Content Recipes).

Input:

Field Type Notes
recipe string Recipe name, e.g. "video-explainer". Omit to list all.
file string Relative path inside the recipe folder, e.g. "references/prompts.md". Requires recipe.

See Content Recipes for the current catalog and the RECIPE.md authoring format (frontmatter fields, folder layout, bundled reference files).

get_picker_catalog

Scope: none (always visible)

Discover the valid values for parameter-picker nodes (setting, mood, person, action-fx, lens, …) — curated catalogs that contribute a descriptive clause to a downstream node’s prompt rather than calling the API. Read-only, idempotent, no side effects. Call it before writing a picker node’s value field in update_workflow_json so you set a real catalog id instead of guessing.

Input:

Field Type Notes
node_type string Picker node type, e.g. "setting" (kebab-case, from start_workflow_editor’s catalog). Omit to list every picker.
detail enum compact / full compact (default): id, label, category, icon. full: additionally includes each option’s description and promptHint (the prompt fragment it injects).
category string Single-dim pickers: filter options to one category.
field string Multi-dim pickers (person / styling / framing): return only this dimension’s field.

See Parameter Picker Catalogs for the underlying @nodaro/shared data and the prompt-fragment helpers.