Flows and stages

// Hook a stage of a built-in flow (see Hook decorators)
const { Will, Did, Around, Stage } = FlowHooksOf("tools:call-tool");

// Or write a flow, register it, and run it
@Flow({ name, access, inputSchema, outputSchema, plan: { pre, execute, post, finalize, error } })
class MyFlow extends FlowBase<typeof name> {
  @Stage("stageName") async stageName() { /* this.input, this.state, this.respond(), this.fail() */ }
}

await this.scope.registryFlows(MyFlow);
const output = await this.scope.runFlowForOutput(name, input);

Reference

How a flow runs

A flow's plan puts its stage names into phases, which run in this order:

Each stage runs its hooks around it: Will hooks, then Around hooks, then the stage's own step (with any Stage hooks beside it), then Did hooks. A Did hook runs after a stage that worked or answered, not after one that failed. Hook decorators has the order within a stage.

Every run starts fresh: a new flow object, with its own input and an empty state. A hook's ctx is that object, so ctx.state is the state the stages share, and ctx.respond() answers exactly as a stage would.

No built-in flow has error stages. The list flows put their lookups in execute and their formatting in post; the flows that run one entry (tools:call-tool, resources:read-resource, prompts:get-prompt, agents:call-agent, jobs:execute-job) have no post, and close with finalize stages instead. That's why ctx.respond() in a Will("findTool") hook ends a tool call but finalize still runs.

Flows in one request

One request runs several flows, one inside another. For a tools/call from a 2026-07-28 client over HTTP:

Which flows a request runs depends on how it arrives:

For 2026-07-28 requests whose response is streamed (the request asks for progress or log messages), the closing stages of http:request and handle:mcp-202607280728 run as soon as the stream starts, before the tool call has run. Don't time requests or release per-request resources in them.

The method's flow for each request:

Stages of the request flows

Each table lists the stages in order, by phase, and the ctx.state fields each stage sets. A field stays set for the rest of the flow. Reading what the stages set shows them.

tools:call-tool

tools:list-tools, resources:list-resources, resources:list-resource-templates, prompts:list-prompts

The four list flows share one plan:

A hook on the find… stage sees and changes what every app contributes: see Changing what clients list.

resources:read-resource, prompts:get-prompt

agents:call-agent

Under invoke_<agent>, checkEntryAuthorities, acquireQuota and acquireSemaphore pass straight through: the surrounding tools:call-tool has already applied them, so they count once. Changed in 1.8.5: before, this flow never ran, and hooks on it never fired.

jobs:execute-job

One run per attempt of a job: execute_job while the client waits or in the background, each retry, and each step of a workflow. Its hooks are JobHook.

A hook that calls ctx.respond({ result, logs }) before execute answers for the job, which doesn't run: updateRunState records that answer as the run's result. An app's plugins hook that app's jobs; the server's plugins hook every app's. New in 1.9.4: before, jobs ran through no flow.

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

export const attempts: object[] = [];

@Plugin({ name: "attempt-log" })
export class AttemptLog extends DynamicPlugin<object> {
  @JobHook.Did("updateRunState")
  async record(ctx: FlowCtxOf<"jobs:execute-job">) {
    const { job, attempt, runId, workflow, answer } = ctx.state;
    attempts.push({ job: job?.name, attempt, hasRunId: runId !== undefined, workflow, answer });
  }
}

completion:complete, skills:filter

skills:search, skills:load, logging:set-level, resources:subscribe, resources:unsubscribe

Changed in 1.9.3: before, these five flows were registered but never ran, so hooks on them never fired: skills/search and skills/load read the skill registry directly, and the other three were answered without a flow. Session requests and skills shows them running.

Stages of the HTTP and transport flows

relayToSessionOwner is new in 1.9.0: on a distributed deployment, it passes a request for a session another node owns to that node, and does nothing elsewhere (read in FrontMCP's code; it needs Redis and two nodes, so it isn't run here). applyNodeHeaders (new in 1.8.7) sets the X-FrontMCP-Machine-Id response header on a distributed deployment. ctx.rawInput.request in an http:request hook is the request: method, path, headers, query and the parsed body. Seeing every HTTP request uses it.

Other flows

