Turn a folder of workflows into a server.

A synchronous tools/call runs in its own throwaway state directory — no checkpoint or context.vars carry-over between calls. The async path (mhl_run_* tools, below) keeps state so a run can be resumed.

Both protocol modes work on one connection: the initialize / notifications/initialized handshake (revisions 2025-11-25 / 2025-06-18 / 2025-03-26), and the stateless 2026-07-28 form where every tools/* request carries params._meta with io.modelcontextprotocol/protocolVersion + io.modelcontextprotocol/clientCapabilities and server/discover replaces initialize. A stateless request missing that _meta is rejected with -32602.

A host that ships its workflows confidential passes --workflows-pack <file> with the key in MHL_SERVE_WORKFLOWS_KEY. Every .mh, prompt … from, skill … from and schema … from file is then read from the pack — never from the disk, and never written anywhere — and <dir> is only the root that paths handed to subprocesses are composed under: a schema's path is <dir>/<its path in the pack>, so the host materializes the files an engine opens by path (schemas, scripts) at that layout. The key is removed from the process environment before anything runs, so no agent CLI or cmd.exec child inherits it and env() cannot read it; the process's own initial environment block (ps -E, /proc/<pid>/environ) still shows it to the same user. A malformed or wrong key, one tampered byte, a truncated pack or a repeated path is fatal — nothing is served. Build the pack with mhl pack <dir> -o workflows.dmpk (key from the same env var, or KEY=$(mhl pack <dir> -o workflows.dmpk --new-key)): every non-hidden file, sorted by path, written only after its workflows load from it. --http only. Format: 12-byte header "DMPK" · u8 2 · 3 zero bytes · u32 count, then per entry a 12-byte nonce, a u32 length and an AES-256-GCM ciphertext (AAD: the entry index as u32) of u16 path length · path · content, little-endian throughout.

Each run is owned by the session (Mcp-Session-Id) that started it. mhl_run_status, mhl_run_resume, mhl_run_cancel and mhl_run_list only act for that caller — any other sees unknown runId (the same answer as a genuinely unknown id, so it is not an existence oracle). Stateless callers have no session and share one anonymous owner, so stateless mode has no per-caller isolation. Terminal runs stay pollable for an hour; a server shutdown cancels any still running.

Each mhl_run_* tool is a thin bridge over a same-named custom JSON-RPC method — run/start, run/status, run/resume, run/cancel, run/list, run/logs — that takes {name, arguments} / {runId} directly and returns the bare status object with no tools/call envelope. Reach for those only when a policy gateway must match one method by name (POST /mcp/run/resume); from an ordinary MCP client, use the tools. Every per-workflow tools/list entry carries _meta.mhl.run.tool: "mhl_run_start" as a hint that it can also be driven async.

The runId from mhl_run_start is durable from that call — it is a real id, not a placeholder that a later step upgrades, and there is no separate claim id. arguments for mhl_run_start and mhl_run_resume must be JSON-serialisable and at most 256 KiB — they are persisted with the run, so pass large payloads by reference (a URL, a blob key), not inline.

Start the server with --state-dir <dir> (or MHL_SERVE_STATE_DIR) and a later process pointed at the same directory can mhl_run_status / mhl_run_resume a runId it never started — the first caller to name the (unguessable) id reclaims it. Without it, run state is per-process and lost on restart. Checkpoints are one small JSON file per completed step, sized by the pipeline's variable state; mhl_run_status on a live run stays a pure in-memory read.

When several server processes share one extension state that advertises the cas capability (atomic compare-and-swap), each run is guarded by a short-lived lock in the store: exactly one replica executes or resumes a given runId at a time, renewed on a heartbeat (~1/3 of the lease TTL). The lease TTL defaults to 45 s; widen it with MHL_SERVE_RUN_LOCK_TTL on a CPU-contended host so a slow renew is not mistaken for a dead replica. Each acquisition is tagged with a token, so a replica whose lease lapsed and was taken over cannot renew or release the successor's lock. A confirmed lease is required to start: if the store cannot be reached to take the lock the run fails ("could not acquire run execution lease") rather than running uncoordinated, and a run/resume whose lock state can't be read is refused. If a replica dies, its lock lapses after the lease TTL and run/status reports the run failed with resumable: true — recovery is an explicit run/resume on a live replica, never automatic; the running replica also cancels its own work if its renewals fail for long enough that the lease is about to expire. A store without cas makes the server refuse to start unless you pass --single-replica (or set MHL_SERVE_SINGLE_REPLICA) to acknowledge a one-writer deployment; a plain --state-dir with no extension state is unaffected. This lock stops two replicas from starting work on the same run, and checkpoint writes are fenced on the lease — with a store that advertises fence (e.g. PostgreSQL) a checkpoint write is one atomic statement conditioned on the lease still being this replica's, so a replica taken over after a stall has the write rejected by the store; without it, a check-then-write with a narrow race. Each replica also runs a periodic housekeeping sweep (every 60 s) that reaps idle sessions and, on a shared store, deletes the records of runs that finished more than MHL_SERVE_TERMINAL_RUN_TTL ago — so the store does not grow without bound. A store that advertises the scan capability serves the durable-intake reconcile/sweep scans and the mhl_serve_runs_pending gauge from a single indexed query instead of a per-run read.

The manifest is projected from the loaded pipeline, so it never drifts from what runs. The workflow resources are available over stdio and HTTP; the mhl://run/* ones need the run registry, so they are HTTP-only and owner-gated exactly like mhl_run_status (a non-owner sees unknown resource). mhl_run_start's result also carries resource_link items pointing at the new run's logs and result.

Same guard surface as serve mcp --http: --token / MHL_SERVE_TOKEN requires Authorization: Bearer <token> on every JSON-RPC request (the Agent Card stays public for discovery); --principal-header / MHL_SERVE_PRINCIPAL_HEADER takes the caller identity from a header an authenticated upstream set, and needs --token (without the shared secret the header is client-spoofable). A cross-origin browser request (non-loopback Origin) is refused, and the request body is capped at 1 MiB. Binding a non-loopback address with no token prints an "unauthenticated" warning.

A2A reports the task's lifecycle state (submitted / working / completed / failed / canceled), not the current step. For step-by-step progress or a resumable gate, use the MCP HTTP mhl_run_* tools above.