@Workflow

@Workflow(options)
class MyWorkflow {}

Reference

@Workflow(options)

Apply @Workflow to an empty class: everything is in the options. List the class in an app's workflows array, and the jobs its steps run in the app's jobs.

import { Workflow } from "@frontmcp/sdk";

@Workflow({
  name: "nightly-report",
  description: "Collect one day's tickets, find the SLA breaches, and write a report",
  steps: [
    { id: "collect", jobName: "collect-tickets", input: { day: "2026-09-26" } },
    {
      id: "breaches",
      jobName: "find-sla-breaches",
      dependsOn: ["collect"],
      input: (steps) => ({ tickets: steps.get("collect").outputs.tickets }),
    },
    {
      id: "report",
      jobName: "write-report",
      dependsOn: ["collect", "breaches"],
      input: (steps) => ({ tickets: steps.get("collect").outputs.tickets, breaches: steps.get("breaches").outputs.breaches }),
    },
  ],
})
export class NightlyReport {}

import { App } from "@frontmcp/sdk";
import { CollectTickets, FindSlaBreaches, WriteReport } from "./jobs";
import { NightlyReport } from "./nightly-report.workflow";

@App({
  id: "help-desk",
  name: "Help Desk",
  jobs: [CollectTickets, FindSlaBreaches, WriteReport],
  workflows: [NightlyReport],
})
export class HelpDeskApp {}

See more examples below, and the whole server in the Nightly Ticket Report example.

Options

Required:

Optional:

Steps

The job still checks its input against its own inputSchema, so input that doesn't match fails the step.

steps.get(id)

In input and condition, steps.get(id) returns a finished step's result: { outputs, state }, where outputs is what the step's job returned and state is "completed", "failed" or "skipped". A failed or skipped step's outputs is {}.

For a step that hasn't finished, or doesn't exist, steps.get() throws: in input, the step fails, and in condition, it's skipped. So list every step whose results a step reads in its dependsOn.

How steps run

1. Every step whose dependsOn steps have all finished (completed or skipped) is ready. Up to maxConcurrency of them start together, as one batch.
2. The next batch starts when the whole batch has finished.
3. When a step fails, the steps that depend on it directly are skipped. Steps that don't depend on it keep running.
4. When every step has a result, the workflow is failed if any step failed without continueOnError, and completed otherwise.

A skipped step counts as finished, so the steps after it run. That's what you want after a condition skip, but it also happens after a failure: a step two levels below a failed step runs.

Each attempt of a step runs the job's jobs:execute-job flow, as execute_job does, so a JobHook sees it, and the job's own permissions are checked there against the caller who started the workflow. See Seeing each step's attempts. (New in 1.9.4: before, steps ran outside any flow.)

workflow(options)

The function form takes the same options and returns something to list in workflows:

import { workflow } from "@frontmcp/sdk";

export const remindAda = workflow({
  name: "remind-ada",
  steps: [{ id: "count", jobName: "count-open-tickets", input: { customer: "Ada" } }],
});

Built-in tools

When any app declares a job or a workflow, FrontMCP adds these tools to the server, next to the job tools:

A run's state is pending, running, completed or failed. A workflow that ran, even with failed steps, is a successful execute_workflow call: check state, not isError. The call itself fails only when the workflow can't run: an unknown name, a caller without permission, a dependsOn mistake, or its timeout.

Caveats

• The result doesn't say why a step failed. A failed step is { outputs: {}, state: "failed" }, whatever the reason; the error goes to the server's log, and an error of the step's job to job hooks too.
• Steps retry by default. A step whose job has no retry is tried three times, so a failing step takes 3 seconds before it counts as failed. execute_job runs the same job once.
• A failure only skips the next step. The steps after a skipped step run, so a step two levels below a failed step runs, with {} as the skipped step's outputs. Guard it with a condition.
• dependsOn mistakes are found when the workflow runs, not when the server starts.
• A function input doesn't get the workflow's input. Only steps without input do. Pass it through a step.
• The workflow's inputSchema isn't checked, and trigger and webhook don't do anything.
• Jobs' logs aren't kept: a workflow's result has no logs.
• A step runs its job as the caller who started the workflow, so a step whose job has permissions the caller doesn't meet fails.
• A step's job calls tools on the "job" surface, as it does from execute_job: a tool whose availableWhen.surface leaves out "job" isn't found, and getCallSurface() is "job" in the job and the tools it calls.

Usage

Running steps one after another

A step that lists another in dependsOn waits for it, and its input function can read that step's outputs:

