dagucloud · yohamta0 · May 22, 2026 · May 22, 2026
diff --git a/.vitepress/config.js b/.vitepress/config.js
@@ -40,7 +40,19 @@ const fullSidebar = [
       { text: "Core Concepts", link: "/getting-started/concepts" },
       { text: "CLI Commands", link: "/getting-started/cli" },
       { text: "AI Agent", link: "/getting-started/ai-agent" },
-      { text: "MCP Server", link: "/getting-started/mcp" },
+    ],
+  },
+  {
+    text: "MCP Server",
+    items: [
+      { text: "Overview", link: "/mcp/" },
+      { text: "Quickstart", link: "/mcp/quickstart" },
+      { text: "Clients", link: "/mcp/clients" },
+      { text: "Architecture", link: "/mcp/architecture" },
+      { text: "Authentication", link: "/mcp/authentication" },
+      { text: "Tools", link: "/mcp/tools" },
+      { text: "Resources", link: "/mcp/resources" },
+      { text: "Auditability", link: "/mcp/auditability" },
     ],
   },
   {
@@ -401,6 +413,7 @@ export default withMermaid(
         { text: "Home", link: "/" },
         { text: "Overview", link: "/overview/", activeMatch: "/overview/" },
         { text: "Quickstart", link: "/getting-started/quickstart", activeMatch: "/getting-started" },
+        { text: "MCP", link: "/mcp/", activeMatch: "/mcp/" },
         { text: "Writing Workflows", link: "/writing-workflows/", activeMatch: "/writing-workflows/" },
         { text: "Actions", link: "/step-types/shell", activeMatch: "/step-types/" },
         { text: "GitHub Integration", link: "/github-integration/", activeMatch: "/github-integration/" },
@@ -412,6 +425,7 @@ export default withMermaid(
         "/": fullSidebar,
         "/overview/": fullSidebar,
         "/getting-started/": fullSidebar,
+        "/mcp/": fullSidebar,
         "/writing-workflows/": fullSidebar,
         "/step-types/": fullSidebar,
         "/github-integration/": fullSidebar,

diff --git a/[page].md b/[page].md
@@ -37,7 +37,7 @@ Credentials: `demouser` / `demouser`
     <p>Declare workflow parameters once in YAML. Dagu uses them to render a guided start form in the Web UI, validate operator input, and keep submitted values attached to the run history.</p>
   </div>
   <div class="overview-card">
-    <h3><a href="/getting-started/mcp">AI-agent ready</a></h3>
+    <h3><a href="/mcp/">AI-agent ready</a></h3>
     <p>Use MCP-capable agents to inspect state, preview workflow changes, apply edits, and start, retry, or stop runs. Agent-authored workflows still run through the same logs, approvals, artifacts, and audit trail as human-authored YAML.</p>
   </div>
 </div>
@@ -372,7 +372,7 @@ steps:
 
 Workflow Operator connects Slack, Telegram, Discord, or LINE to the built-in steward, so teams can ask for run status, debug failures, re-run workflows, and approve actions from chat.
 
-- [MCP Setup](/getting-started/mcp) explains how agents can inspect state and operate workflows through Dagu.
+- [MCP Server](/mcp/) explains how agents can inspect state and operate workflows through Dagu.
 - [AI Agent Authoring](/getting-started/ai-agent) explains workflow generation and debugging with coding agents.
 - [Agent Step](/features/agent/step) explains how to run agent tasks inside DAGs.
 - [Workflow Operator](/features/bots/) explains chat-operator setup.
@@ -413,7 +413,7 @@ Workflow Operator connects Slack, Telegram, Discord, or LINE to the built-in ste
     <p>Compare local, self-hosted, managed, and hybrid operating models.</p>
   </div>
   <div class="step-card">
-    <h3><a href="/getting-started/mcp">MCP Setup</a></h3>
+    <h3><a href="/mcp/">MCP Server</a></h3>
     <p>Connect AI agents to inspect state, preview changes, and operate workflow runs.</p>
   </div>
 </div>

diff --git a/getting-started/ai-agent.md b/getting-started/ai-agent.md
@@ -109,7 +109,7 @@ http://localhost:8080/mcp
 
 The MCP server exposes `dagu_read`, `dagu_change`, and `dagu_execute` for reading state, previewing or applying DAG changes, and controlling DAG runs.
 
-See [MCP Server](/getting-started/mcp) and [CLI Commands](/getting-started/cli#external-ai-coding-tool-integration) for more details.
+See [MCP Server](/mcp/) and [CLI Commands](/getting-started/cli#external-ai-coding-tool-integration) for more details.
 
 ## See Also
 
@@ -121,7 +121,7 @@ See [MCP Server](/getting-started/mcp) and [CLI Commands](/getting-started/cli#e
 - [Personality](/features/agent/settings/behavior) — Configure profiles
 - [Agent Step](/features/agent/step) — Using the agent as a workflow step
 - [AI agent Tools Reference](/features/agent/tools) — Detailed tool parameter documentation
-- [MCP Server](/getting-started/mcp) — Connect external MCP clients to a running Dagu server
+- [MCP Server](/mcp/) — Connect external MCP clients to a running Dagu server
 - [Workflow Operator](/features/bots/) — Use the built-in steward from Slack, Telegram, Discord, or LINE
 - [Basic Chat](/features/chat/basics) — Single-shot LLM calls in workflows
 - [OpenCode](/features/chat/opencode) — Kimi, DeepSeek, GLM, Qwen via OpenCode subscription

diff --git a/getting-started/cli.md b/getting-started/cli.md
@@ -789,7 +789,7 @@ The skill helps AI coding tools write correct Dagu workflow YAML. To let MCP-cap
 http://localhost:8080/mcp
 ```
 
-For details, run `gh skill install --help` and see [MCP Server](/getting-started/mcp).
+For details, run `gh skill install --help` and see [MCP Server](/mcp/).
 
 ### `migrate`
 

diff --git a/getting-started/installation/index.md b/getting-started/installation/index.md
@@ -63,7 +63,7 @@ export DAGU_DATA_DIR=/var/lib/dagu
 dagu version
 ```
 
-Then run the [Quickstart](/getting-started/quickstart) to create your first workflow. If you use AI coding tools, install the [Dagu skill](/getting-started/ai-agent#ai-coding-tool-integration) for workflow authoring and connect the [Dagu MCP server](/getting-started/mcp) to operate a running Dagu server.
+Then run the [Quickstart](/getting-started/quickstart) to create your first workflow. If you use AI coding tools, install the [Dagu skill](/getting-started/ai-agent#ai-coding-tool-integration) for workflow authoring and connect the [Dagu MCP server](/mcp/) to operate a running Dagu server.
 
 ## Uninstalling
 

diff --git a/getting-started/mcp.md b/getting-started/mcp.md
@@ -1,210 +1,12 @@
 # MCP Server
 
-Dagu includes a built-in Model Context Protocol (MCP) server. There is no separate Dagu MCP package to install: run the Dagu HTTP server and point your MCP client at the `/mcp` endpoint.
+Dagu's MCP documentation now lives in the dedicated [MCP Server](/mcp/) section.
 
-Use the MCP server when you want an MCP-capable AI tool to inspect Dagu state, edit workflow definitions, or control DAG runs through Dagu's authenticated API.
+Start with [MCP Quickstart](/mcp/quickstart) to connect an MCP-capable client to a running Dagu server, or use the topic pages directly:
 
-## Quick setup
-
-1. Install Dagu with one of the [installation methods](/getting-started/installation/).
-2. Start the server:
-
-```bash
-dagu start-all
-```
-
-3. In your MCP client, add an HTTP or Streamable HTTP MCP server with these values:
-
-| Field | Value |
-|-------|-------|
-| Name | `dagu` |
-| URL | `https://<your-dagu-host>/mcp`, or `http://localhost:8080/mcp` when Dagu runs on the same machine as the MCP client |
-| Auth | Use `Authorization: Bearer <token>` when Dagu authentication is enabled |
-
-If you changed Dagu's server base path, append `/mcp` under that base path instead.
-
-## Install in an MCP client
-
-Dagu's MCP server is built into the Dagu HTTP server, so there is no separate `dagu-mcp` package. Installing MCP for an AI tool means starting Dagu, then adding the Dagu Streamable HTTP endpoint to that tool.
-
-### Before you configure a client
-
-1. Start or identify the Dagu server. For a local same-machine setup:
-
-```bash
-dagu start-all
-```
-
-2. Set the MCP endpoint URL for your Dagu server:
-
-```bash
-export DAGU_MCP_URL=http://localhost:8080/mcp
-```
-
-Use `localhost` only when the AI tool and Dagu server run on the same machine. For a remote or shared Dagu server, use its reachable HTTPS URL instead:
-
-```bash
-export DAGU_MCP_URL=https://dagu.example.com/mcp
-```
-
-Common URL shapes:
-
-| Server setup | MCP URL |
-|--------------|---------|
-| Same-machine local server | `http://localhost:8080/mcp` |
-| Same-machine custom port | `http://localhost:<port>/mcp` |
-| Remote or shared server | `https://dagu.example.com/mcp` |
-| Server base path such as `/dagu` | `https://dagu.example.com/dagu/mcp` |
-
-3. If Dagu uses `builtin` authentication, create an [API key](/server-admin/authentication/api-keys) and export it before launching the MCP client:
-
-```bash
-export DAGU_MCP_API_KEY=dagu_...
-```
-
-Use a role that matches what the client should do. For example, `viewer` is enough for read-only inspection, `operator` can run and stop workflows, and `developer` can create or edit workflows.
-
-Community self-hosted servers can create up to 2 API keys without an active self-host license. For shared teams, prefer individual keys when you need per-user auditability; use an active self-host license when that means you need more than 2 keys.
-
-### Codex
-
-Codex supports Streamable HTTP MCP servers through `config.toml`. The CLI and IDE extension share this configuration.
-
-For a Dagu server without authentication:
-
-```bash
-codex mcp add dagu --url "$DAGU_MCP_URL"
-```
-
-For a Dagu server using `builtin` authentication:
-
-```bash
-export DAGU_MCP_API_KEY=dagu_...
-codex mcp add dagu \
-  --url "$DAGU_MCP_URL" \
-  --bearer-token-env-var DAGU_MCP_API_KEY
-```
-
-This writes the same configuration you can also add manually to `~/.codex/config.toml`:
-
-```toml
-[mcp_servers.dagu]
-url = "https://dagu.example.com/mcp"
-bearer_token_env_var = "DAGU_MCP_API_KEY"
-```
-
-Verify the setup:
-
-```bash
-codex mcp list
-```
-
-In an interactive Codex session, use `/mcp` to see whether the `dagu` server is connected and which tools are available.
-
-### Claude Code
-
-Claude Code supports Streamable HTTP MCP servers with `claude mcp add --transport http`.
-
-For a Dagu server without authentication:
-
-```bash
-claude mcp add --transport http dagu "$DAGU_MCP_URL"
-```
-
-For a Dagu server using `builtin` authentication:
-
-```bash
-export DAGU_MCP_API_KEY=dagu_...
-claude mcp add --transport http dagu "$DAGU_MCP_URL" \
-  --header "Authorization: Bearer ${DAGU_MCP_API_KEY}"
-```
-
-The default Claude Code scope is local to the current project. To make the server available in every Claude Code project on your machine, add `--scope user`:
-
-```bash
-claude mcp add --transport http --scope user dagu "$DAGU_MCP_URL" \
-  --header "Authorization: Bearer ${DAGU_MCP_API_KEY}"
-```
-
-Verify the setup:
-
-```bash
-claude mcp list
-claude mcp get dagu
-```
-
-Inside Claude Code, use `/mcp` to inspect the connection status.
-
-### Share Claude Code setup with a team
-
-Use project scope when you want a repository to include the MCP server definition. Keep the secret in each user's environment:
-
-```bash
-claude mcp add --transport http --scope project dagu "$DAGU_MCP_URL"
-```
-
-Then edit the generated `.mcp.json` so the API key is read from an environment variable instead of being committed:
-
-```json
-{
-  "mcpServers": {
-    "dagu": {
-      "type": "http",
-      "url": "${DAGU_MCP_URL}",
-      "headers": {
-        "Authorization": "Bearer ${DAGU_MCP_API_KEY}"
-      }
-    }
-  }
-}
-```
-
-Each teammate should set `DAGU_MCP_URL`, create their own Dagu API key, and export `DAGU_MCP_API_KEY` before starting Claude Code. Community self-hosted servers can create up to 2 API keys without an active license, so larger teams should configure a self-host license before issuing individual teammate keys.
-
-## Authentication
-
-The MCP endpoint uses the same authentication mode as the Dagu server.
-
-| Dagu auth mode | MCP client setup |
-|----------------|------------------|
-| `none` | No token is required. |
-| `builtin` | Create an [API key](/server-admin/authentication/api-keys) and send it as `Authorization: Bearer dagu_...`. A login JWT also works, but API keys are better for tools and automation. |
-| `basic` | Use HTTP Basic authentication if your MCP client supports it. |
-
-Prefer an `Authorization` header. Codex and Claude Code both support sending headers to HTTP MCP servers. If a client cannot send headers, Dagu also accepts `?token=<token>` on stream endpoints, but headers are safer for shared or proxied environments.
-
-## Tool surface
-
-Dagu intentionally exposes a compact MCP surface:
-
-| Tool | Use it for |
-|------|------------|
-| `dagu_read` | Read DAG lists, DAG details, DAG specs, DAG-run details, logs, and MCP reference resources. |
-| `dagu_change` | Preview and apply DAG YAML upserts. Use `mode=preview` before `mode=apply`. |
-| `dagu_execute` | Start, enqueue, retry, or stop DAG runs. |
-
-The server also exposes resources such as `dagu://dags/{name}/spec`, `dagu://runs/{name}/{dagRunId}`, and `dagu://runs/{name}/{dagRunId}/logs`. MCP clients that support resource subscriptions can subscribe to a run resource and receive an update when the run reaches a terminal state.
-
-## Skill vs MCP
-
-The Dagu skill and the Dagu MCP server solve related but different problems.
-
-| Integration | Install or configure | Best for |
-|-------------|----------------------|----------|
-| Dagu skill | `gh skill install dagucloud/dagu dagu` | Teaching AI coding tools how to write valid Dagu workflow YAML. |
-| Dagu MCP server | `http://localhost:8080/mcp` | Letting MCP clients read Dagu state, validate or apply DAG edits, and control runs. |
-
-Most AI-assisted workflow authoring setups benefit from both: install the skill for authoring guidance, then connect MCP when the tool should operate a running Dagu server.
-
-## Troubleshooting
-
-- **404 or connection refused**: confirm `dagu start-all` is running and the MCP URL matches your server address and base path.
-- **401 unauthorized**: add an API key or login token as `Authorization: Bearer <token>`.
-- **Client shows no tools**: configure Dagu as an HTTP or Streamable HTTP MCP server, not a stdio command.
-- **Remote server access**: expose the Dagu server through your normal secure route, use HTTPS, and give the MCP client a least-privilege API key.
-
-## See also
-
-- [AI Agent](/getting-started/ai-agent) — built-in AI agent and workflow agent steps
-- [CLI Commands](/getting-started/cli) — command reference, including external AI tool integration
-- [API Keys](/server-admin/authentication/api-keys) — bearer tokens for programmatic access
+- [Clients](/mcp/clients)
+- [Architecture](/mcp/architecture)
+- [Authentication](/mcp/authentication)
+- [Tools](/mcp/tools)
+- [Resources](/mcp/resources)
+- [Auditability](/mcp/auditability)
diff --git a/getting-started/quickstart.md b/getting-started/quickstart.md
@@ -226,4 +226,5 @@ steps:
 - [Step Types](/step-types/shell) — built-in executors (docker, ssh, http, wait, sql, s3, sub-DAG, ...)
 - [Examples](/writing-workflows/examples) — ready-to-adapt patterns
 - [CLI Reference](/getting-started/cli) — every command and flag
-- [AI Agent and MCP](/getting-started/ai-agent) — built-in AI agent, the Dagu skill, and the MCP server for external AI tools
+- [AI Agent](/getting-started/ai-agent) — built-in AI agent and the Dagu skill for external AI tools
+- [MCP Server](/mcp/) — connect MCP-capable clients to a running Dagu server
diff --git a/mcp/architecture.md b/mcp/architecture.md
@@ -0,0 +1,61 @@
+# 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.
+
+```mermaid
+flowchart LR
+  client["MCP client"] --> route["Dagu HTTP server /mcp"]
+  route --> auth["Auth middleware"]
+  auth --> mcp["MCP server"]
+  mcp --> api["Dagu API service"]
+  api --> stores["DAG, run, queue, and log stores"]
+  api --> runtime["Runtime and scheduler operations"]
+  auth --> audit["Audit context"]
+  mcp --> audit
+  api --> audit
+```
+
+## 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 state and reference resources.
+- `dagu_change` validates and optionally writes DAG YAML.
+- `dagu_execute` starts, enqueues, retries, or stops DAG runs.
+
+This keeps client instructions stable and avoids exposing every REST endpoint as a separate MCP tool.
+
+## Resource Boundary
+
+The MCP server exposes resource templates for current Dagu state:
+
+| Resource | Backing operation |
+|----------|-------------------|
+| `dagu://dags/{name}/spec` | Current DAG YAML from the DAG spec API |
+| `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://reference/{topic}` | Built-in MCP guidance bundled with the server |
+
+Run resources can be subscribed to. Dagu watches subscribed run resources and sends a resource update notification when a run reaches a terminal state.
+
+## 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 connected with the DAG, run, or API-key events it caused.