this.context

const { requestId, traceContext, authInfo, metadata, sessionId } = this.context

Reference

this.context

Read this.context inside execute().

import { PublicMcpError, Tool, ToolContext, z } from "@frontmcp/sdk";

@Tool({ name: "reopen_ticket", description: "Reopen a closed support ticket", inputSchema: { id: z.string() } })
export class ReopenTicket extends ToolContext {
  async execute({ id }: { id: string }) {
    try {
      return await reopen(id);
    } catch (err) {
      this.contextLogger.error(`reopen ${id} failed: ${String(err)}`);
      this.fail(new PublicMcpError(`Couldn't reopen ${id}. Give support this reference: ${this.context.requestId}`));
    }
  }
}

See more examples below.

Properties

Methods

What each entry point fills in

Seeing what each entry point fills in shows the last three columns. The Node server column is what Reading the Request found running frontmcp dev.

authInfo

this.context.authInfo is what the auth layer produced, before FrontMCP turns it into this.auth:

The token is what this.fetch() forwards to the origins you list. Don't put it in results or logs.

Related members

getCallSurface() and getRunningTool()

Two functions exported by @frontmcp/sdk describe the call the code runs in. Unlike this.context, they work anywhere in that call, including helper functions that have no this:

surface in availableWhen is checked against the same value, so a tool whose surface leaves out "agent" or "job" can't be called by agents or jobs. See Telling a client's call from an in-process one. Changed in 1.8.4: before, only MCP requests had a surface, and getCallSurface() was undefined in a prompt and in anything an agent or a job called.

Where it's available

Where it throws, this.tryGetContext() returns undefined, and this.fetch() adds no headers. See Troubleshooting.

Caveats

• Everything in metadata, clientInfo and platformType came from the client, which can write anything there. Use them for formatting, logging and tracing, never to decide access. Reading the Request explains why.
• The store holds values for one request. To keep something between requests, use a provider.
• this.context throws where there's no request, rather than returning undefined. Use this.tryGetContext() in code that runs in both.

Usage

Tagging logs and errors with the request id

requestId identifies the request in your logs, and this.contextLogger puts it in every line it writes. Give it to the user in an error message, and support can find the failure. Reading the Request walks through this example:

import { PublicMcpError, Tool, ToolContext, z } from "@frontmcp/sdk";

@Tool({ name: "reopen_ticket", description: "Reopen a closed support ticket", inputSchema: { id: z.string() } })
export class ReopenTicket extends ToolContext {
  async execute({ id }: { id: string }) {
    try {
      if (id === "T-2") throw new Error("SQLITE_BUSY: database is locked");
      return { id, status: "open" };
    } catch (err) {
      this.contextLogger.error(`reopen ${id} failed: ${String(err)}`);
      this.fail(new PublicMcpError(`Couldn't reopen ${id}. Give support this reference: ${this.context.requestId}`, "STORE_UNAVAILABLE"));
    }
  }
}

The Logs tab shows the error line, with the first eight characters of the request id and of the trace id in brackets.

Joining a trace

A request with a traceparent header continues that trace: traceContext.traceId is the caller's, and parentId the caller's span. this.fetch() sends it on, so a trace follows the call through your services. Without the header, each request starts a trace of its own.

Tracing with OpenTelemetry, and how a trace continues into the services your tools call, are in Observability and telemetry.

import { App, Tool, ToolContext } from "@frontmcp/sdk";

@Tool({ name: "trace_info", description: "Show this request's trace. For debugging.", inputSchema: {} })
export class TraceInfo extends ToolContext {
  async execute() {
    const { traceId, parentId, traceFlags, raw } = this.context.traceContext;
    return { traceId, parentId, traceFlags, raw };
  }
}

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

FrontMCP reads the header, not the traceparent a client puts in _meta: that one is only echoed back.

Passing a value from a hook to the tool

The store lets a hook work something out once, for the tool to use. Here a plugin decides which support desk a request belongs to, from a header, and tools read it. A tool called with this.callTool() sees the same store, and the next request starts with an empty one:

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

