Customize Flow Stages

Hooks allow you to intercept and modify tool execution at specific lifecycle stages. Use hooks to add cross-cutting concerns like validation, logging, auditing, rate limiting, and data transformation without modifying individual tools.

Core Concepts

Flows

Named execution pipelines with defined stages (e.g., tools:call-tool, http:request)

Hook Types

Will (before), Did (after), Around (wrap), Stage (one more step of the stage)

Priority

Within a stage, a lower priority runs first, for Will, Did and Stage hooks alike

Context

The running flow, typed FlowCtxOf<'flow-name'>: its typed state, logger and provider lookup

Hook Types

Will (Before)
Did (After)
Around (Wrap)
Stage (Step)

Runs before a stage executes. Use for:

Input validation
Pre-processing
Short-circuiting execution
Setting up context

@ToolHook.Will('execute', { priority: 100 })
async rejectNonPositiveAmount(ctx: FlowCtxOf<'tools:call-tool'>) {
  // A plugin hook sees the tool's arguments untyped: check a value before using it
  const amount = ctx.state.required.input.arguments?.['amount'];
  if (typeof amount === 'number' && amount <= 0) {
    throw new InvalidInputError('Amount must be greater than 0');
  }
}

Runs after a stage completes. Use for:

Post-processing
Logging/auditing
Output transformation
Cleanup

@ToolHook.Did('execute', { priority: 100 })
async redactSensitiveData(ctx: FlowCtxOf<'tools:call-tool'>) {
  const { toolContext } = ctx.state.required;
  const output = toolContext.output;
  if (typeof output !== 'object' || output === null) return;

  // Mask the sensitive fields the result has; the output schema still validates it
  const redacted: Record<string, unknown> = { ...output };
  if ('ssn' in redacted) redacted['ssn'] = '***-**-****';
  if ('creditCard' in redacted) redacted['creditCard'] = '****-****-****-****';
  toolContext.output = redacted;
}

Wraps execution, running code before and after. Use for:

Timing/profiling
Try-catch error handling
Resource management
Transactions

@ToolHook.Around('execute')
async measureExecutionTime(
  ctx: FlowCtxOf<'tools:call-tool'>,
  next: () => Promise<void>
) {
  const start = Date.now();

  try {
    await next(); // Execute the stage
  } finally {
    const duration = Date.now() - start;
    ctx.logger.info(`Tool ${ctx.state.required.input.name} took ${duration}ms`);
  }
}

Runs as one more step of a stage the flow declares, next to the flow’s own step: it does not replace it. At equal priority it runs before the flow’s own step; the value it returns is ignored. Use for:

Extra work that belongs to the stage
Ending the flow early with ctx.respond(), which skips the flow’s own step

@ToolHook.Stage('execute', {
  filter: (ctx) => ctx.state.required.input.name === 'fetch_weather',
})
async mockWeather(ctx: FlowCtxOf<'tools:call-tool'>) {
  // Ends the flow with this result; the tool's execute() does not run
  ctx.respond({ content: [{ type: 'text', text: '72F and sunny' }] });
}

To skip a stage and let the flow go on, use an Around hook that does not call next().

Available Flows

FrontMCP provides pre-defined hooks for common flows. Each flow has its own stages; a hook names one of them:

import { FlowCtxOf, Plugin, ToolHook } from '@frontmcp/sdk';

@Plugin({ name: 'tool-hooks' })
class MyPlugin {
  @ToolHook.Will('execute')
  async beforeToolExecution(ctx: FlowCtxOf<'tools:call-tool'>) {
    // Runs before the tool's execute()
  }

  @ToolHook.Did('execute')
  async afterToolExecution(ctx: FlowCtxOf<'tools:call-tool'>) {
    // Post-process the result: ctx.state.required.toolContext.output
  }
}

import { FlowCtxOf, HttpHook, Plugin } from '@frontmcp/sdk';

@Plugin({ name: 'http-hooks' })
class MyPlugin {
  // http:request stages: traceRequest, checkIpFilter, ..., checkAuthorization, router, then the transport handlers
  @HttpHook.Will('checkAuthorization')
  async beforeAuthorization(ctx: FlowCtxOf<'http:request'>) {
    const { method, path } = ctx.rawInput.request;
    ctx.logger.info(`Authorizing ${method} ${path}`);
  }
}

import { FlowCtxOf, ListToolsHook, Plugin } from '@frontmcp/sdk';

@Plugin({ name: 'list-tools-hooks' })
class MyPlugin {
  // tools:list-tools stages: parseInput, ensureRemoteCapabilities, findTools,
  // filterByAuthorities, resolveConflicts, parseTools
  @ListToolsHook.Did('resolveConflicts')
  async hideInternalTools(ctx: FlowCtxOf<'tools:list-tools'>) {
    const visible = ctx.state.required.resolvedTools.filter(({ finalName }) => !finalName.startsWith('internal_'));
    ctx.state.set('resolvedTools', visible);
  }
}

