MCP Tools ​

Dagu intentionally exposes three MCP tools.

dagu_read ​

Use dagu_read for current Dagu state.

Examples:

{ "target": "dags", "query": "page=1&perPage=100" }

{ "target": "dag_spec", "name": "nightly-report" }

Search DAG definitions across accessible workspaces:

{
  "target": "dag_search",
  "workspace": "all",
  "search": "warehouse_url",
  "limit": 20
}

Results contain matching line snippets and canonical DAG spec URIs. If hasMore is true, pass nextCursor as cursor in the next call and keep search and workspace unchanged.

List Wiki pages in one workspace:

{
  "target": "wiki",
  "workspace": "operations",
  "prefix": "runbooks",
  "query": "flat=true&perPage=100&sort=mtime&order=desc"
}

In tree mode, page and perPage select direct children of the workspace or prefix, and each returned directory includes its descendants. In flat mode, they select individual Wiki pages. Wiki page lists accept up to 200 entries per page.

Read or search Markdown Wiki pages:

{ "target": "wiki_page", "workspace": "operations", "path": "runbooks/restart" }

{
  "target": "wiki_search",
  "workspace": "operations",
  "prefix": "runbooks",
  "search": "database failover",
  "limit": 20
}

Search results include matching snippets and modifiedAt. If hasMore is true, pass nextCursor as cursor in the next call and keep search, workspace, and prefix unchanged.

Inspect an .xlsx workbook on the server before writing xlsx steps for it:

{ "target": "workbook", "path": "/srv/data/orders.xlsx" }

The result describes each sheet, its used range, detected data block, header row, headers, column types, row count, and tables, with five typed sample rows, plus the workbook's named ranges and date system. Each column carries a profile over up to 5000 data rows: filled and blank cells, distinct values, the values themselves when a few repeat, the lowest and highest number or date, and the odd cells that do not read as the column's type, such as 未定 in a number column. Use it to choose where, types, and on_type_error for xlsx.read. path is any file the server process can read, and is recorded in the audit log as workbook_path.

The legacy docs, doc, and doc_search targets remain available as deprecated exact aliases. New clients should use the Wiki target names.

{ "uri": "dagu://runs/nightly-report/latest/logs?tail=100" }

Read stdout and stderr for one step:

{
  "target": "step_log",
  "name": "nightly-report",
  "dagRunId": "20260522T010000",
  "stepName": "generate-report",
  "query": "stream=stderr&offset=101&limit=200"
}

step_log supports tail, head, offset, limit, and stream=stdout|stderr. Use at most one of tail, head, and offset; limit can be used alone or with offset, and by itself reads from the beginning. Without positioning parameters, the last 1000 lines are returned. Values for tail, head, and limit range from 1 to 10000.

Read a child DAG run or one of its step logs by adding the child ID returned in a run step's subRuns list:

{
  "target": "run",
  "name": "nightly-report",
  "dagRunId": "20260522T010000",
  "subRunId": "child-run-id"
}

List the items of a foreach step, filtered by the status each body run reached (not_started, running, succeeded, failed, or aborted):

{
  "target": "foreach_items",
  "name": "nightly-report",
  "dagRunId": "20260522T010000",
  "stepName": "process-files",
  "query": "status=failed"
}

Read one item with foreach_item, or the log of one body step of an item with step_log:

{
  "target": "step_log",
  "name": "nightly-report",
  "dagRunId": "20260522T010000",
  "stepName": "process-files",
  "item": "3",
  "bodyStepName": "upload"
}

Read the default runtime profile of a DAG. The result has configuredProfile, effectiveProfile, and source (dag, workspace, or none):

{ "target": "dag_profile", "name": "nightly-report" }

Successful reads return a stable envelope with target, normalized data, built-in references, and uri when the result has a canonical resource URI. DAG and run lists include canonical URIs; run summaries include numeric and human-readable statuses; run details include the current attemptId, step statuses, errors, log URIs, and child-run references.

dagu_change ​

Use dagu_change to create, update, rename, or delete DAG definitions and to maintain Markdown Wiki pages. Preview does not write; apply uses the same authorization, Git Sync write policy, mutation notifications, and audit path as the REST API.

The legacy upsert_doc, rename_doc, and delete_doc types remain available as deprecated exact aliases.

Preview validates the spec without writing it:

{
  "mode": "preview",
  "type": "upsert_dag",
  "name": "nightly-report",
  "spec": "steps:\n  - name: hello\n    command: echo hello\n"
}

Apply writes only after validation succeeds:

{
  "mode": "apply",
  "type": "upsert_dag",
  "name": "nightly-report",
  "spec": "steps:\n  - name: hello\n    command: echo hello\n"
}

Preview a DAG rename:

{
  "mode": "preview",
  "type": "rename_dag",
  "name": "nightly-report",
  "newName": "daily-report"
}

Preview verifies that the source exists and the destination is available. Repeat the call with mode=apply to rename the stored DAG. Rename changes the stored identifier without rewriting the YAML name field or historical runs. A successful apply links to the destination DAG and omits the obsolete source dagUri.