export const DESK = Symbol("desk");

@Plugin({ name: "desk", description: "Works out which support desk a request belongs to" })
export class DeskPlugin extends DynamicPlugin<object> {
  @ToolHook.Will("execute")
  async pickDesk(ctx: FlowCtxOf<"tools:call-tool">) {
    const context = ctx.state.toolContext?.context;
    if (!context || context.has(DESK)) return; // once per request
    context.set(DESK, context.metadata.customHeaders["x-frontmcp-desk"] ?? "general");
  }
}

Use a Symbol or a prefixed string as the key, so plugins don't overwrite each other's values. The hook runs again for the inner call, and has() keeps it from redoing the work. To give tools a typed service instead of a loose value, a CONTEXT-scoped provider is the other way to share per-request state.

Timing parts of a call

mark() records a point in time, and elapsed() measures between marks. "init" is when the request started, so elapsed() with no arguments is how long the request has been running:

import { Tool, ToolContext } from "@frontmcp/sdk";

const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));

@Tool({ name: "export_tickets", description: "Export every ticket as CSV", inputSchema: {} })
export class ExportTickets extends ToolContext {
  async execute() {
    const ctx = this.context;
    ctx.mark("query");
    await sleep(40); // stands in for the database query
    ctx.mark("format");
    await sleep(10); // stands in for building the CSV
    const timings = { queryMs: ctx.elapsed("query", "format"), formatMs: ctx.elapsed("format"), totalMs: ctx.elapsed() };
    this.contextLogger.info(`export timings ${JSON.stringify(timings)}`);
    return { rows: 43, timings, marks: [...ctx.getMarks().keys()], startedAt: ctx.getMarks().get("init") === ctx.timestamp, log: ctx.toLogContext() };
  }
}

this.context.mark() is a timing mark. this.mark(), on the context classes, is something else: it only sets this.activeStage.

Telling a client's call from an in-process one

getCallSurface() and getRunningTool() work in a plain function, so a helper that several tools share can record which tool it ran in, and who asked for it: a client, an agent, a job, or another tool. Here close_ticket notifies the customer through another tool, and both write to the audit log:

import { getCallSurface, getRunningTool } from "@frontmcp/sdk";

/** One line for the audit log, from whichever tool calls it. */
export function auditEntry(action: string) {
  return { action, tool: getRunningTool()?.fullName, from: getCallSurface() ?? "in-process" };
}

Seeing what each entry point fills in

One tool, called through createFetchHandler() with headers, in three auth modes, then through connect() and create():

import { App, FRONTMCP_CONTEXT, Tool, ToolContext } from "@frontmcp/sdk";

@Tool({ name: "describe_request", description: "Describe the request this call arrived in. For debugging.", inputSchema: {} })
export class DescribeRequest extends ToolContext {
  async execute() {
    const c = this.context;
    const { token, clientId, scopes, expiresAt } = c.authInfo;
    return {
      sessionId: c.sessionId,
      verifiedSessionId: c.verifiedSessionId ?? null,
      scopeId: c.scopeId,
      metadata: c.metadata,
      clientInfo: c.clientInfo ?? null,
      platformType: c.platformType ?? null,
      authInfo: { keys: Object.keys(c.authInfo).sort(), token: token ?? null, clientId: clientId ?? null, scopes: scopes ?? null, expiresAt: expiresAt ?? null },
      config: c.config,
      flow: c.flow?.name ?? null,
      sameScope: c.scope === this.scope,
      transport: c.transport !== undefined,
      sessionMetadata: c.sessionMetadata !== undefined,
      sameAsToken: this.get(FRONTMCP_CONTEXT) === c,
    };
  }
}

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

The request sets a User-Agent header, but a browser doesn't let a script set one, so in this Playground metadata.userAgent is missing. From a real client, it's the client's User-Agent.