These run for HTTP endpoints outside the MCP endpoint, or for features you turn on. Through createFetchHandler(), they don't run inside http:request. The acquireQuota stage after checkIpFilter counts the request against throttle.global (new in 1.9.2).

The OAuth, well-known, custom-route and task flows need a real server or a client on an older protocol, so this page doesn't show them running. The elicitation flows run for connect()'s in-process client, which keeps a session as older clients do. A question from a 2026-07-28 client runs neither:

import { App, DynamicPlugin, FlowHooksOf, FrontMcp, Plugin, Tool, ToolContext, z } from "@frontmcp/sdk";

export const started: string[] = [];

const ElicitRequest = FlowHooksOf("elicitation:request");
const ElicitResult = FlowHooksOf("elicitation:result");

@Plugin({ name: "elicit-log" })
export class ElicitLogPlugin extends DynamicPlugin<object> {
  @ElicitRequest.Will("parseInput")
  async asked() {
    started.push("elicitation:request");
  }

  @ElicitResult.Will("parseInput")
  async answered() {
    started.push("elicitation:result");
  }
}

@Tool({ name: "close_ticket", description: "Close a ticket once the user confirms", inputSchema: { id: z.string() } })
class CloseTicket extends ToolContext {
  async execute({ id }: { id: string }) {
    const answer = await this.elicit(`Close ticket ${id}?`, z.object({ confirm: z.boolean() }));
    return { id, status: answer.status === "accept" && answer.content?.confirm ? "closed" : "open" };
  }
}

@App({ id: "help-desk", name: "Help Desk", tools: [CloseTicket] })
class HelpDeskApp {}

export const config = { info: { name: "help-desk", version: "1.0.0" }, apps: [HelpDeskApp], plugins: [ElicitLogPlugin], elicitation: { enabled: true } };

@FrontMcp(config)
export default class Server {}

Session requests and skills

logging/setLevel, resources/subscribe and resources/unsubscribe come from clients that keep a session: clients before 2026-07-28 and connect()'s in-process client. 2026-07-28 removed them, so they get -32601 Method not found: resources/subscribe was removed in protocol 2026-07-28 and run no flow. skills/search and skills/load run their flows for every client:

import { App, DynamicPlugin, FlowHooksOf, FrontMcp, Plugin, Resource, ResourceContext, Skill, Tool, ToolContext, z } from "@frontmcp/sdk";

export const started: string[] = [];

const SetLevel = FlowHooksOf("logging:set-level");
const Subscribe = FlowHooksOf("resources:subscribe");
const Unsubscribe = FlowHooksOf("resources:unsubscribe");
const Search = FlowHooksOf("skills:search");
const Load = FlowHooksOf("skills:load");

@Plugin({ name: "request-log" })
export class RequestLogPlugin extends DynamicPlugin<object> {
  @SetLevel.Will("parseInput")
  async setLevel() {
    started.push("logging:set-level");
  }

  @Subscribe.Will("parseInput")
  async subscribe() {
    started.push("resources:subscribe");
  }

  @Unsubscribe.Will("parseInput")
  async unsubscribe() {
    started.push("resources:unsubscribe");
  }

  @Search.Will("parseInput")
  async search() {
    started.push("skills:search");
  }

  @Load.Will("parseInput")
  async load() {
    started.push("skills:load");
  }
}

@Tool({ name: "search_tickets", description: "Search support tickets by title", inputSchema: { query: z.string() } })
class SearchTickets extends ToolContext {
  async execute({ query }: { query: string }) {
    return { tickets: [], query };
  }
}

@Resource({ uri: "tickets://open", name: "open-tickets", mimeType: "application/json" })
class OpenTickets extends ResourceContext {
  async execute() {
    return { tickets: ["T-1"] };
  }
}

@Skill({ name: "triage", description: "Triage incoming tickets", instructions: "Search for duplicates, then set a priority.", tools: [SearchTickets] })
class Triage {}

@App({ id: "help-desk", name: "Help Desk", tools: [SearchTickets], resources: [OpenTickets], skills: [Triage] })
class HelpDeskApp {}

export const config = { info: { name: "help-desk", version: "1.0.0" }, apps: [HelpDeskApp], plugins: [RequestLogPlugin] };

