Workflow MCP

Workflow MCP standalone

Workflow MCP runs Claude-compatible JavaScript workflow definitions as durable Codex-backed MCP jobs without requiring Agent Code. Docker owns the runtime, Codex CLI, credentials, state, and process isolation; normal operation needs no host Node.js, Codex, or Agent Code installation. The host runtime needs a local Docker Engine or Docker Desktop plus Compose. The verified release bootstrap also needs GitHub CLI (gh), tar, sha256sum or shasum, and a POSIX shell; Windows uses PowerShell 7 plus the corresponding built-in archive/hash commands.

Codex's Linux Bubblewrap boundary requires unprivileged user namespaces on the Docker host. Docker Desktop supplies that Linux-VM capability. Native Linux operators must allow the container runtime to create nested user namespaces; Ubuntu 24.04 enables an AppArmor restriction that can deny them unless the administrator supplies an appropriate AppArmor policy or changes the documented kernel.apparmor_restrict_unprivileged_userns host setting. Hosts that expose kernel.unprivileged_userns_clone must also enable it. Docker's default seccomp and AppArmor profiles separately block the namespace syscalls and mount propagation Bubblewrap needs, so the published Compose and OCI Registry profiles apply per-container seccomp=unconfined and apparmor=unconfined exceptions. Those exceptions enable the inner Codex sandbox; they do not disable it. The container remains non-root with every capability dropped, no-new-privileges, read-only mounts, and bounded resources. The launcher and doctor fail closed when the real sandbox probe cannot start. Do not replace this runtime shape with a privileged container, added capabilities, writable outer mounts, or a disabled Codex sandbox. See the Docker runtime-security options and the Ubuntu 24.04 security notes.

The normal installation is one long-lived daemon per project. Codex connects to a tiny STDIO proxy with docker compose exec; disconnecting one MCP client therefore does not cancel the daemon or its runs. A session-bound STDIO image mode also exists for generic OCI/MCP registries, but it has a narrower lifecycle contract.

Install

One command, in the project directory, after the matching release is published:

curl -fsSL https://github.com/Juliusolsson05/workflow-mcp/releases/latest/download/install.sh | sh

The script needs only Docker. It pulls the release image pinned by immutable digest (the digest is baked into each released copy of install.sh, so the convenience URL never decides which bytes run), renders the checksummed install bundle from that image, installs the project-scoped launcher, writes the Codex stanza, starts the daemon, and installs a global workflow-mcp PATH shim so every later command is just workflow-mcp from anywhere inside the project. If the host has a Codex login (~/.codex/auth.json), the daemon inherits it read-only — no second login. The tokenless read-only dashboard comes up on http://127.0.0.1:7331 unless --no-web or the port is taken by another instance.

Operators who want to verify publisher attestations and checksums by hand before executing anything should follow the hardened bootstrap in SECURITY.md, which downloads and verifies the same bundle without piping anything to a shell.

Installation creates /.workflow-mcp/, writes one marked project-local Codex MCP stanza to /.codex/config.toml, pulls the image pinned by digest, and records stable instance, Compose project, Docker context, Docker Engine ID fingerprint, project, and named-volume identities. Machine-specific files are gitignored. In the default profile agents read the whole mounted project but the managed Codex permission profile currently grants write only under `.claude/workflows` (the authoring subtree) — the project bind is writable at the container layer, yet an agent commanded to edit other project files is denied by policy, so a workflow that rewrites source will not succeed today. Broadening agent writes to the rest of the project is deliberately deferred to a separately threat-modeled writable-subtree profile (an agent is a prompt-injectable LLM, so widening its reach is not a default). Meanwhile the container root filesystem stays read-only, the daemon stays UID/GID 10001:10001, /data and every secret mount stay unreadable to agent commands, and the project .codex directory stays masked. Install with --hardened to restore the original shipped posture: read-only project bind, startup/durable source approvals, token-gated web, and isolated container-only credentials, all from one recorded profile bit.

Use --no-codex if another configuration manager owns config.toml. instance codex-config inside the image can render the exact stanza for recovery.

Authentication

If the host already has a Codex login, the daemon inherits it and you do not need to log in at all — workflow-mcp doctor and auth status will report Authenticated. Only if there is no usable host credential do you run:

workflow-mcp auth login

This uses Codex's device-code flow, which your ChatGPT account must permit — if device authorization is disabled in your ChatGPT security settings, this command fails until you enable it (or supply an API key at install with --api-key-file). Host-login inheritance is the path that avoids this entirely.

That is a Codex device login owned by the container: it prints a URL and code, and writes a real credential into the container's own Codex home. It always works, and a container login always wins over anything inherited.

