Automations through MCP

MCP automation tools expose the same validation and execution path as the Flow editor. An agent can discover valid repos, agents, and models before it changes a draft, then inspect each run without loading every graph into the listing.

Work with an existing automation

1. Call mogplex_list_automations with a bounded limit.
2. Pass nextCursor back as cursor when you need another page.
3. Call mogplex_get_automation for the one draft you intend to inspect or change.
4. Call mogplex_get_automation_schema for the graph fields and supported combinations. Use mogplex_set_automation_model for a model change or mogplex_update_automation for a complete graph replacement.
5. Call mogplex_validate_automation with installationId and the complete graph. Then save and publish the draft.
6. After the user authorizes a real run, call mogplex_trigger_automation with the automation id and repo id. This is not a dry run. It can incur charges and change the repository.
7. Inspect execution with mogplex_list_automation_runs and mogplex_get_automation_run_logs.

Create an automation

Call mogplex_list_repos first and use the returned positive installation_id. Call mogplex_list_agents before binding an agent node. Call mogplex_list_models only when you need an explicit model override. Get the graph schema and examples from mogplex_get_automation_schema.

Validate the graph, then call mogplex_create_automation.

Use agent IDs exactly as returned. preset:NAME IDs are valid. Mogplex creates a private agent copy when you save a draft with a preset.

No separate create-agent tool is necessary. For the native Mogplex harness, set harness: "mogplex", and agentId. Leave modelOverride unset or null to use your configured Agent/API/MCP default, or your global default when no surface default is set. If that model is unavailable, Mogplex applies its available-model fallback policy. Mogplex resolves the default when each run starts; it does not pin it in the graph. An explicit modelOverride takes precedence and remains unchanged when settings change. Claude Code and Codex use their own harnesses and credentials. Do not switch harnesses to avoid an agent binding.

If create receives no graph, Mogplex builds a simple Start → Agent → End draft when an agent is available. Set publish: true only when the graph should be validated and activated immediately.

Graph contract

mogplex_get_automation_schema returns the supported node types, fields, validation rules, and a complete scheduled-task example. Create and update also expose the graph schema in their MCP input definitions.

Create and update accept a complete graph object:

{
  "nodes": [],
  "edges": [],
  "viewport": {
    "x": 0,
    "y": 0,
    "zoom": 1
  }
}

nodes and edges are required arrays. viewport is optional, but when present its x, y, and positive zoom values must be valid finite numbers. null, strings, partial objects, and structurally malformed graphs return BAD_REQUEST before the existing draft can be replaced.

The create and update installationId, when supplied, must be a positive safe integer. Invalid values return BAD_REQUEST instead of reaching persistence.

Publish checks

Draft shape validation protects stored data. Publishing applies stricter execution checks:

• exactly one start node
• exactly one end node
• at least one agent node
• valid graph connections and node configuration
• owned installation, repositories, and agent bindings
• an enabled, available model for each native Mogplex agent node

mogplex_validate_automation checks these rules. It does not save data, create an agent, launch a sandbox, or call a model. Validation is not a check of live sandbox capacity or provider credentials.

Publish creates an active version. Trigger always runs the published version, not an unpublished draft.

An active version proves publication, not successful execution. Read the run and node results before you report that it works.

Scheduled tasks

Automations support cron directly. Use the scheduledTask example returned by mogplex_get_automation_schema and replace its installation, repository, agent, and instructions. Set a model override only when needed. The start node needs:

{
  "label": "Daily maintenance",
  "event": "schedule",
  "scheduleCron": "10 7 * * *",
  "scheduleTimezone": "UTC",
  "filter": {
    "scope": "org",
    "installationIds": [123],
    "repos": ["owner/repository"]
  }
}

Use exactly one repository, identified by full_name from mogplex_list_repos. Connect Start to an agent with role: "task", then End. Put the requested work and checks in systemPromptOverride.

Task nodes start on a new branch from the default branch and can run commands and open a PR. Keep autofix, autoMerge, and autoRevert false. Per-tool requireApproval requires the native Mogplex harness.

The edit role fixes an existing PR. It cannot create the first PR for a scheduled task, even with a review node before it. A task needs no review predecessor. Add one only when a separate analysis step helps.

Include a check for existing PRs in the instructions. This is not an atomic duplicate-prevention guarantee. Pause other schedulers that own the same job before the handover.