@FrontMcp(config)
export default class Server {}

The answers are the same as before 1.9.3, when the five requests were answered without their flows, except that skills/load with activateSession: true now gives each skill a session: { activated: false } here, where nothing starts a skill session.

Writing a flow

A flow is a class that extends FlowBase, decorated with @Flow (also exported as FrontMcpFlow). Each stage is a method decorated with Stage() from FlowHooksOf(name).

Inside a stage:

For typed this.input, this.state and stage names, add the flow to the global ExtendFlows interface, as in Writing and running a flow.

Registering and running

No @FrontMcp or @App option registers a flow. Register it at run time on an endpoint with scope.registryFlows(MyFlow), from code that has the scope: this.scope in a tool, resource or prompt, or createForGraph().getScopes() in a script. Registering the same class again replaces the first registration.

Both throw what the run fails with, and FlowNotRegisteredError (Flow "desk:nope" is not registered) for a name that isn't registered on that endpoint. A run started from a tool is part of the tool's request: this.context in the flow is the tool's, with the same requestId.

Caveats

• TypeScript rejects a plan written as const satisfies FlowPlan<string>: as const makes the stage lists read-only, and FlowPlan wants plain arrays. Type the plan as FlowPlan<Stages> instead, as in Writing and running a flow.
• A flow's name must be unique on the endpoint. Registering a class with the name of a built-in flow, like tools:list-tools, replaces the built-in one.
• Plugin hooks on your flow run for every run of it, whichever app the plugin is on: a flow of your own has no owner to limit them.

Usage

Seeing which flows a request runs

A server plugin with a Will hook on the first stage of several flows records each flow as it starts, and the librarian agent has a plugin of its own for the reads its model makes. The tests show the nesting for each kind of request:

import { AgentCallHook, DynamicPlugin, FlowHooksOf, HttpHook, JobHook, ListToolsHook, Plugin, ResourceHook, ToolHook } from "@frontmcp/sdk";

export const started: string[] = [];

const SessionHook = FlowHooksOf("session:verify");
const Mcp2026Hook = FlowHooksOf("handle:mcp-202607280728");

@Plugin({ name: "flow-log" })
export class FlowLogPlugin extends DynamicPlugin<object> {
  @HttpHook.Will("traceRequest")
  async http() {
    started.push("http:request");
  }

  @SessionHook.Will("parseInput")
  async session() {
    started.push("session:verify");
  }

  @Mcp2026Hook.Will("parseInput")
  async transport() {
    started.push("handle:mcp-202607280728");
  }

  @ToolHook.Will("parseInput")
  async call() {
    started.push("tools:call-tool");
  }

  @ListToolsHook.Will("parseInput")
  async list() {
    started.push("tools:list-tools");
  }

  @AgentCallHook.Will("parseInput")
  async agent() {
    started.push("agents:call-agent");
  }

  @JobHook.Will("parseInput")
  async job() {
    started.push("jobs:execute-job");
  }

  @ResourceHook.Will("parseInput")
  async read() {
    started.push("resources:read-resource");
  }
}

// On an agent: hooks the agent's own flows
@Plugin({ name: "agent-flow-log" })
export class AgentFlowLogPlugin extends DynamicPlugin<object> {
  @ResourceHook.Will("parseInput")
  async read() {
    started.push("resources:read-resource, in the agent");
  }
}

A hook on http:request sees every request, but it runs before FrontMCP knows which tool is called. To act on tool calls, hook tools:call-tool, which runs whichever way the call arrives: over HTTP, over stdio, or from this.callTool().

Reading what the stages set

ctx.state.snapshot() returns a copy of the state. This plugin records which fields are set after five stages of tools:call-tool, and after the find… stage of tools:list-tools. It also sets resultMeta before finalize, which the second test reads from the result:

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

export const fieldsAfter: Record<string, string[]> = {};

function record(stage: string, state: { snapshot(): object }) {
  const snapshot = state.snapshot() as Record<string, unknown>;
  fieldsAfter[stage] = Object.keys(snapshot).filter((key) => snapshot[key] !== undefined);
}

