Nodaro DocsProjects and workflows
Let an AI assistant build Nodaro workflows as JSON, edit them safely with version checks, move them with export and import, and run them in the mcp project.
The project and workflow tools let an assistant build Nodaro workflows the way the editor stores them: as JSON nodes and connections. The assistant learns the format with start_workflow_editor and get_node_skill, creates and edits workflows, moves them between projects with export and import, and runs them. Every workflow it creates or edits lives in the mcp project, so your own projects stay untouched.
A typical session
Learn the format
Call start_workflow_editor. It returns the workflow JSON shape, the rules for wiring connections, and the catalog of node types. Call get_node_skill for each node type the workflow needs, and get_picker_catalog for the valid values of each picker.
Create the workflow
Call create_workflow with a name and, if you like, the first nodes and connections. The workflow opens in the editor under MCP Workflows.
Edit it safely
Read the current graph with get_workflow_json, then send a delta to update_workflow_json with the version you read. Only the nodes and connections you name change.
Run it
Call run_workflow and follow the run with get_app_run. Each node's result is saved to your library.
start_workflow_editor
Returns the guide an assistant reads before it builds or edits a workflow. The guide covers the workflow JSON shape, the wiring conventions for connections and inputs, and the rules of update_workflow_json. It also lists the result fields of every generation node and the catalog of node types.
Permission: none, always visible. Credits: free.
This tool has no parameters. It changes nothing and can be called any number of times.
get_node_skill
Returns the full guide for one node type: its data fields with their defaults, when to use it, common mistakes, and a worked JSON example. Use it before writing a node of that type into a workflow.
Permission: none, always visible. Credits: free.
| Parameter | Type | Notes |
|---|---|---|
node_type | string | Required. The node type in kebab case, as listed by start_workflow_editor, for example generate-image, list or trim-video. |
Returns: the node's guide. An unknown type returns an error with the list of valid types.
get_picker_catalog
Returns the valid values of a picker node, such as Setting, Mood, Person or Lens. Pickers add a phrase to the prompt of the node they feed, so a workflow must use a real catalog id. Call this tool before you write a picker's value into a workflow.
Permission: none, always visible. Credits: free.
| Parameter | Type | Notes |
|---|---|---|
node_type | string | The picker type in kebab case, for example setting. Omit it to list every picker. |
detail | string | compact (default): id, label, category, term, icon and imageUrl. full also adds each option's description and promptHint, the full phrase it adds to the prompt. |
category | string | For single-dimension pickers: only the options of one category. |
field | string | Only one dimension of a multi-dimension picker, such as Person, Styling or Framing. Also the extra settings of a single-dimension picker, such as the position, duration and intensity of Transition and Character FX, or the position and pace of Character Motion. |
Returns: without node_type, a directory of every picker with its nodeType, label, kind (single or multi), its value field or fields, optionCount and imageCount. With node_type, that picker's options. An unknown type returns an error with the valid types.
Every option carries a term, the short professional phrase to write into a prompt, such as whip pan left. label is only for display. A no-op option such as auto or none has an empty term. Options with a picture carry an absolute imageUrl: show it as it is and never build one from an id. Person and Styling also return sections, their topics in order, each with a label, its fields and an optional picture.
{
"nodeType": "person",
"sections": [
{ "label": "Identity", "fields": ["type", "age", "ethnicity", "regionalAesthetic"],
"imageUrl": "https://app.nodaro.ai/picker-art/character/sections/identity.2d5ec1a4.webp" }
],
"dimensions": [
{ "field": "type", "label": "Type", "options": [
{ "id": "man", "label": "Man", "term": "man",
"imageUrl": "https://app.nodaro.ai/picker-art/character/person/man.441363db.webp" }
] }
]
}The pictures of the look pickers are returned on Nodaro Cloud only. Picker catalogs covers the same data for developers.
list_projects
Lists every project in your account, ordered by name, with its id, name, description, workflow count and creation date. The assistant can read all your projects, but it edits only the mcp project.
Permission: workflows:read. Credits: free.
This tool has no parameters.
Returns: data, the list of projects.
get_project
Returns one project by id or by name.
Permission: workflows:read. Credits: free.
| Parameter | Type | Notes |
|---|---|---|
project_id | string | Required. A project id, or a project name. A name must match exactly, including capital letters, for example My Feature Film. |
Returns: the project's id, name, description, workflow count and creation date.
list_workflows
Lists the workflows in the mcp project, newest first.
Permission: workflows:read. Credits: free.
| Parameter | Type | Notes |
|---|---|---|
limit | integer | From 1 to 100. Default 20. |
cursor | string | The next_cursor of the previous page. |
include_sub_workflows | boolean | Default false, which hides sub-workflows that belong to another workflow, as the editor's project view does. Pass true to list them too. |
Returns: data, with each workflow's id, name, description, version, thumbnail and dates, and next_cursor. A next_cursor of null means the last page.
get_workflow
Returns the details of one workflow in the mcp project: its name, description, version and dates.
Permission: workflows:read. Credits: free.
| Parameter | Type | Notes |
|---|---|---|
workflow_id | string | Required. A workflow id in the mcp project. |
get_workflow_json
Returns the full graph of a workflow in the mcp project: its nodes, connections, settings, name, updated_at and version.
Permission: workflows:read. Credits: free.
| Parameter | Type | Notes |
|---|---|---|
workflow_id | string | Required. A workflow id in the mcp project. |
Returns: the graph. Keep version and send it back with your next change, so the change fails instead of overwriting someone else's edit.
create_workflow
Creates a workflow in the mcp project, empty or with a first graph.
Permission: workflows:write. Credits: free.
| Parameter | Type | Notes |
|---|---|---|
name | string | Required. From 1 to 200 characters. |
description | string | Up to 2,000 characters. |
nodes | array | The first nodes, in the editor's node format. |
edges | array | The first connections. |
settings | object | Workflow settings. |
Returns: the new workflow's id and name. Settings a model does not support are corrected, as described in update_workflow_json.
update_workflow_json
Changes a workflow in the mcp project: its graph, its settings or its thumbnail. Every field except workflow_id is optional, so you can, for example, change only the thumbnail.
Permission: workflows:write. Credits: free.
| Parameter | Type | Notes |
|---|---|---|
workflow_id | string | Required. A workflow id in the mcp project. |
delta | object | A partial change, applied as one step against delta.base_version. The preferred way to edit. See below. |
nodes | array | Replaces every node. Send it together with edges. |
edges | array | Replaces every connection. Send it together with nodes. |
settings | object | Replaces the workflow settings. |
thumbnail_url | string or null | The URL of an image that is already hosted, or null to remove the thumbnail. |
expected_version | integer | The version from get_workflow_json. The change is refused if the workflow changed since. |
expected_updated_at | string | The updated_at from get_workflow_json, an older way to do the same check. Prefer expected_version. |
Returns: a confirmation with the node count, and the list of any settings Nodaro corrected.
Edit with a delta
A delta names only what changes, by id. It cannot be combined with nodes, edges, settings, thumbnail_url or the expected_ fields.
| Delta field | What it does |
|---|---|
base_version | Required. The version from get_workflow_json. The change is refused if the workflow changed since. |
upsert_nodes | Whole nodes to add or replace, matched by id. |
delete_node_ids | Nodes to remove. Their connections are removed too. |
upsert_edges | Whole connections to add or replace, matched by id. |
delete_edge_ids | Connections to remove. |
set | A new name, or new settings that replace the old ones. |
Prefer a delta to sending the whole graph. A full write based on an old copy erases the changes another session made in the meantime.
When the workflow changed in between
With expected_version, expected_updated_at or a delta, a workflow that changed since you read it returns a conflict: "Workflow was modified since you last read it. Fetch the latest JSON with get_workflow_json and retry." Read it again and repeat the change. Without these fields, the write overwrites the workflow unconditionally.
Settings a model does not support
Image nodes take model-specific settings, such as aspectRatio, resolution and quality, and each model allows different values. When a node asks for a value its model does not accept, Nodaro does not refuse the write. It changes the value to one the model supports, or removes it when the model has no such setting, and the reply lists each change:
Updated workflow 4f0c… (12 nodes).
Adjusted 2 parameter(s) the selected model does not accept:
- node_8 (gpt-image): aspectRatio "16:9" → "1:1" — GPT Image 1.5 does not
support aspect_ratio "16:9". Supported: 1:1, 3:2, 2:3.
- node_8 (gpt-image): resolution "2K" → removed — GPT Image 1.5 has no
resolution setting.The structured result carries the same list as adjustments. The stored value is not what you sent, so do not send the original value again. Check each model's allowed values with list_models, or choose a model that supports what you need. create_workflow and import_workflow correct settings in the same way. A node set to several models at once is left as it is.
Prompt pre and post text
Any AI node's data can carry promptPrefix and promptSuffix, text that Nodaro adds before and after the node's prompt when it runs. See Prompt pre and post text.
Studio productions
A workflow that holds a studio production keeps its scenes and results in settings.studio. A settings change that alters or drops settings.studio is refused. Copy it unchanged from get_workflow_json, or leave settings out. To change a production, use the studio production tools.
delete_workflow
Deletes a workflow from the mcp project. Deleting is permanent.
Permission: workflows:write. Credits: free.
| Parameter | Type | Notes |
|---|---|---|
workflow_id | string | Required. A workflow id in the mcp project. |
Returns: a confirmation, or an error when the workflow is not in the mcp project.
export_workflow
Exports any of your workflows, from any project, as a portable JSON bundle. This is the one workflow tool that is not limited to the mcp project.
Permission: workflows:read. Credits: free.
| Parameter | Type | Notes |
|---|---|---|
workflow_id | string | Required. Any of your workflows. |
with_assets | boolean | Default false. true also bundles the characters, objects and locations the workflow uses. |
Returns: the bundle as a JSON string. Pass the whole string to import_workflow.
| Mode | What the bundle holds | Use it for |
|---|---|---|
Template, with_assets: false | The graph, without asset-specific content | Sharing a workflow structure as a reusable template |
Full, with_assets: true | The graph and every character, object and location it uses | Moving a complete production to another account or instance |
When a node uses media that another instance cannot download, such as a file on a self-hosted install's local storage, the bundle lists it under portability.unreachableMedia, with the node, the field and the URL. The bundle still imports, but those nodes do not run elsewhere until the media is uploaded again.
import_workflow
Imports a bundle from export_workflow into the mcp project.
Permission: workflows:write. Credits: free.
| Parameter | Type | Notes |
|---|---|---|
workflow_json | string | Required. The whole JSON string from export_workflow. |
Returns: the new workflow's id and name, and an importReport that says which media was copied, which was left as it is, and which was skipped.
- Media is copied. Media on other hosts is copied to this instance where it can be reached, so the workflow runs from the copies. The limits are 25 files for the graph and 25 more for the bundled assets, with images up to 20 MB and video or audio up to 50 MB. Media on a private host that this instance cannot reach is left as it is and listed as
unreachable. - Assets are re-created. Bundled characters, objects, creatures and locations are created again in your account with new ids. Asset nodes and every
@mention in the graph or the settings point to the new copies, andassetIdMapmaps each old id to its new one. - Copies count against your storage. The images of bundled assets are copied into your own storage. When your storage is full,
assetsSkippednames the assets that were not created; the workflow still lands.
run_workflow
Runs a workflow from the mcp project, exactly as a run in the editor.
Permission: workflows:execute. Credits: the credits of every node that runs, at the same prices as the editor.
| Parameter | Type | Notes |
|---|---|---|
workflow_id | string | Required. A workflow id in the mcp project. |
inputs | object | Changes for this run, keyed by node id. A plain value, such as "blue car", goes to the node's main input field. An object, such as { "prompt": "..." }, sets named fields. |
client_request_id | string | A retry token: 8 to 128 characters of letters, digits and _ - . :. Reuse it when you retry after a timeout, so the run is not started or charged twice. Use a new value for a new run. |
Returns: executionId and name. Follow the run with get_app_run, or explain a failure with diagnose_run. Clients with MCP Apps show the run's progress in a card.
Frequently asked questions
Related
MCP tools reference
Workflows and projects
Import and export
Apps and components
Film Director
Last updated on
Workspaces
List the organizations and workspaces your Nodaro account belongs to and choose where an AI assistant's work lands, with list_workspaces and select_workspace.
Apps and components
Find published Nodaro apps and components, read their inputs, and run them from an AI assistant with list_apps, run_app, list_components and run_component.