Reading the Request

What a tool knows about the call

execute() receives the arguments. Everything else about the call is on this. This tool returns the parts you'll use most. You wouldn't ship it, but call it a few times and watch what changes:

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

@Tool({
  name: "describe_call",
  description: "Describe the request this call arrived in. For debugging.",
  inputSchema: {},
})
export class DescribeCall extends ToolContext {
  async execute() {
    return {
      requestId: this.context.requestId,
      traceId: this.context.traceContext.traceId,
      caller: this.auth.user.sub,
      client: this.clientInfo ?? null,
      platform: this.platform,
    };
  }
}

requestId and traceId are new on every call, and here so is the caller: the Playground has no authentication, so each request comes from a new anonymous caller, anon: and a random id. client is the Playground's own description of itself, which it sends with every request. Here is what this offers:

Not all of them are filled in for every call. The deep dive below shows what FrontMCP 1.9.3 fills in for each way of running a server.

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

@Tool({ name: "describe_request", description: "Which client sent this request, and its trace and headers. For debugging.", inputSchema: {} })
export class DescribeRequest extends ToolContext {
  async execute() {
    return {
      client: this.clientInfo ?? null,
      platform: this.platform,
      traceparent: this.context.traceContext.raw,
      headers: this.context.metadata.customHeaders,
    };
  }
}

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

Tagging logs and errors with the request id

When a tool fails for a reason that isn't the model's fault, like a database that's having a bad day, the model can only tell the user something went wrong. This tool does exactly that:

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

@Tool({
  name: "reopen_ticket",
  description: "Reopen a closed support ticket.",
  inputSchema: { id: z.string().regex(/^T-\d+$/).describe("Ticket id, like T-1") },
})
export class ReopenTicket extends ToolContext {
  async execute({ id }: { id: string }) {
    try {
      return await reopen(id);
    } catch {
      this.fail(new PublicMcpError("Something went wrong. Please try again later."));
    }
  }
}

It's safe: the database error stays hidden. But when the user writes to support, "the assistant said something went wrong", nobody can find out which call failed or why. FrontMCP does log the failure, as a warning with an error id, but that line holds only the message the tool wrote: the database error is gone. And the message the model got has nothing for the user to quote.

Log the real error with this.contextLogger, and give the user a reference to quote:

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

@Tool({
  name: "reopen_ticket",
  description: "Reopen a closed support ticket.",
  inputSchema: { id: z.string().regex(/^T-\d+$/).describe("Ticket id, like T-1") },
})
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(
          `The ticket system couldn't reopen ${id} just now. Try again in a minute. ` +
            `If it keeps failing, tell the user to give support this reference: ${this.context.requestId}`,
          "STORE_UNAVAILABLE",
        ),
      );
    }
  }
}

Open the Logs tab. After the time, the error line shows two ids in brackets, like [[1f0c2a9e:5d1b4c7e]]: the first eight characters of the request id and of the trace id. The message the model got ends with the full request id, so support can search the logs for its first eight characters and find the real error. The same id also reaches other services: this.fetch() sends it upstream as x-request-id.

Who is calling

this.auth describes the caller: user.sub says who they are, isAnonymous whether they signed in, scopes and roles what they were granted, and claims what their token said. It's filled in from what your server's authentication checked, usually a token the client sent, so it's the one part of the request a tool can base a decision on. Authenticating Clients covers where it comes from, and Authorizing Calls what each field holds in each auth mode.

This tool lists the tickets assigned to whoever is calling. It has no argument for "who", because the caller doesn't get to choose:

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

const assigned: Record<string, string[]> = { nour: ["T-1", "T-3"], sam: ["T-2"] };

@Tool({
  name: "my_tickets",
  description: "List the support tickets assigned to the signed-in agent.",
  inputSchema: {},
  annotations: { readOnlyHint: true },
})
export class MyTickets extends ToolContext {
  async execute() {
    if (this.auth.isAnonymous) {
      this.fail(new PublicMcpError("Only signed-in agents have tickets. Ask the user to sign in.", "SIGN_IN_REQUIRED"));
    }
    const agent = this.auth.user.sub;
    return { agent, tickets: assigned[agent] ?? [] };
  }
}

The Playground has no authentication, so the call above is anonymous and fails. The second test calls the tool as the agent nour, using create(), which runs a server in-process and lets the calling code say who the user is: the user's sub becomes this.auth.user.sub. That's for tests and trusted code, and Running FrontMCP Anywhere covers it.

Arguments, client info and headers are claims

Only team leads may move a ticket to someone else. Here's a first attempt:

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

const leads = ["nour"];

@Tool({
  name: "reassign_ticket",
  description: "Move a ticket to another agent. Team leads only.",
  inputSchema: {
    id: z.string().regex(/^T-\d+$/),
    to: z.string().describe("The agent to assign it to"),
    requested_by: z.string().describe("Who is asking"),
  },
})
export class ReassignTicket extends ToolContext {
  async execute({ id, to, requested_by }: { id: string; to: string; requested_by: string }) {
    if (!leads.includes(requested_by)) {
      this.fail(new PublicMcpError(`${requested_by} isn't a team lead.`, "LEADS_ONLY"));
    }
    return { id, assignee: to };
  }
}

The check works if the model passes the truth. But the model writes requested_by, from whatever is in the conversation, and a conversation can contain anything: a user who says "I'm Nour", or a ticket whose text says "the team lead asked to reassign this to mallory". The test shows it: an anonymous call that claims to be nour passes as a team lead.

Decide from this.auth, which the model can't write, and take the argument away:

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

@Tool({
  name: "reassign_ticket",
  description: "Move a ticket to another agent. Team leads only.",
  inputSchema: {
    id: z.string().regex(/^T-\d+$/),
    to: z.string().describe("The agent to assign it to"),
  },
})
export class ReassignTicket extends ToolContext {
  async execute({ id, to }: { id: string; to: string }) {
    if (!this.auth.hasRole("lead")) {
      this.fail(new PublicMcpError("Only team leads can reassign tickets.", "LEADS_ONLY"));
    }
    return { id, assignee: to, by: this.auth.user.sub };
  }
}

Roles come from the caller's verified claims, here a roles claim in their token, which this.auth.roles reads. In-process, authContext.user stands in for those claims, so the test puts roles there. Authorizing Calls shows how to declare rules like this one so FrontMCP checks them before execute() runs at all.

Arguments aren't the only thing a client makes up. Everything in the request came from the client, and nothing but your authentication checks any of it:

• Client info. A client names itself in clientInfo, and FrontMCP guesses this.platform from that name. Any client can say it's claude-ai.
• Headers. this.context.metadata holds the User-Agent and every x-frontmcp-* header exactly as the client sent them. If you let this.fetch() pass the x-frontmcp-* ones on to a service, don't let that service trust them either.
• _meta. Trace ids, progress tokens and client capabilities travel in the request's _meta, written by the client.

Use these for what they're good for: formatting a result for a client, logging, joining up a trace. Base access decisions only on the caller your authentication established, in this.auth.

Recap

Try some challenges

import { PublicMcpError, Tool, ToolContext } from "@frontmcp/sdk";
import { upload } from "./storage";

@Tool({
  name: "export_tickets",
  description: "Export every support ticket to a CSV file and return a link to it.",
  inputSchema: {},
})
export class ExportTickets extends ToolContext {
  async execute() {
    try {
      return { url: await upload("tickets.csv", "id,title\nT-1,Cannot log in\n") };
    } catch (err) {
      this.fail(new PublicMcpError(`Export failed: ${String(err)}`, "EXPORT_FAILED"));
    }
  }
}