@Plugin({ name: "state-log" })
export class StateLogPlugin extends DynamicPlugin<object> {
  @ToolHook.Did("parseInput")
  async parsed(ctx: FlowCtxOf<"tools:call-tool">) {
    record("parseInput", ctx.state);
  }

  @ToolHook.Did("findTool")
  async found(ctx: FlowCtxOf<"tools:call-tool">) {
    record("findTool", ctx.state);
  }

  @ToolHook.Did("createToolCallContext")
  async created(ctx: FlowCtxOf<"tools:call-tool">) {
    record("createToolCallContext", ctx.state);
  }

  @ToolHook.Did("execute")
  async executed(ctx: FlowCtxOf<"tools:call-tool">) {
    record("execute", ctx.state);
  }

  @ToolHook.Did("validateOutput")
  async validated(ctx: FlowCtxOf<"tools:call-tool">) {
    record("validateOutput", ctx.state);
  }

  @ToolHook.Will("finalize")
  async marked(ctx: FlowCtxOf<"tools:call-tool">) {
    ctx.state.set("resultMeta", { checked: true });
  }

  @ListToolsHook.Did("findTools")
  async listed(ctx: FlowCtxOf<"tools:list-tools">) {
    record("findTools", ctx.state);
  }
}

Read fields by name, like ctx.state.tool or ctx.state.toolContext, rather than from a snapshot: a snapshot is a copy, and changing it changes nothing.

Writing and running a flow

A triage flow for tickets: loadTicket answers at once for closed tickets and fails for unknown ones, classify picks a priority, and answer sends it. audit, in finalize, runs every time, and onError only when a stage failed. A tool registers the flow the first time it's called, then runs it, and a plugin hooks one of its stages like any other flow's:

import { Flow, FlowBase, FlowHooksOf, PublicMcpError, z, type FlowPlan, type FlowRunOptions } from "@frontmcp/sdk";

const name = "desk:triage" as const;
const inputSchema = z.object({ id: z.string() });
const outputSchema = z.object({ id: z.string(), priority: z.enum(["low", "high", "none"]) });
const stateSchema = z.object({ title: z.string(), vip: z.boolean(), priority: z.enum(["low", "high"]) });

type Stages = "loadTicket" | "classify" | "answer" | "audit" | "onError";
const plan: FlowPlan<Stages> = {
  pre: ["loadTicket"],
  execute: ["classify"],
  post: ["answer"],
  finalize: ["audit"],
  error: ["onError"],
};

// Makes the name known to FlowHooksOf, FlowCtxOf and runFlowForOutput, with typed input and state
declare global {
  interface ExtendFlows {
    "desk:triage": FlowRunOptions<TriageFlow, typeof plan, typeof inputSchema, typeof outputSchema, typeof stateSchema>;
  }
}

const tickets: Record<string, { title: string; status: "open" | "closed"; customer: string }> = {
  "T-1": { title: "Cannot log in", status: "open", customer: "globex" },
  "T-2": { title: "Printer is slow", status: "open", customer: "globex" },
  "T-3": { title: "Old invoice", status: "closed", customer: "globex" },
  "T-4": { title: "Printer is slow", status: "open", customer: "acme" },
};

export const auditLog: string[] = [];
const { Stage } = FlowHooksOf(name);

@Flow({ name, access: "authorized", inputSchema, outputSchema, plan })
export class TriageFlow extends FlowBase<typeof name> {
  private steps: string[] = [];

  @Stage("loadTicket")
  async loadTicket() {
    this.steps.push("loadTicket");
    const ticket = tickets[this.input.id];
    if (!ticket) this.fail(new PublicMcpError(`There's no ticket ${this.input.id}.`));
    if (ticket.status === "closed") this.respond({ id: this.input.id, priority: "none" });
    this.state.set({ title: ticket.title, vip: ticket.customer === "acme" });
  }

  @Stage("classify")
  async classify() {
    this.steps.push("classify");
    this.state.set("priority", /log in|password/i.test(this.state.title ?? "") ? "high" : "low");
  }

  @Stage("answer")
  async answer() {
    this.steps.push("answer");
    if (!this.state.priority) return; // post runs after an early answer too
    this.respond({ id: this.input.id, priority: this.state.priority });
  }