import { Workflow } from "@frontmcp/sdk";

@Workflow({
  name: "remind-customer",
  description: "Count Ada's open tickets and draft a reminder about them",
  steps: [
    { id: "count", jobName: "count-open-tickets", input: { customer: "Ada" } },
    {
      id: "draft",
      jobName: "draft-reminder",
      dependsOn: ["count"],
      input: (steps) => steps.get("count").outputs,
    },
  ],
})
export class RemindCustomer {}

Running steps in parallel

Steps that don't depend on each other start together, up to maxConcurrency at a time. Here three queues load at once, and report waits for all three:

import { Workflow } from "@frontmcp/sdk";

const loadSteps = ["billing", "login", "shipping"].map((queue) => ({
  id: queue,
  jobName: "load-queue",
  input: { queue },
}));

@Workflow({
  name: "queue-report",
  steps: [
    ...loadSteps,
    {
      id: "report",
      jobName: "sum-queues",
      dependsOn: ["billing", "login", "shipping"],
      input: (steps) => ({
        sizes: ["billing", "login", "shipping"].map((id) => steps.get(id).outputs.size as number),
      }),
    },
  ],
})
export class QueueReport {}

@Workflow({ name: "queue-report-one-at-a-time", maxConcurrency: 1, steps: loadSteps })
export class QueueReportOneAtATime {}

Without the TC39 AsyncContext, FrontMCP's browser build runs ready steps one at a time, as if maxConcurrency were 1. (Changed in 1.8.5: before, steps that overlapped there failed and were retried, and the workflow could end failed.) The Playground provides a minimal AsyncContext, so here they run at the same time, as on Node.

Passing input to a workflow

execute_workflow's input goes to every step that has no input of its own. To use it in later steps, have the first step return it, and read it from that step's outputs:

import { Workflow, z } from "@frontmcp/sdk";

@Workflow({
  name: "remind-customer",
  description: "Count a customer's open tickets and draft a reminder about them",
  inputSchema: { customer: z.string() },
  steps: [
    { id: "count", jobName: "count-open-tickets" }, // no input: gets the workflow's
    {
      id: "draft",
      jobName: "draft-reminder",
      dependsOn: ["count"],
      input: (steps) => steps.get("count").outputs, // includes the customer
    },
  ],
})
export class RemindCustomer {}

The second test runs the workflow with a number for customer. execute_workflow accepts it, and the count step fails when its job checks the input, after three attempts.

Handling a failed step

By default, a failed step skips the steps that depend on it and fails the workflow. continueOnError lets its dependents run anyway, and condition skips a step on purpose:

import { App, Job, JobContext, Workflow, z } from "@frontmcp/sdk";

@Job({ name: "notify-team", inputSchema: {}, outputSchema: { sent: z.boolean() } })
export class NotifyTeam extends JobContext {
  async execute(): Promise<{ sent: boolean }> {
    throw new Error("Mail server busy");
  }
}

@Job({ name: "archive-tickets", inputSchema: {}, outputSchema: { archived: z.number() } })
export class ArchiveTickets extends JobContext {
  async execute() {
    return { archived: 12 };
  }
}

@Job({ name: "daily-stats", inputSchema: {}, outputSchema: { closed: z.number() } })
export class DailyStats extends JobContext {
  async execute() {
    return { closed: 12 };
  }
}

@Workflow({
  name: "close-day",
  steps: [
    { id: "notify", jobName: "notify-team", retry: { maxAttempts: 1 } },
    { id: "archive", jobName: "archive-tickets", dependsOn: ["notify"] },
    { id: "stats", jobName: "daily-stats" },
  ],
})
export class CloseDay {}

@App({ id: "help-desk", name: "Help Desk", jobs: [NotifyTeam, ArchiveTickets, DailyStats], workflows: [CloseDay] })
export class HelpDeskApp {}

Running a workflow in the background

With background: true, execute_workflow returns a runId at once. The user who started the run reads its steps with get_job_status: in FrontMCP 1.8, get_workflow_status returns the run's state, but never its steps.

import { App, Job, JobContext, Workflow, z } from "@frontmcp/sdk";

@Job({ name: "load-queue", inputSchema: { queue: z.string() }, outputSchema: { queue: z.string(), size: z.number() } })
export class LoadQueue extends JobContext {
  async execute({ queue }: { queue: string }) {
    await new Promise((resolve) => setTimeout(resolve, 100)); // stands in for a slow query
    return { queue, size: queue.length };
  }
}