Host-login inheritance is a best-effort convenience, not a promise. Install detects ~/.codex/auth.json (honoring CODEX_HOME) and mounts it read-only as a seed for the container's writable Codex home; when that seed is usable you never need to log in at all. But a host ChatGPT/subscription login carries account and configuration state beyond that one file, so the seed can copy cleanly and still leave the containerized Codex unable to authenticate. The daemon therefore verifies the inherited credential by asking Codex itself rather than assuming a readable file means "configured" — auth status reports it honestly, and if it cannot authenticate, the fix is the one auth login above. Use --no-host-auth at install to skip detection entirely; --hardened also disables inheritance.

For the explicit non-interactive path, put only the key in an ordinary non-symlink file and bind its absolute path at installation (an explicit API key always wins over host inheritance):

umask 077

printf '%s\n' "$OPENAI_API_KEY" > /absolute/private/openai-api-key

Native Linux only: local Compose secrets retain host ownership. Grant the fixed runtime identity

read access to this one file without broadening its mode; Docker Desktop normally needs no ACL.

setfacl -m u:10001:r /absolute/private/openai-api-key ./workflow-mcp-bundle/workflow-mcp-docker install /absolute/project \ --api-key-file=/absolute/private/openai-api-key /absolute/project/.workflow-mcp/workflow-mcp-docker up

Compose presents that file as /run/secrets/openai_api_key; it is not copied into the installation, run records, logs, or backup. Removing or rotating the host file affects the next container start.

Interactive device login is daemon-owned and refuses account mutation while a workflow is active:

./workflow-mcp-docker auth status

./workflow-mcp-docker auth login ./workflow-mcp-docker auth logout

The login stream travels over the private admin Unix socket. Do not call codex login through a separate docker compose exec: that would create an uncoordinated writer to the shared Codex home.

Codex MCP use

The generated Codex stanza runs the installed, project-scoped launcher:

/absolute/project/.workflow-mcp/workflow-mcp-docker mcp-proxy

The launcher revalidates instance/context identity and reconstructs every recorded Compose overlay before entering the proxy. The proxy keeps stdout exclusively for MCP JSON-RPC and authenticates to the loopback daemon with the MCP token stored in the named volume. It exposes fourteen tools:

• workflow_list, workflow_author_guide, workflow_describe, and workflow_validate discover definitions and teach authoring;
• workflow_run, workflow_resume, and workflow_run_cancel mutate durable run state;
• workflow_run_status and workflow_run_events follow a run by strict cursor; and
• the five result/agent tools page complete workflow and per-agent evidence without filesystem paths.

workflow_run returns immediately. Keep polling workflow_run_events from the returned cursor or read workflow_run_status; MCP transport lifetime is not run lifetime.

Terminal and browser interfaces

The terminal UI and status command are read-only clients of the daemon:

./workflow-mcp-docker status

./workflow-mcp-docker status --json ./workflow-mcp-docker ui

The interactive UI uses 1–5 or Left/Right for runs, workflow result, agent result, transcript, and diagnostics. Use Up/Down to select or scroll, [/] to change the selected run outside the run-list view, Tab/Shift-Tab to change agents, and n/p/g for next, retained previous, and first page. Inventory, result, and transcript cursors keep a fixed 32-entry history; only the current content page is retained in memory. ui --snapshot is the non-interactive, non-ANSI fallback.

The browser UI is on by default: open http://127.0.0.1:7331 and the dashboard loads with no token. What replaced the bearer is invisible and free: the port binds to loopback only, foreign Host headers are refused (which defeats DNS rebinding — a rebound name arrives carrying the attacker's Host), cross-site Origins are rejected, the API is GET-only, and there is no cancel, approval, auth, token-rotation, backup, or project-write route to protect in the first place. Inventory, result, and transcript controls page through bounded API responses and replace the current content page instead of accumulating an unbounded DOM transcript. Choose the port with install --web-port=PORT, opt out with --no-web; under --hardened the web API requires the bearer from token --purpose=web again, and the page shows its token form when it sees a 401.

Web publication requires Docker Engine 28.3.3 or newer because earlier engines had a loopback publication bypass. An explicit --web-port below that floor is refused; the web-on-by-default detection simply downgrades to no web UI with an upgrade hint. Base/terminal/MCP operation does not publish a host port and does not impose that web-specific floor.

Profiles: default and hardened

The default profile is built for one person on their own machine. Authoring is on: Codex can call workflow_run with an inline script, the source is persisted under the project's .claude/workflows, and it runs immediately — no approval command exists between an agent writing a workflow and executing it, because the operator launched this MCP against their own project and the workflow is their own agent's output. The MCP server instructions ship the complete authoring format on connect, so a fresh client needs no example files to learn the DSL.

--hardened restores the original review posture from a single recorded bit:

• Sources are read-only. Existing visible .claude/workflows/*.js files are approved at daemon startup by canonical identity and exact SHA-256 bytes; inline MCP source fails with authoring-disabled before any project filesystem operation. Combine with --authoring for the narrow writable-.claude/workflows overlay: the launch