Reporting Progress and Logs

A tool that goes quiet

This tool exports every ticket to a CSV file, one ticket at a time. Each ticket takes a moment:

import { Tool, ToolContext } from "@frontmcp/sdk";
import { exportRow, tickets } from "./store";

@Tool({
  name: "export_tickets",
  description: "Export every support ticket to tickets.csv. Takes a few seconds.",
  inputSchema: {},
})
export class ExportTickets extends ToolContext {
  async execute() {
    const rows: string[] = [];
    for (const ticket of tickets) {
      rows.push(await exportRow(ticket));
    }
    return { file: "tickets.csv", rows: rows.length };
  }
}

With five tickets that's under a second. With five thousand, the user stares at a spinner for minutes and can't tell a slow export from a stuck one. Nothing about this tool is wrong, except that it says nothing until it's done.

Reporting progress

this.progress(progress, total, message) sends a progress notification to the client that made the call:

• progress is how much is done so far. It should go up with every call; the MCP spec requires it.
• total is how much there is in all, if you know it. Leave it out if you don't.
• message is a short description of the current step. It's optional too.

import { Tool, ToolContext } from "@frontmcp/sdk";
import { exportRow, tickets } from "./store";

@Tool({
  name: "export_tickets",
  description: "Export every support ticket to tickets.csv. Takes a few seconds.",
  inputSchema: {},
})
export class ExportTickets extends ToolContext {
  async execute() {
    const rows: string[] = [];
    for (const [i, ticket] of tickets.entries()) {
      rows.push(await exportRow(ticket));
      await this.progress(i + 1, tickets.length, `Exported ${ticket.id}`);
    }
    return { file: "tickets.csv", rows: rows.length };
  }
}

The Call tab now shows a progress bar and five progress notifications above the result. A real client gets each one as it's sent, while the tool is still running. The Playground collects the whole response first, so here they appear together when the call ends.

Report after each real unit of work, like a ticket, a page or a file. Progress that jumps from 0 to 100% at the end doesn't tell anyone anything.

Sending log messages

Progress says how far along a tool is. this.notify(message, level) says what's happening, as a log message:

import { Tool, ToolContext } from "@frontmcp/sdk";
import { exportRow, tickets } from "./store";

@Tool({
  name: "export_tickets",
  description: "Export every support ticket to tickets.csv. Takes a few seconds.",
  inputSchema: {},
})
export class ExportTickets extends ToolContext {
  async execute() {
    await this.notify(`Exporting ${tickets.length} tickets to tickets.csv`);

    const rows: string[] = [];
    for (const [i, ticket] of tickets.entries()) {
      if (!ticket.title) await this.notify(`${ticket.id} has no title. It's exported with an empty one.`, "warning");
      rows.push(await exportRow(ticket));
      await this.progress(i + 1, tickets.length, `Exported ${ticket.id}`);
    }

    await this.notify({ file: "tickets.csv", bytes: rows.join("\n").length }, "debug");
    return { file: "tickets.csv", rows: rows.length };
  }
}

Each call to notify() sends a notifications/message:

• A string becomes data: { message: "..." }. An object is sent as data as it is, for clients that read structured logs.
• level is one of MCP's log levels, from least to most severe: "debug", "info", "notice", "warning", "error", "critical", "alert" and "emergency". It defaults to "info".
• FrontMCP sets logger to the tool's name, so the client knows which tool said it.

The client chooses the lowest level it wants, and FrontMCP drops anything below it. The Call tab asks for "info" and up, which is why the debug message with the byte count isn't in the list above.

How a client asks for notifications

In MCP 2026-07-28, notifications belong to the request that caused them, and a client asks for them in that request's _meta:

• a progressToken asks for progress. The server copies the token into every progress notification, so a client with several calls in flight knows which one each update is about.
• io.modelcontextprotocol/logLevel asks for log messages at that level and above.

Open the Wire tab in the example above and expand the tools/call. The request carries both:

{
  "method": "tools/call",
  "params": {
    "name": "export_tickets",
    "arguments": {},
    "_meta": {
      "progressToken": "progress-1",
      "io.modelcontextprotocol/logLevel": "info"
    }
  }
}