@Workflow({
  name: "queue-report",
  steps: [
    { id: "billing", jobName: "load-queue", input: { queue: "billing" } },
    { id: "login", jobName: "load-queue", dependsOn: ["billing"], input: { queue: "login" } },
  ],
})
export class QueueReport {}

@App({ id: "help-desk", name: "Help Desk", jobs: [LoadQueue], workflows: [QueueReport] })
export class HelpDeskApp {}

As with jobs, nobody can read an anonymous caller's runs, so the Playground's Call tab can start a background run but not poll it. The last test signs in as nour. Chaining Jobs into Workflows covers when to run a workflow in the background, and the Nightly Ticket Report example starts one from a tool and keeps its report where another tool can read it.

Seeing each step's attempts

A step's result doesn't say why it failed, but a JobHook sees every attempt of every step, and the job's error when one fails. For a step, ctx.state.workflow is { name, stepId, runId }: the workflow, the step's id and the workflow run's id. ctx.state.runId is undefined, since the workflow run keeps the record:

import { DynamicPlugin, FlowCtxOf, JobHook, Plugin } from "@frontmcp/sdk";

export const stepLog: string[] = [];

@Plugin({ name: "step-log" })
export class StepLogPlugin extends DynamicPlugin<object> {
  @JobHook.Did("finalize", { filter: (ctx) => ctx.state.workflow !== undefined })
  async record(ctx: FlowCtxOf<"jobs:execute-job">) {
    const { workflow, attempt, flowError } = ctx.state;
    stepLog.push(`${workflow?.name}/${workflow?.stepId} attempt ${attempt}: ${flowError ? flowError.message : "completed"}`);
  }
}

