MCP Architecture

Dagu serves MCP from the same HTTP server as the Web UI and REST API. The MCP route is not a separate daemon, package, or sidecar.

Request Path

1. The MCP client connects to the public /mcp route with Streamable HTTP.
2. Dagu applies the same auth stack used by stream endpoints: query-token support, client IP capture, API key or session validation, and default stream-user injection.
3. MCP requests must satisfy the MCP API-key surface when an API key is used.
4. The MCP server handles tools, resources, prompts, subscriptions, and unsubscribe requests.
5. Tool implementations call the internal frontend API service rather than bypassing Dagu's normal authorization and validation paths.

The route honors the server base path. With base_path: /dagu, the route is /dagu/mcp.

Tool Boundary

Dagu exposes a small tool surface by design:

• dagu_read reads and searches DAGs and Wiki pages, inspects root and child runs, and reads logs and reference resources.
• dagu_change previews or applies DAG definition upserts, renames, and deletions, plus workspace-aware Wiki page changes.
• dagu_execute starts, enqueues, retries, or stops DAG runs and can wait for an identified run to finish.

This keeps client instructions stable and avoids exposing every REST endpoint as a separate MCP tool.

The deprecated dagu_create_doc and dagu_edit_doc prompts forward to the Wiki prompts.

The tool boundary does not include human-task completion or push-back. MCP can author and start a root DAG containing action: human.task, locally or on a distributed worker, and it can read the resulting run state. Complete or push back a waiting task through the Web UI, REST API, or local dagu human-task complete and dagu human-task push-back commands. Human tasks are not supported in sub-DAGs.

Resource Boundary

The MCP server exposes resource templates for current Dagu state:

Resource	Backing operation
dagu://reference	Available built-in MCP references
dagu://dags	DAG summaries visible to the caller
dagu://dags/{name}/spec	Current DAG YAML from the DAG spec API
dagu://wiki	Wiki page tree from the Wiki API across accessible workspaces
dagu://wiki/{workspace}	Wiki page tree for one workspace
dagu://wiki/{workspace}/{path}	Markdown content for one Wiki page
dagu://runs	DAG-run summaries visible to the caller
dagu://runs/{name}/{dagRunId}	DAG-run details from the run details API
dagu://runs/{name}/{dagRunId}/logs	DAG-run logs from the logs API
dagu://runs/{name}/{dagRunId}/steps/{stepName}/logs	Standard output and standard error for one root-run step
dagu://runs/{name}/{dagRunId}/sub/{subRunId}	Child-run details addressed under the root run
dagu://runs/{name}/{dagRunId}/sub/{subRunId}/steps/{stepName}/logs	Standard output and standard error for one child-run step
dagu://reference/{topic}	Built-in MCP guidance bundled with the server

Clients can subscribe to run resources. Dagu watches subscribed runs and sends a resource update notification when a run reaches a terminal state or stops at a waiting checkpoint. Wiki page resources are read on demand; successful Wiki page mutations continue to notify the Web UI through the existing Wiki API notifier.

The dagu://docs resource family remains registered as a deprecated alias for older clients.

Audit Context

The MCP route seeds an audit context before authentication. That context records:

• source=mcp
• surface=mcp
• transport=streamable_http
• request and correlation IDs
• optional requested workspace from the workspace query parameter

After authentication, Dagu adds credential and subject attribution. Tool calls and downstream API actions share the same correlation ID, so an MCP attempt can be linked to the DAG, run, or API-key events it caused.