Using taskflow on Grok Build

Grok Build is xAI's terminal coding agent. Taskflow's published path is its MCP server; a plugin scaffold is also available in the repository checkout.

This page walks through install, verify, first run, permissions, and long-running flows. The full reference lives in docs/grok-mcp.md in the repo.

Install

Published MCP package (recommended)

grok mcp add taskflow -- npx -y -p grok-taskflow@0.2.0 grok-taskflow-mcp

Requires Node.js ≥ 22.19.0. The MCP protocol code has no MCP SDK dependency. A public Grok plugin marketplace/source is not published yet; do not substitute an imaginary source string.

Plugin scaffold from a monorepo checkout

Until the package is on npm, build locally and point MCP at the compiled bin:

pnpm install
pnpm --filter taskflow-core build
pnpm --filter taskflow-mcp-core build
pnpm --filter taskflow-hosts build
pnpm --filter grok-taskflow build

grok plugin install ./packages/grok-taskflow/plugin --trust
grok plugin enable taskflow

grok mcp add taskflow -- \
  node "$(pwd)/packages/grok-taskflow/dist/mcp/bin.js"

Restart an already-open Grok session (or run grok inspect) so plugins and MCP reload.

Verify the install

grok plugin list
grok plugin details taskflow
grok mcp list
grok mcp doctor taskflow
grok inspect

You should see the plugin (skills + MCP components) and a healthy taskflow MCP server. In the TUI, /plugins and /mcps open the same extensions modal.

Run your first flow

On Grok Build you invoke taskflow through MCP tools (discovered via search_tool / use_tool, often namespaced as taskflow__taskflow_*). The bundled skill routes multi-phase work automatically.

Just ask

> List my saved taskflows.
> Verify this flow, then run it: {name:"review-changes", phases:[...]}
> Run the "review-changes" taskflow with dir set to src.

Call the tool directly

{
  "name": "review-changes",
  "args": { "dir": "src" }
}

{
  "define": {
    "name": "quick-review",
    "phases": [
      {
        "id": "discover",
        "type": "agent",
        "agent": "scout",
        "task": "List changed source files under src/. Output ONLY a JSON array of {path} objects.",
        "output": "json"
      },
      {
        "id": "review-each",
        "type": "map",
        "over": "{steps.discover.json}",
        "as": "file",
        "agent": "security-reviewer",
        "task": "Review {file.path} for security risks. Return one paragraph.",
        "dependsOn": ["discover"],
        "concurrency": 4
      },
      {
        "id": "summarize",
        "type": "reduce",
        "from": ["review-each"],
        "agent": "writer",
        "task": "Combine these reviews into one prioritized summary:\n{steps.review-each.output}",
        "dependsOn": ["review-each"],
        "final": true
      }
    ]
  }
}

Only the phase marked final: true is returned. Intermediate transcripts stay inside the runtime.

Check a flow before spending tokens

{
  "define": {
    "name": "quick-review",
    "phases": [{ "id": "a", "type": "agent", "agent": "executor", "task": "noop", "final": true }]
  }
}

Or render the DAG with taskflow_compile (text outline + optional inline SVG).

How subagents run

Each phase's subagent runs as an isolated grok -p --output-format streaming-json session — a real Grok Build headless process. The server discovers saved flows and agents from its launch cwd.

Permission mapping

Effective thinking maps to Grok's --reasoning-effort flag (off maps to none). A max_turns_reached event fails the phase instead of accepting partial text. Grok 0.2.93 emits no token/cost usage in streaming-json, so the Grok MCP adapter refuses every flow declaring budget rather than silently ignoring an unobservable threshold.

Grok children inherit only platform/proxy/CA plus Grok/xAI/Taskflow-Grok variables. Unrelated parent secrets are removed. Add an intentional task variable by name with the comma-separated PI_TASKFLOW_CHILD_ENV_ALLOW operator setting.

Long-running flows

taskflow_run is synchronous — the tool call returns only when the whole DAG finishes. The plugin ships tool_timeout_sec: 1800; MCP does not expose Pi's detached mode. Split huge graphs. If the client cancels a request, the server aborts the active DAG and subagent instead of leaving hidden background work.

Approvals in MCP mode

MCP-driven runs are non-interactive, so an approval phase auto-rejects (fail-closed for the approval decision). Prefer a gate for agent review.

Tool reference

Alternative: register the MCP server manually

pnpm add -g grok-taskflow
grok mcp add taskflow -- grok-taskflow-mcp
# or: grok mcp add taskflow -- npx -y -p grok-taskflow@0.2.0 grok-taskflow-mcp

Remove

grok plugin uninstall taskflow
grok mcp remove taskflow

Next

• Full repo guide: docs/grok-mcp.md
• Syntax reference for every phase type
• Guides index for patterns and case studies

Last updated on