The two steps don't depend on each other, so they run together, and the test sorts the lines. The same hook sees execute_job's runs too, without workflow; the filter leaves them out. (New in 1.9.4: before, steps ran outside any flow, and nothing but the server's log saw their errors.)

Troubleshooting

A step failed, and the result doesn't say why

A step's result is { outputs: {}, state: "failed" } whatever went wrong: the job threw, its input didn't match, it timed out, its jobName doesn't exist, or its input function read a step that hadn't finished. The error only goes to the server's log; a job hook also sees the errors of the step's job. To see it, run the step's job by itself with execute_job and the same input:

import { App, Job, JobContext, PublicMcpError, Workflow, z } from "@frontmcp/sdk";

@Job({ name: "escalate", inputSchema: { ids: z.array(z.string()) }, outputSchema: { paged: z.string() } })
export class Escalate extends JobContext {
  async execute({ ids }: { ids: string[] }): Promise<{ paged: string }> {
    this.fail(new PublicMcpError("Nobody is on call tonight.", "NO_ON_CALL"));
  }
}

@Workflow({ name: "sla-check", steps: [{ id: "escalate", jobName: "escalate", input: { ids: ["T-7"] }, retry: { maxAttempts: 1 } }] })
export class SlaCheck {}

@App({ id: "help-desk", name: "Help Desk", jobs: [Escalate], workflows: [SlaCheck] })
export class HelpDeskApp {}

If the step's input comes from a function, return the values it would build from an earlier step, and pass those.

A failing step takes three seconds

A step whose job has no retry is tried three times, waiting 1 and then 2 seconds, so it fails after 3 seconds. Set retry on the step, or on the job, to change that:

import { App, Job, JobContext, Workflow, z } from "@frontmcp/sdk";

@Job({ name: "notify-team", inputSchema: {}, outputSchema: { sent: z.boolean() } })
export class NotifyTeam extends JobContext {
  async execute(): Promise<{ sent: boolean }> {
    throw new Error("Mail server busy");
  }
}

@Workflow({ name: "notify", steps: [{ id: "notify", jobName: "notify-team" }] })
export class Notify {}

@Workflow({ name: "notify-once", steps: [{ id: "notify", jobName: "notify-team", retry: { maxAttempts: 1 } }] })
export class NotifyOnce {}

@App({ id: "help-desk", name: "Help Desk", jobs: [NotifyTeam], workflows: [Notify, NotifyOnce] })
export class HelpDeskApp {}

A step ran even though a step before it failed

When a step fails, FrontMCP 1.8 skips the steps that depend on it, and then treats those as finished, so the steps after them run. Here archive fails, report is skipped, and notify, which depends on report, runs, with {} as the report. A condition that checks the step before it stops that:

import { App, Job, JobContext, Workflow, z } from "@frontmcp/sdk";

@Job({ name: "archive-tickets", inputSchema: {}, outputSchema: { archived: z.number() } })
export class ArchiveTickets extends JobContext {
  async execute(): Promise<{ archived: number }> {
    throw new Error("Archive is full");
  }
}

@Job({ name: "write-report", inputSchema: {}, outputSchema: { text: z.string() } })
export class WriteReport extends JobContext {
  async execute() {
    return { text: "12 tickets archived" };
  }
}

@Job({ name: "email-report", inputSchema: { text: z.string().optional() }, outputSchema: { sent: z.string() } })
export class EmailReport extends JobContext {
  async execute({ text }: { text?: string }) {
    return { sent: text ?? "(no report)" };
  }
}

const steps = [
  { id: "archive", jobName: "archive-tickets", retry: { maxAttempts: 1 } },
  { id: "report", jobName: "write-report", dependsOn: ["archive"] },
];

@Workflow({
  name: "unguarded",
  steps: [
    ...steps,
    { id: "notify", jobName: "email-report", dependsOn: ["report"], input: (s) => s.get("report").outputs },
  ],
})
export class Unguarded {}

@Workflow({
  name: "guarded",
  steps: [
    ...steps,
    {
      id: "notify",
      jobName: "email-report",
      dependsOn: ["report"],
      condition: (s) => s.get("report").state === "completed", // ✅ only after a real report
      input: (s) => s.get("report").outputs,
    },
  ],
})
export class Guarded {}

@App({ id: "help-desk", name: "Help Desk", jobs: [ArchiveTickets, WriteReport, EmailReport], workflows: [Unguarded, Guarded] })
export class HelpDeskApp {}

Step "…" depends on unknown step "…" or Workflow has a cycle involving step "…"

A step's dependsOn names a step id that isn't in steps, or steps depend on each other in a loop. FrontMCP checks this when the workflow runs, not when the server starts, so the server starts fine and every execute_workflow call fails:

import { App, Job, JobContext, Workflow, z } from "@frontmcp/sdk";

@Job({ name: "archive-tickets", inputSchema: {}, outputSchema: { archived: z.number() } })
export class ArchiveTickets extends JobContext {
  async execute() {
    return { archived: 12 };
  }
}

@Workflow({
  name: "close-day",
  steps: [
    { id: "archive", jobName: "archive-tickets", dependsOn: ["notify"] }, // 🚩 there's no "notify" step
  ],
})
export class CloseDay {}

@App({ id: "help-desk", name: "Help Desk", jobs: [ArchiveTickets], workflows: [CloseDay] })
export class HelpDeskApp {}

Fix the id, or break the loop. A test that runs each workflow once catches this before your users do.

Workflow "…" timed out after …ms

The workflow ran longer than its timeout. FrontMCP checks it each time a batch of steps finishes, so the step that was running finished first, and the call fails with TOOL_EXECUTION_ERROR instead of returning the steps' results:

import { App, Job, JobContext, Workflow, z } from "@frontmcp/sdk";

@Job({ name: "load-queue", inputSchema: { queue: z.string() }, outputSchema: { queue: z.string() } })
export class LoadQueue extends JobContext {
  async execute({ queue }: { queue: string }) {
    await new Promise((resolve) => setTimeout(resolve, 60));
    return { queue };
  }
}

@Workflow({
  name: "queue-report",
  timeout: 50,
  steps: [
    { id: "billing", jobName: "load-queue", input: { queue: "billing" } },
    { id: "login", jobName: "load-queue", dependsOn: ["billing"], input: { queue: "login" } },
  ],
})
export class QueueReport {}

@App({ id: "help-desk", name: "Help Desk", jobs: [LoadQueue], workflows: [QueueReport] })
export class HelpDeskApp {}

Raise timeout, or run the workflow in the background. To limit one step, set the step's timeout: a step that runs too long fails, and the workflow carries on as for any failed step.

Job or workflow "…" not found or not permitted

execute_workflow found no workflow by that name that the caller may run. Check that the name matches @Workflow({ name }) (or its id, if it has one), that the class is in an app's workflows, and that its permissions let the caller run it. A step whose jobName is wrong doesn't cause this error: that step fails.

get_workflow_status returns an empty stepResults

In FrontMCP 1.8, get_workflow_status never fills in stepResults. Call get_job_status with the same runId: its result is the workflow's result, steps included. Running a workflow in the background shows both.

A step's input function can't see the workflow's input

An input function only receives steps. The workflow's input goes to steps without an input. Let the first step take it and return what later steps need, and read that from its outputs, as in Passing input to a workflow.