Preview a DAG deletion:

{
  "mode": "preview",
  "type": "delete_dag",
  "name": "daily-report"
}

Repeat the call with mode=apply to delete the DAG definition. A successful deletion omits dagUri because the resource no longer exists.

Set the default runtime profile of a DAG:

{
  "mode": "preview",
  "type": "set_dag_profile",
  "name": "nightly-report",
  "profile": "prod"
}

set_dag_profile and clear_dag_profile change the server-side DAG setting, not the YAML. Preview checks the profile without writing it. clear_dag_profile removes the setting, so the DAG falls back to its workspace default, if any. Read the current value with target=dag_profile. See Runtime Profiles.

Preview a Wiki page create or update:

{
  "mode": "preview",
  "type": "upsert_wiki_page",
  "workspace": "operations",
  "path": "runbooks/restart",
  "content": "# Restart procedure\n\n..."
}

Rename or move a Wiki page or directory:

{
  "mode": "apply",
  "type": "rename_wiki_page",
  "workspace": "operations",
  "path": "runbooks",
  "newPath": "procedures"
}

Delete a Wiki page or directory:

{
  "mode": "preview",
  "type": "delete_wiki_page",
  "workspace": "operations",
  "path": "procedures/obsolete"
}

dagu_execute ​

Use dagu_execute for run control and for deciding steps that wait for a person.

Start a stored DAG:

{
  "action": "start",
  "targetType": "dag",
  "name": "nightly-report",
  "params": {"TARGET": "orders"},
  "wait": true,
  "waitTimeoutSeconds": 30
}

Enqueue a stored DAG:

{ "action": "enqueue", "name": "nightly-report", "queue": "default" }

Retry a run:

{
  "action": "retry",
  "name": "nightly-report",
  "dagRunId": "20260522T010000",
  "stepName": "load",
  "includeDownstream": true
}

Stop a run:

{ "action": "stop", "name": "nightly-report", "dagRunId": "20260522T010000" }

When a run can be identified, dagu_execute returns canonical resource links for run details and logs. Without wait, it also returns subscription guidance. With wait=true, the result reports whether the run completed, its last observed status, and the normalized run and step summary after terminal completion. A wait timeout does not stop the run.

Tool errors use structured codes such as invalid_tool_input, resource_not_found, conflict, and resource_unavailable. When a stored DAG name is close to an existing name, resource_not_found may include suggestions under details.didYouMean.

Deciding Waiting Steps ​

When dagu_read with target=run lists a step as waiting with approval or humanTask, approve, reject, or push_back decides it. Read the run first and pass its attemptId:

{
  "action": "approve",
  "name": "nightly-report",
  "dagRunId": "20260522T010000",
  "stepName": "publish_gate",
  "inputs": {"TICKET": "CHG-42"},
  "attemptId": "att-2",
  "wait": true
}

• Human-task inputs are typed JSON values, as with dagu human-task complete --inputs-json.
• Deciding requires permission to run DAGs in the run's workspace, as in the Web UI and REST API: operator or above. A decision resumes the run as those surfaces do.
• When attemptId differs from the run's current attempt, the call fails with conflict, changes nothing, and reports the current attempt in details.attemptId. Read the run again before deciding.
• A step that is not waiting fails with conflict. An unknown step fails with resource_not_found.
• reject on a human task, a non-string approval input, a missing required approval input, and input the task's form refuses fail with invalid_tool_input and change nothing.
• Without wait, the result includes stepName and the run's status and statusLabel observed after the decision.

attemptId is optional on the server's own MCP endpoint. Calls from Dagu Cloud must pass it, and can decide steps only while the server allows remote approvals.

Through Dagu Cloud ​

Dagu Cloud's MCP endpoint offers the same three tool names for every server in the workspaces a connection reaches. A connection is offered dagu_execute only where it may operate, and dagu_change only where it may edit.

Reading Reported Data ​

Without server, dagu_read answers from what servers reported to Dagu Cloud, including while a server is offline.

workspace keeps one Dagu Cloud workspace. server takes workspace/server, a server name, or the serverRef an answer gave. Every row links to the same thing in Dagu Console.

dagu_execute acts on an open alert, by its alert ref:

Calling a Server ​

With server, the tools call the server's own tools through remote access, with the inputs described above:

• dagu_read targets: run, run_logs, step_log, dags, dag, dag_spec, dag_profile, dag_search, wiki, wiki_page, wiki_search, references, reference, foreach_items, and foreach_item. workspace then names the Dagu workspace on that server. uri reads a dagu:// URI the server's answer gave.
• dagu_execute actions: start, enqueue, retry, stop, approve, reject, and push_back. wait follows a run for up to 50 seconds. Decisions need the attemptId and remote approvals.
• dagu_change types: upsert_dag, rename_dag, delete_dag, set_dag_profile, clear_dag_profile, upsert_wiki_page, rename_wiki_page, and delete_wiki_page, with mode=preview before mode=apply.

Calls through Dagu Cloud offer no resource subscriptions. Read the run again, or pass wait.

Prompts ​

MCP Apps hosts render live run answers in the run inspector.