Logging

FastMCP writes its own diagnostic logs: lifecycle events, warnings, and errors from the framework itself. These are framework logs. They are separate from ctx.log, which sends MCP log notifications to the connected client. This page covers framework logs only.

Default output

FastMCP chooses a log format on its own. You do not need to configure it. When stderr is a terminal (a TTY) and the NO_COLOR environment variable is unset, FastMCP writes styled lines. Each line starts with a colored symbol that marks its level. On startup, FastMCP also prints a banner: the server name, version, transport, and, for HTTP, the URL it listens on. When stderr is not a terminal, or NO_COLOR is set, FastMCP writes plain lines instead. Each line has this form:

[fastmcp] LEVEL message {"meta":"json"}

LEVEL is one of DEBUG, INFO, WARN, or ERROR, in uppercase. The JSON object at the end is optional. It appears only when the log call carries metadata. All framework logs go to stderr. FastMCP never writes a framework log to stdout. On the stdio transport, stdout carries the protocol stream, so a framework log there would corrupt it.

Log level

Use logLevel to set the lowest severity FastMCP logs. There are five levels, from most to least verbose: debug, info, warn, error, and silent. Setting a level logs that level and every level after it. For example, warn logs warnings and errors, but not debug or info messages. silent logs nothing at all, including the startup banner and the listening line.

new FastMCP({ name: 'server', logLevel: 'debug' })

FastMCP resolves the level from three sources, checked in this order:

The logLevel option, if you set it.
The FASTMCP_LOG_LEVEL environment variable, if you set it. The value is case-insensitive.
info, the default, when neither is set.

The gate applies before FastMCP calls any logger, including a logger you inject. A log call below the configured level never reaches your logger. An invalid value throws an error at construction, when you call new FastMCP(...). This applies to both logLevel and FASTMCP_LOG_LEVEL. A misconfigured deployment fails immediately, instead of logging too much or too little in silence. The TypeScript type for this option is FrameworkLogLevel. It is a separate type from LogLevel, which is the eight-level type ctx.log uses. See Framework logs and client logging below.

Custom loggers

FastMCP does not require a specific logging library. The logger option accepts any object with four methods: debug, info, warn, and error. Each method takes a message string and an optional metadata object. console satisfies this shape directly.

// console satisfies the Logger interface directly
const server = new FastMCP({ name: 'server', logger: console })

Do not use logger: console with the stdio transport. console.info and console.debug write to stdout, and stdout carries the JSON-RPC protocol stream on stdio. This corrupts the protocol. Use a logger that writes every level to stderr instead, for example the Winston example below, which routes info and debug to stderr via stderrLevels. Winston also satisfies this shape directly. Winston’s info(message, meta) signature matches FastMCP’s.

// Winston: also direct; winston's info(message, meta) matches
import winston from 'winston'
const server = new FastMCP({ name: 'server', logger: winston.createLogger({ transports: [new winston.transports.Console({ stderrLevels: ['error', 'warn', 'info', 'debug'] })] }) })

Pino inverts the argument order: its methods take the metadata object first and the message second. Wrap it in a small adapter:

// Pino inverts the argument order, so wrap it:
import { pino } from 'pino'
const p = pino()
const server = new FastMCP({
  name: 'server',
  logger: {
    debug: (message, meta) => p.debug(meta ?? {}, message),
    info: (message, meta) => p.info(meta ?? {}, message),
    warn: (message, meta) => p.warn(meta ?? {}, message),
    error: (message, meta) => p.error(meta ?? {}, message),
  },
})

An injected logger receives clean input. FastMCP strips ANSI color codes and the [fastmcp] prefix before it calls your logger. The message is plain text, and the metadata is a structured object, not a formatted string. Most metadata objects carry a component field. This field names the part of the framework that produced the log, for example tool, http, cors, openapi, proxy, auth, context, or routes.

Framework logs and client logging

FastMCP has two separate logging systems. Do not confuse them.

	Framework logs (this page)	`ctx.log`
Audience	The operator running the server	The connected MCP client
Purpose	Diagnose the server itself: startup, shutdown, internal warnings and errors	Let a tool handler narrate its own work to the client
Levels	Five: `debug`, `info`, `warn`, `error`, `silent`	Eight (RFC 5424): `debug`, `info`, `notice`, `warning`, `error`, `critical`, `alert`, `emergency`
Destination	Your injected `logger`, or stderr by default	An MCP `notifications/message` sent to the client
Configured by	`FastMCPOptions.logger` and `FastMCPOptions.logLevel`	The client, which decides what to do with each notification

These two systems never mix. A framework log never reaches the client. A ctx.log call never reaches your injected logger. See context for ctx.log.

LoggingMiddleware

LoggingMiddleware logs every request: its method, its outcome, and how long it took. See middleware for the full middleware system.

import { FastMCP, LoggingMiddleware } from '@prefecthq/fastmcp-ts/server'

const server = new FastMCP({ name: 'my-server' })
server.use(new LoggingMiddleware())

LoggingMiddleware takes an optional emit function, and its behavior depends on whether you supply one. With no emit function, LoggingMiddleware writes through the framework logger. Its output goes to stderr, gated by logLevel like any other framework log. This is the default, and it changed in this release: earlier versions wrote to stdout through console.log. On the stdio transport, that corrupted the JSON-RPC protocol stream. If something in your setup reads LoggingMiddleware output from stdout, point it at stderr instead. With an explicit emit function, LoggingMiddleware calls it directly with a [fastmcp]-prefixed string. This keeps the previous format, and you control where the string goes.

Proxy servers

createProxy and buildProxyFromClient accept logger and logLevel options. FastMCP forwards them to the internal FastMCP instance that backs the proxy, so the proxy’s own lifecycle and warning logs (for example a failed capability probe against the upstream server) follow the same configuration as any other server.

Get Started

Concepts

Servers

Authentication

Advanced Servers

Apps

Clients

More

Default output

Log level

Custom loggers

Framework logs and client logging

LoggingMiddleware

Proxy servers

​Default output

​Log level

​Custom loggers

​Framework logs and client logging

​LoggingMiddleware

​Proxy servers

Default output

Log level

Custom loggers

Framework logs and client logging

LoggingMiddleware

Proxy servers