MCP or REST?

MadMax has two external surfaces and they share one mmx_ token (Settings → developer). They are not interchangeable — each is built for a different kind of caller, and the fastest integrations use both.

The one-line rule

If a model is deciding what to do, use MCP. If your code already knows what to do, use REST.

Use MCP when…

…the caller is an AI client (Claude Desktop, Cursor, Claude Code, or your own agent) that is figuring out a workflow — building, editing, debugging, exploring.

• Tools carry the know-how. get_build_context returns the full step catalog, your connections, and data resources in one call; stage_graph lands a whole build; edit_graph applies a multi-phase modification (remove → add → update → disconnect → connect) with one validation report at the end.
• Every write echoes findings. Mutating tools return the touched steps' remaining issues, so the model repairs problems in the same conversation instead of shipping a broken graph.
• Test machinery is built in. run_workflow_step, get_step_output_paths (a step's real last-run output shape), and validation tools give an agent the same verify loop the in-canvas assistant uses.

Use REST when…

…the caller is CI, a cron job, a backend, or a human with curl — anything deterministic.

• Lifecycle: POST /workflows/:id/activate and /deactivate. This is deliberate: on MCP, activation is human-gated — a model can propose going live, but the decision routes through you. Your own scripts carry your intent, so REST is the sanctioned door.
• Running + observing: POST /workflows/:id/run, then GET /executions/:id/steps — add ?fields[execution-step]=node_id,status,output,error when you need step payloads (outputs are opt-in; errors ride the defaults).
• The data plane: stores (/stores/:id/export, row reads), knowledge bases and documents, memories.
• Portability: single-workflow export/import, and folder-level GET /folders/:id/export / POST /folders/import — the whole multi-workflow document with sibling references preserved.

They compose

The pattern that works best in practice: let the AI build over MCP, then let your automation operate it over REST. An agent stages and repairs the graph conversationally; your deploy script activates it, fires runs, and watches executions with plain HTTP.

Gotchas worth knowing

• Same token, different framing: REST wants Content-Type: application/vnd.api+json; MCP is JSON-RPC at POST /mcp.
• MCP tool discovery is scope-filtered: a read-only token neither sees nor calls mutating tools.
• stage_graph merges into the existing canvas — for surgical changes to a populated workflow, edit_graph is the tool.
• Workflow exports strip environment identifiers (connection ids, webhook bindings) by design; imports surface them as needs-connection findings rather than carrying foreign ids.

See the REST API and MCP pages for the full reference on each surface.