Hiding a tool from tools/list does not stop a client that knows its name from calling it; gate the call in tools:call-tool too.

You can also create custom flows using FlowHooksOf('custom-flow-name') for application-specific pipelines.

Complete Examples

Example 1: Request Validation & Auditing

import { FlowCtxOf, Plugin, ToolHook, UnauthorizedError } from '@frontmcp/sdk';

@Plugin({
  name: 'audit-plugin',
  description: 'Requires a tenant for tenant-scoped tools and logs all tool executions',
})
export default class AuditPlugin {
  @ToolHook.Will('execute', { priority: 100 })
  async requireTenant(ctx: FlowCtxOf<'tools:call-tool'>) {
    const { tool, toolContext } = ctx.state.required;

    // Enforce tenant isolation for the tools tagged 'tenant-scoped'
    const tenantId = toolContext.authInfo.claims?.['tenantId'];
    if (tool.metadata.tags?.includes('tenant-scoped') && typeof tenantId !== 'string') {
      throw new UnauthorizedError('Tenant ID required for this tool');
    }
  }

  @ToolHook.Did('execute', { priority: 100 })
  async auditExecution(ctx: FlowCtxOf<'tools:call-tool'>) {
    const { tool, toolContext } = ctx.state.required;

    ctx.logger.info('Tool executed', {
      toolName: tool.fullName,
      userId: toolContext.authInfo.user?.sub,
      tenantId: toolContext.authInfo.claims?.['tenantId'],
      timestamp: new Date().toISOString(),
    });
  }
}

Example 2: Error Handling & Retries

An Around hook sees a failing stage as a rejected next(), and can call next() again to retry it. A Did hook runs only after its stage succeeded, so failures are logged here.

import { FlowCtxOf, Plugin, ToolHook } from '@frontmcp/sdk';

@Plugin({
  name: 'resilience-plugin',
  description: 'Retries idempotent tools and logs failures',
})
export default class ResiliencePlugin {
  private readonly maxRetries = 2;

  @ToolHook.Around('execute', {
    filter: (ctx) => ctx.state.tool?.metadata.annotations?.idempotentHint === true,
  })
  async withRetry(ctx: FlowCtxOf<'tools:call-tool'>, next: () => Promise<void>) {
    const toolName = ctx.state.required.input.name;

    for (let attempt = 0; ; attempt++) {
      try {
        await next();
        return; // Success
      } catch (error) {
        if (attempt >= this.maxRetries) {
          ctx.logger.error('Tool execution failed', {
            tool: toolName,
            error: error instanceof Error ? error.message : String(error),
          });
          throw error;
        }
        ctx.logger.warn(`Retry attempt ${attempt + 1} for ${toolName}`);
        await this.delay((attempt + 1) * 1000); // Linear backoff
      }
    }
  }

  private delay(ms: number) {
    return new Promise((resolve) => setTimeout(resolve, ms));
  }
}

Example 3: Data Transformation Pipeline

import { FlowCtxOf, Plugin, ToolHook } from '@frontmcp/sdk';

@Plugin({
  name: 'transform-plugin',
  description: 'Normalizes inputs and tags results',
})
export default class TransformPlugin {
  // Before validateInput, so the tool's input schema checks the normalized values
  @ToolHook.Will('validateInput', { priority: 50 })
  async normalizeInput(ctx: FlowCtxOf<'tools:call-tool'>) {
    const toolArguments = ctx.state.required.input.arguments;
    if (!toolArguments) return;

    for (const [key, value] of Object.entries(toolArguments)) {
      if (typeof value === 'string') {
        toolArguments[key] = value.trim();
      }
    }
  }

  @ToolHook.Did('execute', { priority: 50 })
  async tagResult(ctx: FlowCtxOf<'tools:call-tool'>) {
    // `resultMeta` is merged into the result's `_meta`; the tool's own output stays as its schema defines it
    ctx.state.set('resultMeta', {
      ...ctx.state.resultMeta,
      executedAt: new Date().toISOString(),
    });
  }
}

Priority System

Priority sets the order within a stage: a lower priority runs first, for Will, Did and Stage hooks alike. Hooks with the same priority run in the order they were registered.

class PriorityExample {
  @ToolHook.Will('execute', { priority: 50 })
  async firstValidation() {
    // Runs first
  }

  @ToolHook.Will('execute', { priority: 100 })
  async secondValidation() {
    // Runs second
  }

  @ToolHook.Did('execute', { priority: 50 })
  async firstCleanup() {
    // Runs first after the stage
  }