A test run can still create a PR. An expected NO_ACTION result does not make the run read-only.

Task commands have repository write access. autoMerge: false disables built-in auto-merge, not shell permissions. Use GitHub branch rules to enforce human review before a merge. Task instructions alone do not enforce that rule.

Change one model safely

Prefer mogplex_set_automation_model when only one agent node needs a model change. Pass an enabled modelId, or null to return to the configured default. Publication checks that an enabled, available model can be resolved, whether inherited or explicit. This tool changes the model without a complete graph replacement.

Cancel a Flow run

Call mogplex_cancel_automation_run with automationId and runId. For runId, use the run's id from mogplex_list_automation_runs, or run.jobRunId from mogplex_trigger_automation. Do not use runtime_run_id or run.runtime.runId. These fields refer to the Trigger.dev runtime, not the Flow job.

This tool needs write scope. It checks ownership of the automation and checks that the job belongs to that automation. A trigger also needs access to the target repository. mogplex_cancel_run cancels one-off agent runs, not Flow runs.

Cancellation stops active work and pending waits. It does not disable the schedule or undo completed repository changes. Other queued jobs can start when cancellation releases capacity. A finished run returns CONFLICT (HTTP 409). Inspect its logs before another action.

Delete an automation

Call mogplex_delete_automation with automationId. This tool needs write scope and checks ownership of the automation. Deletion is permanent.

It removes the schedule, the draft, every published version, and the per-node run records. Job runs are kept with no automation attached.

An automation with pending or running job runs returns CONFLICT (HTTP 409) and names those runs. Cancel each one with mogplex_cancel_automation_run, then delete again. A second delete of the same automation returns NOT_FOUND.

Agents should delete only an automation you asked them to remove, or one they created as a test. Give a test automation a name that says so, and have the agent delete it after it reads the run logs.

Inspect runs and logs

mogplex_list_automation_runs returns recent execution summaries. mogplex_get_automation_run_logs returns the detailed node runs, dispatch events, AI calls, errors, token usage, and review findings for one run. Use the run id from the list response rather than repeatedly listing the automation.

Agent node output stores the complete report in text and a short preview in text_summary. Downstream agents receive a separate handoff: a decision, summary, report ID, and report length. Full reports do not enter downstream prompts or Flow output state.

If Mogplex cannot save the report, the node fails before downstream agents start.

Report a decision

Flow agents receive instructions to include exactly one structured declaration:

MOGPLEX_FLOW_HANDOFF: {"decision":"NO_ACTION","summary":"Both changes already have open PRs."}

Use the task's decision code, such as PROCEED, NO_ACTION, or ESCALATE. Codes use uppercase letters, digits, and underscores, with a maximum of 64 characters. Summaries contain at most 2,000 characters. These bounds apply to the handoff, not the full report.

For CLI review nodes, place the declaration before the final MOGPLEX_REVIEW_RESULT line.

Mogplex parses the declaration before it builds the preview. The declaration can appear after a long report without losing the decision. Plain prose such as DECISION: NO_ACTION is not a structured declaration.

Absent declarations have status missing. Malformed or duplicate declarations have status invalid. Neither status grants approval to act.

Use If nodes to gate actions on both decisions.<nodeId>.status equal to reported and decisions.<nodeId>.value equal to the required code. Decision codes do not automatically change graph routing. Do not use summary text as the action gate.

Read the evidence

Native Flow agents receive listFlowReports(offset) and readFlowReport(reportId, offset) tools. These are internal agent tools, not additional MCP tools. Reads check the current job, owner, and upstream report references.

Each read returns up to 20,000 characters and a nextOffset. Offsets use JavaScript string positions. Reads are repeatable, with no lifetime read limit.

Claude Code and Codex receive full report files plus an index.jsonl file under /tmp/mogplex-flow-reports/<jobRunId>/. The prompt names the index. Agents can read file ranges as needed.

These files stay outside the repository checkout. The node-run record remains the durable source.

The inline report context contains at most 16,000 characters across all reports. If some reports do not fit, the prompt explicitly directs the agent to the complete index. An omitted report does not mean NO_ACTION.

Older records that contain truncated text keep that text. Mogplex cannot restore the omitted output. Full reports still consume storage, and evidence reads still consume model input tokens.