Skip to main content

Documentation Index

Fetch the complete documentation index at: https://magica.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Workflow runs are asynchronous. Start one with start_run, then poll get_run_status for status until it reaches a terminal state.

​
Request Node Handling

When a workflow contains a Request Node with input fields, start_run automatically detects it and guides the AI assistant through providing values.
1

Initial call

The AI assistant calls start_run with just the workflowId.
2

Field discovery

The tool detects Request Node fields and returns their names, types, and current defaults — instead of starting the run.
3

Call with values

The AI assistant calls start_run again with the values parameter filled in for each Request Node field.
4

Run executes

The workflow runs with the provided inputs. Values are synced to the Request Node in the UI.
The values parameter is keyed by nodeId then fieldId. The tool returns the exact field IDs needed, so the AI assistant can construct the correct payload automatically.

​
Run Results

Both start_run and get_run_status return a structured response with two sections:
The Response Node output — the final workflow result. This is always listed first in the response so the AI assistant can surface the primary result immediately.
If the workflow is still running, the response shows the current execution state and per-node statuses instead. Use get_run_status to poll for the final result.

​
Choosing the Right Tool

The MCP server has two execution paths depending on what you’re doing:
User intentToolNotes
”Generate an image of a Ferrari”execute_toolOne-shot generation — no workflow needed
”Run my saved workflow My Pipeline”start_runUser workflows → falls back to system templates
”Run the Nano Banana Pro template”start_runWorkflow name fuzzy-matches system templates
Workflow name lookups in start_run use fuzzy matching — partial names like “Nano Banana” match “Nano Banana Pro”.
For single-step generation (one image / one video / one TTS clip), prefer execute_tool over building a workflow. Workflows are for reusable multi-step pipelines the user explicitly wants to save.

​
Checking Run Status

After starting a run, use get_run_status to check progress. The same tool works for both execute_tool and start_run results: 
execute_tool / start_run  →  returns runId + initial status
get_run_status(runId)     →  long-polls until COMPLETED / FAILED / CANCELED
get_run_status long-polls (~12 min window) and returns either the final result or a still-running response telling you to call again. Long jobs (1–2 hr videos, project training) typically resolve in 5–10 polls.