  @ToolHook.Did('execute', { priority: 100 })
  async lastCleanup() {
    // Runs last
  }
}

To run a Will hook before everything else, give it a very low priority (the observability plugin uses -1000). To run a Did hook after everything else, give it a very high one (1000).

Flow Context

A hook receives the running flow, typed FlowCtxOf<'flow-name'>. It has:

state - The flow’s state, typed per flow (tool, toolContext, input, authInfo, resultMeta, … for tools:call-tool)
rawInput - The input the flow was started with
logger - Logger instance for this flow
get(token) - Resolves a provider
respond(output) / fail(error) - End the flow with an output or an error

The state accepts only the keys the flow declares. The flow has no error or metrics member: a Did hook runs only after its stage succeeded, so observe failures from an Around hook. See Hook Context for details.

@ToolHook.Will('execute')
async logToolInfo(ctx: FlowCtxOf<'tools:call-tool'>) {
  const { tool, toolContext } = ctx.state;

  ctx.logger.info('Executing tool', {
    name: tool?.fullName,
    input: toolContext?.input,
  });
}

@ToolHook.Will('execute')
async tagRequest(ctx: FlowCtxOf<'tools:call-tool'>) {
  // Only declared keys: `resultMeta` is merged into the result's `_meta`
  ctx.state.set('resultMeta', { ...ctx.state.resultMeta, requestId: randomUUID() });
}

@Plugin({ name: 'request-ids' })
class RequestIdPlugin {
  // Each call runs its own flow instance, and every hook of the call receives it
  private readonly requestIds = new WeakMap<FlowCtxOf<'tools:call-tool'>, string>();

  @ToolHook.Will('execute')
  async assignRequestId(ctx: FlowCtxOf<'tools:call-tool'>) {
    this.requestIds.set(ctx, randomUUID());
  }

  @ToolHook.Did('execute')
  async logRequestId(ctx: FlowCtxOf<'tools:call-tool'>) {
    ctx.logger.info('Request completed', { requestId: this.requestIds.get(ctx) });
  }
}

randomUUID comes from @frontmcp/utils.

Hook Registry API

For advanced use cases, you can programmatically access hooks using the Hook Registry API. This is useful when building custom flow orchestration or when you need to dynamically query which hooks are registered.

Accessing the Hook Registry

The registry is the scope’s hooks. A hook reaches the scope by resolving the ScopeEntry token; inside a tool, resource or prompt it is this.scope.

import { FlowCtxOf, Plugin, ScopeEntry, ToolHook } from '@frontmcp/sdk';

@Plugin({ name: 'hook-inspector' })
class MyPlugin {
  @ToolHook.Will('execute')
  async checkRegisteredHooks(ctx: FlowCtxOf<'tools:call-tool'>) {
    const hookRegistry = ctx.get(ScopeEntry).hooks;

    // Now you can use registry methods
    const hooks = hookRegistry.getFlowHooks('tools:call-tool');
  }
}

Registry Methods

getFlowHooks
getFlowHooksForOwner
getFlowStageHooks
getClsHooks

Retrieves the plugin and provider hooks registered for a specific flow.

const hooks = hookRegistry.getFlowHooks('tools:call-tool');
// Returns: HookEntry[] - the flow's plugin and provider hooks, highest priority first

Retrieves the hooks a flow runs for the entries of one owner: the id of the app that owns the tool, resource or prompt. These are the same hooks the flow itself runs for such an entry.Parameters:

flow: The flow name (e.g., 'tools:call-tool')
ownerId (optional): The id of the app that owns the entry

Behavior:

If no ownerId is provided, returns all hooks for the flow
If ownerId is provided, returns:
- Hooks with no owner, and hooks owned by the scope or a plugin (server-level hooks)
- Hooks owned by that app
- Another app’s hooks declared with appliesTo: 'uncovered-apps', when no instance of the same hook applies to the app

// Get all hooks for a flow
const allHooks = hookRegistry.getFlowHooksForOwner('tools:call-tool');

// Get the hooks that run for the tools of the 'billing' app
const billingHooks = hookRegistry.getFlowHooksForOwner('tools:call-tool', 'billing');

Retrieves the plugin and provider hooks on one stage of a flow, of every type.

const executeHooks = hookRegistry.getFlowStageHooks(
  'tools:call-tool',
  'execute'
);
// Returns: HookEntry[] - the Will, Did, Around and Stage hooks on 'execute'; metadata.type tells them apart

Retrieves the hooks declared on an entry class: a @Tool, @Resource, @Prompt or @Agent class. Plugin and provider hooks are not indexed by class; use getFlowHooks() for them.

const classHooks = hookRegistry.getClsHooks(MyTool);
// Returns: HookEntry[] - the hooks declared on the MyTool class

Example: Owner-Scoped Hook Filtering

