Logging

Copy Markdown View Source

FastestMCP exposes two distinct logging planes:

  1. server-side request logging through middleware
  2. protocol log notifications emitted from handlers through the request context

Keeping those separate matters. Request logging is about observing runtime behavior. Handler log notifications are about sending structured messages to the connected client that is actively participating in the session.

Request Logging Middleware

Use request logging middleware when you want server-side observability for all operations.

server =
  FastestMCP.server("logging")
  |> FastestMCP.add_middleware(
    FastestMCP.Middleware.logging(
      include_payload_length: true,
      structured_logging: true
    )
  )

The built-in logging middleware can:

  • log before and after execution
  • include method and duration
  • include serialized payloads
  • include payload length or rough token count
  • emit structured JSON or plain text
  • restrict logging to specific MCP methods

Use this when you need runtime traces in application logs.

Handler Log Notifications

Use FastestMCP.Context.log/4 when a handler wants to emit a protocol message to the current client session:

alias FastestMCP.Context

server =
  FastestMCP.server("logging")
  |> FastestMCP.add_tool("work", fn _arguments, ctx ->
    Context.log(ctx, :info, "Tool execution started")
    Context.log(ctx, :notice, "Fetching data", logger: "docs")
    Context.log(ctx, :info, "Tool execution completed")
    %{status: "ok"}
  end)

These messages are session-aware. They are useful when the client is actively watching the operation and wants structured log notifications alongside progress, sampling, or elicitation callbacks.

Client-side Consumption

Connected clients can provide a log_handler:

client =
  FastestMCP.Client.connect!("http://127.0.0.1:4100/mcp",
    client_info: %{"name" => "docs-client", "version" => "1.0.0"},
    log_handler: &IO.inspect/1
  )

That handler receives protocol log notifications from the server while the session is connected.

Choosing The Right Plane

Use middleware logging when:

  • you want consistent request-level runtime logs
  • you care about timings, payloads, and errors
  • the logs belong in your application's log pipeline

Use Context.log/4 when:

  • a handler wants to narrate work to the active client
  • the message is part of the session experience
  • you want client-side callbacks to see the event

It is normal to use both:

  • middleware for operations
  • context logs for user-visible or agent-visible status

Logging and Background Tasks

Handler log notifications can be emitted from background tasks too, as long as the session is still active and the client is listening.

That makes them a good fit for:

  • long-running workflows
  • task narration
  • step-by-step diagnostic output during interactive tool runs

Why This Shape

FastestMCP keeps application logs and protocol logs separate because they solve different problems.

Middleware logging is about server observability. Context.log/4 is about session-aware MCP notifications. Mixing those responsibilities usually produces confusing logs and weaker client behavior.