connect() gives the tool its clientInfo too, but as this.clientInfo, not in this.context. The Node server can't run in the Playground; its column in the table above comes from running frontmcp dev.

Reading the request in a prompt

A prompt has this.context, as a tool does. Here a prompt ends its text with the request id and the trace, for a note that support can trace back:

import { Prompt, PromptContext, type GetPromptResult } from "@frontmcp/sdk";

@Prompt({
  name: "handover_note",
  description: "Write a handover note for a ticket",
  arguments: [{ name: "id", description: "Ticket id, like T-1", required: true }],
})
export class HandoverNote extends PromptContext {
  async execute({ id }: Record<string, string>): Promise<GetPromptResult> {
    const { requestId, traceContext } = this.context;
    const text = `Write a handover note for ticket ${id}. End it with "ref ${requestId}, trace ${traceContext.traceId}".`;
    return { messages: [{ role: "user", content: { type: "text", text } }] };
  }
}

Changed in 1.9.2: before, PromptContext had no context getter, and this.get(FRONTMCP_CONTEXT) was the way to the request. It still returns the same object.

Troubleshooting

RequestContext not available

The full message is RequestContext not available. Ensure execution runs within a request scope created by RequestContextStorage.run(), from a RequestContextNotAvailableError. The code read this.context where FrontMCP 1.9.4 has no request context: in a channel's onEvent(), which runs outside any request, even for an event a tool emitted:

import { Channel, ChannelContext, Tool, ToolContext, z, type ChannelEventBus, type ChannelNotification } from "@frontmcp/sdk";

export const seen: { error?: string; ref?: string } = {};

@Channel({ name: "outages", description: "Service outages", source: { type: "app-event", event: "outage" } })
export class OutagesChannel extends ChannelContext {
  async onEvent(payload: unknown): Promise<ChannelNotification> {
    const { service, ref } = payload as { service: string; ref: string };
    try {
      this.context; // 🚩 throws in a channel
    } catch (err) {
      seen.error = (err as Error).message;
    }
    seen.ref = ref; // ✅ what it needs came in the payload
    return { content: `${service} is down (ref ${ref})` };
  }
}

@Tool({ name: "report_outage", description: "Report that a service is down", inputSchema: { service: z.string() } })
export class ReportOutage extends ToolContext {
  async execute({ service }: { service: string }) {
    const { channelEventBus } = this.scope as unknown as { channelEventBus?: ChannelEventBus };
    delete seen.error;
    delete seen.ref;
    channelEventBus?.emit("outage", { service, ref: this.context.requestId });
    for (let i = 0; i < 100 && !seen.ref; i++) await new Promise((r) => setTimeout(r, 10)); // let onEvent() finish
    return { reported: service, sameRef: seen.ref === this.context.requestId, error: seen.error ?? null };
  }
}

Pass what a channel needs, like a reference to log, in the event's payload. And use this.tryGetContext() in code that runs both in requests and elsewhere. this.auth works in both: in a channel it's an empty caller. A job has the context of the request that started it since 1.9.2; before, it threw here too.

this.context.clientInfo is undefined

The client sent its info at initialize, as clients before MCP 2026-07-28 and connect() do, not in this request's _meta. this.clientInfo on a tool covers both, so read that.

this.context.metadata.clientIp is undefined

Behind createFetchHandler(), the IP comes from the runtime when it says who connected (Deno, Bun, Cloudflare Workers), and from X-Forwarded-For or X-Real-IP only when the environment variable FRONTMCP_TRUST_PROXY says the proxy can be trusted. With neither, and in the Playground, it's undefined. In-process calls never have one. Reading the client's address shows each case.

this.context.sessionId is different on every call

Under MCP 2026-07-28 there are no sessions, so each request gets its own anon: placeholder, even from a signed-in caller. Don't use it to recognize a caller or to key per-user data: use this.auth.user.sub.

A value I set() is gone on the next call

The store belongs to one request. Keep values across requests in a provider, keyed by this.auth.user.sub when they belong to a user.