import { FlowCtxOf, Plugin, ScopeEntry, ToolHook } from '@frontmcp/sdk';

@Plugin({
  name: 'tool-isolation-plugin',
  description: 'Demonstrates owner-scoped hook retrieval',
})
export default class ToolIsolationPlugin {
  @ToolHook.Will('execute')
  async filterHooksByOwner(ctx: FlowCtxOf<'tools:call-tool'>) {
    const { tool } = ctx.state.required;
    const hookRegistry = ctx.get(ScopeEntry).hooks;
    const toolOwnerId = tool.owner.id;

    // Get only hooks relevant to this specific tool
    const relevantHooks = hookRegistry.getFlowHooksForOwner('tools:call-tool', toolOwnerId);

    ctx.logger.info(`Found ${relevantHooks.length} hooks for this tool`, {
      toolOwnerId,
      hooks: relevantHooks.map((h) => h.metadata.stage),
    });
  }
}

The Hook Registry API is an advanced feature primarily intended for framework developers and complex plugin authors. Most users should use the decorator-based approach (@ToolHook, @HttpHook, etc.) instead.

Best Practices

1. Use Plugins for Reusable Hooks

Package related hooks into plugins to reuse across multiple apps:

@Plugin({
  name: 'my-hooks',
  description: 'Reusable hook collection',
})
export default class MyHooksPlugin {
  @ToolHook.Will('execute')
  async myValidation(ctx: FlowCtxOf<'tools:call-tool'>) {
    // Validation logic
  }
}

// Use in app
@App({
  name: 'my-app',
  plugins: [MyHooksPlugin],
})

2. Set Appropriate Priorities

Validation: Low priority (1-20)
Transformation: Medium priority (40-60)
Logging/Metrics (Did hooks): High priority (90-100)

Lower priorities run first, so validation runs before transformation, and late Did hooks capture everything.

3. Handle Errors Gracefully

Throw an MCP error class: a public error such as InvalidInputError reaches the client with its message and code. A plain Error becomes a generic server error, and in production the client sees only its error id.

@ToolHook.Will('execute')
async safeValidation(ctx: FlowCtxOf<'tools:call-tool'>) {
  const { arguments: toolArguments } = ctx.state.required.input;
  if (typeof toolArguments?.['query'] === 'string' && toolArguments['query'].length > 500) {
    throw new InvalidInputError('Invalid input: query is longer than 500 characters');
  }
}

4. Keep Per-Call Data in the Hook, Not the State

The flow state accepts only the keys the flow declares, and a plugin serves every call, so this is shared. Keep per-call data in a local variable of an Around hook, or in a WeakMap keyed on ctx when separate hooks share it:

@ToolHook.Around('execute')
async timeExecution(ctx: FlowCtxOf<'tools:call-tool'>, next: () => Promise<void>) {
  const startTime = Date.now();
  await next();
  ctx.logger.info(`Execution took ${Date.now() - startTime}ms`);
}

5. Avoid Heavy Computation in Hooks

Hooks run for every tool execution. Keep them fast:

Use caching for expensive operations
Delegate heavy work to background jobs
Consider async/non-blocking operations

Links & Resources

Plugin Documentation

Learn more about FrontMCP plugins

Tool Documentation

Understand tool lifecycle and execution

Cache Plugin

See hooks in action with the Cache Plugin

Get Started

Concepts

Build

Deploy

Plugins

Adapters

Extensibility

Testing

React SDK

Guides

Customize Flow Stages

Core Concepts

Flows

Hook Types

Priority

Context

Hook Types

Available Flows

Complete Examples

Example 1: Request Validation & Auditing

Example 2: Error Handling & Retries

Example 3: Data Transformation Pipeline

Priority System

Flow Context

Hook Registry API

Accessing the Hook Registry

Registry Methods

Example: Owner-Scoped Hook Filtering

Best Practices

Links & Resources

Plugin Documentation

Tool Documentation

Cache Plugin

​Core Concepts

Flows

Hook Types

Priority

Context

​Hook Types

​Available Flows

​Complete Examples

​Example 1: Request Validation & Auditing

​Example 2: Error Handling & Retries

​Example 3: Data Transformation Pipeline

​Priority System

​Flow Context

​Hook Registry API

​Accessing the Hook Registry

​Registry Methods

​Example: Owner-Scoped Hook Filtering

​Best Practices

​Links & Resources

Plugin Documentation

Tool Documentation

Cache Plugin

Core Concepts

Hook Types

Available Flows

Complete Examples

Example 1: Request Validation & Auditing

Example 2: Error Handling & Retries

Example 3: Data Transformation Pipeline

Priority System

Flow Context

Hook Registry API

Accessing the Hook Registry

Registry Methods

Example: Owner-Scoped Hook Filtering

Best Practices

Links & Resources