  @Stage("onError")
  async onError() {
    this.steps.push("onError");
  }

  @Stage("audit")
  async audit() {
    auditLog.push(`${this.input.id}: ${this.steps.join(" > ")}`);
  }
}

answer checks for a priority because post runs after the early answer for T-3 too, and a second this.respond() there would replace it. The plugin is on the same app as the tool here, but it doesn't have to be: hooks on a flow of your own run whichever app's plugin declares them.

Answering HTTP requests with a flow

A flow with middleware: { method, path } answers HTTP requests to that path, once it's registered. Its input is the request, and its output an HTTP response: httpRespond.json(body), httpRespond.ok(text) and others build one. A tool registers this one here, so the endpoint appears after the first call:

import { Flow, FlowBase, FlowHooksOf, httpInputSchema, httpOutputSchema, httpRespond, z, type FlowPlan, type FlowRunOptions } from "@frontmcp/sdk";

const name = "desk:export" as const;
const stateSchema = z.object({});
const plan: FlowPlan<"serve"> = { execute: ["serve"] };

declare global {
  interface ExtendFlows {
    "desk:export": FlowRunOptions<ExportFlow, typeof plan, typeof httpInputSchema, typeof httpOutputSchema, typeof stateSchema>;
  }
}

const { Stage } = FlowHooksOf(name);

@Flow({
  name,
  access: "public",
  inputSchema: httpInputSchema,
  outputSchema: httpOutputSchema,
  plan,
  middleware: { method: "GET", path: "/exports" },
})
export class ExportFlow extends FlowBase<typeof name> {
  @Stage("serve")
  async serve() {
    const { query } = this.input.request as { query: Record<string, string | undefined> };
    this.respond(httpRespond.json({ format: query.format ?? "csv", tickets: ["T-1", "T-2"] }));
  }
}

With the Node server, the flow is mounted as an Express route on the same port. Because nothing registers a flow at startup, prefer http.routes for an endpoint that must exist from the first request; a flow is for an endpoint that should run hooks, or that code turns on later.

Troubleshooting

My hook on a flow never runs

Check that the request reaches the flow: stdio, createDirect() and connect() skip http:request, and a 2026-07-28 resources/subscribe or logging/setLevel never gets past the transport (Session requests and skills). Before 1.9.3, logging:set-level, resources:subscribe, resources:unsubscribe, skills:search and skills:load never ran at all. Hook decorators lists the other reasons.

Flow "desk:triage" is not registered

runFlow() or runFlowForOutput() was called with a name that isn't registered on that endpoint: the flow wasn't registered yet, its name is spelled differently, or it was registered on another endpoint (each standalone app is one). Register it with scope.registryFlows() first, on the same scope.

Flow exited without producing output

runFlowForOutput() ran the flow and no stage called this.respond(). Check that the stage that answers is in plan and has a @Stage() decorator with the same name: a plan entry without one is skipped without a warning. Use runFlow() if the flow isn't meant to answer.

Invalid input: expected Object, received undefined from @Flow

The path in the error is inputSchema: every flow needs one, even a flow that takes no input (z.object({})). The error comes when the class is decorated, so importing the file is enough to throw it.

Cannot read properties of undefined (reading 'parse') from this.respond()

The flow has no outputSchema, and respond() parses the answer with it. Add one, like z.object({ ... }).

TypeScript says Argument of type '"desk:triage"' is not assignable to parameter of type 'keyof ExtendFlows'

FlowHooksOf(), FlowCtxOf, FlowBase and @Flow only accept names in the global ExtendFlows interface. Add yours with declare global { interface ExtendFlows { ... } }, as in Writing and running a flow. Every built-in flow is in it, all 46 of them, jobs:execute-job (new in 1.9.4) included. (Changed in 1.9.3: before, 19 were missing, session:verify, handle:mcp-202607280728, handle:streamable-http, elicitation:request and elicitation:result, well-known.jwks and http:ip-filter among them, and code wrote FlowHooksOf<any>("…") with a ctx type of its own. prompts:get-prompt, prompts:list-prompts, completion:complete and the channel flows are typed since 1.9.0, with PromptHook, ListPromptsHook and CompletionHook exported for them.)