(The real request's _meta also holds the protocol version, client info and capabilities.) When a request asks for either, FrontMCP answers with Content-Type: text/event-stream instead of plain JSON. Each notification is an event, sent as it happens, and the last event is the result:

event: message
data: {"jsonrpc":"2.0","method":"notifications/message","params":{"level":"info","logger":"export_tickets","data":{"message":"Exporting 5 tickets to tickets.csv"}}}

event: message
data: {"jsonrpc":"2.0","method":"notifications/progress","params":{"progressToken":"progress-1","progress":1,"total":5,"message":"Exported T-1"}}

…

event: message
data: {"jsonrpc":"2.0","id":6,"result":{"content":[…],"structuredContent":{"file":"tickets.csv","rows":5}}}

The Wire tab labels this response SSE and shows each event before the final response. When the call ends, the stream ends with it.

A client in your own code asks the same way. One made with connect() passes { onProgress } as callTool()'s third argument, which sends a progress token with that call, and gets each update: see this.progress(). (Changed in 1.9.3: before, a connect() client had no way to ask.)

When the client doesn't ask

Not every client asks for notifications, and a client that asks for some calls may not ask for others. A tool has to work either way. This version puts what progress() returned into the result, so you can see it:

import { Tool, ToolContext } from "@frontmcp/sdk";
import { exportRow, tickets } from "./store";

@Tool({
  name: "export_tickets",
  description: "Export every support ticket to tickets.csv. Takes a few seconds.",
  inputSchema: {},
})
export class ExportTickets extends ToolContext {
  async execute() {
    let reported = false;
    for (const [i, ticket] of tickets.entries()) {
      await exportRow(ticket);
      reported = await this.progress(i + 1, tickets.length, `Exported ${ticket.id}`);
    }
    // Only here to show what progress() returned.
    return { file: "tickets.csv", rows: tickets.length, progressReported: reported };
  }
}

The first call asked for progress, so progressReported is true. Untick Stream progress & logs and call again: the response is plain JSON, with no notifications, and progressReported is false. The export itself is the same.

progress() and notify() return true when the notification was queued for the client, and false when the client didn't ask for it (or, for notify(), asked only for higher levels). They never throw for that reason, so you don't need to check before calling them. The test file does the same thing from code: mcp.raw.request() sends a request exactly as you write it, without a progressToken.

Testing progress and logs

The test client records the notifications that come back. mcp.notifications.collectProgress().all lists the progress updates, and mcp.notifications.collect().received lists every notification, logs included. In the Playground, each mcp.tools.call() asks for progress and for every log level, debug included:

import { test, expect } from "@frontmcp/testing";

test("reports progress once per ticket", async ({ mcp }) => {
  const progress = mcp.notifications.collectProgress();
  const result = await mcp.tools.call("export_tickets", {});

  expect(result).toBeSuccessful();
  expect(progress.all.map((p) => p.progress)).toEqual([1, 2, 3, 4, 5]);
  expect(progress.all.every((p) => p.total === 5)).toBe(true);
});

type LogMessage = { level: string; logger?: string; data: { message?: string } };

test("warns about the ticket with no title", async ({ mcp }) => {
  const notifications = mcp.notifications.collect();
  await mcp.tools.call("export_tickets", {});

  const warnings = notifications.received
    .filter((n) => n.method === "notifications/message")
    .map((n) => n.params as LogMessage)
    .filter((log) => log.level === "warning");
  expect(warnings).toHaveLength(1);
  expect(warnings[0].data.message).toContain("T-2");
});

Recap

Try some challenges

Each challenge runs hidden checks against your code. Edit the code, then press Check.

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

const imported: { id: string; title: string }[] = [];

@Tool({
  name: "import_tickets",
  description: "Import tickets from the old help desk. Takes about a second per 5 tickets.",
  inputSchema: {
    tickets: z.array(z.object({ id: z.string(), title: z.string() })).min(1).max(20),
  },
})
export class ImportTickets extends ToolContext {
  async execute({ tickets }: { tickets: { id: string; title: string }[] }) {
    for (const ticket of tickets) {
      await new Promise((resolve) => setTimeout(resolve, 100));
      imported.push(ticket);
    }
    return { imported: tickets.length };
  }
}