Logging

FastMCP provides flexible logging options, allowing you to customize how your server logs messages and integrate with existing logging infrastructure.

Custom Logger

Provide a custom logger implementation to control how the server logs messages:

import { FastMCP, Logger } from "fastmcp";

class CustomLogger implements Logger {
  debug(...args: unknown[]): void {
    console.log("[DEBUG]", new Date().toISOString(), ...args);
  }

  error(...args: unknown[]): void {
    console.error("[ERROR]", new Date().toISOString(), ...args);
  }

  info(...args: unknown[]): void {
    console.info("[INFO]", new Date().toISOString(), ...args);
  }

  log(...args: unknown[]): void {
    console.log("[LOG]", new Date().toISOString(), ...args);
  }

  warn(...args: unknown[]): void {
    console.warn("[WARN]", new Date().toISOString(), ...args);
  }
}

const server = new FastMCP({
  name: "My Server",
  version: "1.0.0",
  logger: new CustomLogger(),
});

Logger Interface

The Logger interface requires five methods:

interface Logger {
  debug(...args: unknown[]): void;
  error(...args: unknown[]): void;
  info(...args: unknown[]): void;
  log(...args: unknown[]): void;
  warn(...args: unknown[]): void;
}

Logging in Tools

Tools can log messages to the client using the log object in the context:

import { FastMCP } from "fastmcp";
import { z } from "zod";

const server = new FastMCP({
  name: "My Server",
  version: "1.0.0",
});

server.addTool({
  name: "download",
  description: "Download a file",
  parameters: z.object({
    url: z.string(),
  }),
  execute: async (args, { log }) => {
    log.info("Downloading file...", {
      url: args.url,
    });

    // Download logic here...

    log.info("Downloaded file");

    return "done";
  },
});

Log Methods

The log object provides four methods:

Method	Description	Use Case
`debug(message, data?)`	Debug-level logging	Detailed diagnostic information
`error(message, data?)`	Error-level logging	Error conditions
`info(message, data?)`	Info-level logging	General informational messages
`warn(message, data?)`	Warning-level logging	Warning conditions

All methods accept:

message: string - The log message
data?: SerializableValue - Optional structured data

Integration Examples

Winston
Pino
File-based
Simple Custom

import winston from 'winston';
import { FastMCP, Logger } from 'fastmcp';

class WinstonLoggerAdapter implements Logger {
  private winston: winston.Logger;

  constructor() {
    this.winston = winston.createLogger({
      level: 'debug',
      format: winston.format.combine(
        winston.format.timestamp(),
        winston.format.errors({ stack: true }),
        winston.format.json()
      ),
      transports: [
        new winston.transports.Console({
          format: winston.format.combine(
            winston.format.colorize(),
            winston.format.simple()
          )
        }),
        new winston.transports.File({ filename: 'fastmcp.log' })
      ]
    });
  }

  debug(...args: unknown[]): void {
    this.winston.debug(this.formatArgs(args));
  }

  error(...args: unknown[]): void {
    this.winston.error(this.formatArgs(args));
  }

  info(...args: unknown[]): void {
    this.winston.info(this.formatArgs(args));
  }

  log(...args: unknown[]): void {
    this.winston.info(this.formatArgs(args));
  }

  warn(...args: unknown[]): void {
    this.winston.warn(this.formatArgs(args));
  }

  private formatArgs(args: unknown[]): string {
    return args.map(arg =>
      typeof arg === 'object' ? JSON.stringify(arg) : String(arg)
    ).join(' ');
  }
}

const server = new FastMCP({
  name: "My Server",
  version: "1.0.0",
  logger: new WinstonLoggerAdapter(),
});

import pino from 'pino';
import { FastMCP, Logger } from 'fastmcp';

class PinoLoggerAdapter implements Logger {
  private pino: pino.Logger;

  constructor() {
    this.pino = pino({
      level: 'debug',
      transport: {
        target: 'pino-pretty',
        options: {
          colorize: true,
          translateTime: 'SYS:standard',
          ignore: 'pid,hostname'
        }
      }
    });
  }

  debug(...args: unknown[]): void {
    this.pino.debug(this.formatMessage(args));
  }

  error(...args: unknown[]): void {
    this.pino.error(this.formatMessage(args));
  }

  info(...args: unknown[]): void {
    this.pino.info(this.formatMessage(args));
  }

  log(...args: unknown[]): void {
    this.pino.info(this.formatMessage(args));
  }

  warn(...args: unknown[]): void {
    this.pino.warn(this.formatMessage(args));
  }

  private formatMessage(args: unknown[]): string {
    return args.map(arg =>
      typeof arg === 'object' ? JSON.stringify(arg) : String(arg)
    ).join(' ');
  }
}

const server = new FastMCP({
  name: "My Server",
  version: "1.0.0",
  logger: new PinoLoggerAdapter(),
});

import * as fs from 'fs';
import { FastMCP, Logger } from 'fastmcp';

class FileLogger implements Logger {
  private logFile: string;

  constructor(logFile: string) {
    this.logFile = logFile;
  }

  debug(...args: unknown[]): void {
    this.logToFile('DEBUG', ...args);
  }

  error(...args: unknown[]): void {
    this.logToFile('ERROR', ...args);
  }

  info(...args: unknown[]): void {
    this.logToFile('INFO', ...args);
  }

  log(...args: unknown[]): void {
    this.logToFile('LOG', ...args);
  }

  warn(...args: unknown[]): void {
    this.logToFile('WARN', ...args);
  }

  private logToFile(level: string, ...args: unknown[]): void {
    const timestamp = new Date().toISOString();
    const message = `[${timestamp}] [${level}] ${args.map(arg =>
      typeof arg === 'object' ? JSON.stringify(arg) : String(arg)
    ).join(' ')}\n`;

    fs.appendFileSync(this.logFile, message);
  }
}

const server = new FastMCP({
  name: "My Server",
  version: "1.0.0",
  logger: new FileLogger('/var/log/fastmcp.log'),
});

import { FastMCP, Logger } from 'fastmcp';

class SimpleCustomLogger implements Logger {
  debug(...args: unknown[]): void {
    console.log('[CUSTOM DEBUG]', new Date().toISOString(), ...args);
  }

  error(...args: unknown[]): void {
    console.error('[CUSTOM ERROR]', new Date().toISOString(), ...args);
  }

  info(...args: unknown[]): void {
    console.info('[CUSTOM INFO]', new Date().toISOString(), ...args);
  }

  log(...args: unknown[]): void {
    console.log('[CUSTOM LOG]', new Date().toISOString(), ...args);
  }

  warn(...args: unknown[]): void {
    console.warn('[CUSTOM WARN]', new Date().toISOString(), ...args);
  }
}

const server = new FastMCP({
  name: "My Server",
  version: "1.0.0",
  logger: new SimpleCustomLogger(),
});

Real-World Example

Here’s a complete example from the FastMCP repository showing custom logging:

src/examples/custom-logger.ts

import { z } from "zod";
import { FastMCP, Logger } from "../FastMCP.js";

// Simple Custom Logger Implementation
class SimpleCustomLogger implements Logger {
  debug(...args: unknown[]): void {
    console.log("[CUSTOM DEBUG]", new Date().toISOString(), ...args);
  }

  error(...args: unknown[]): void {
    console.error("[CUSTOM ERROR]", new Date().toISOString(), ...args);
  }

  info(...args: unknown[]): void {
    console.info("[CUSTOM INFO]", new Date().toISOString(), ...args);
  }

  log(...args: unknown[]): void {
    console.log("[CUSTOM LOG]", new Date().toISOString(), ...args);
  }

  warn(...args: unknown[]): void {
    console.warn("[CUSTOM WARN]", new Date().toISOString(), ...args);
  }
}

const logger = new SimpleCustomLogger();

const server = new FastMCP({
  logger: logger,
  name: "custom-logger-example",
  version: "1.0.0",
});

server.addTool({
  description: "A test tool that demonstrates custom logging",
  execute: async (args) => {
    return `Received: ${args.message}`;
  },
  name: "test_tool",
  parameters: z.object({
    message: z.string().describe("A message to log"),
  }),
});

server.start({ transportType: "stdio" });

Structured Logging

Log structured data alongside messages:

server.addTool({
  name: "processOrder",
  description: "Process an order",
  parameters: z.object({
    orderId: z.string(),
    items: z.array(z.string()),
  }),
  execute: async ({ orderId, items }, { log }) => {
    log.info("Processing order", {
      orderId,
      itemCount: items.length,
      timestamp: new Date().toISOString(),
    });

    try {
      // Process order...
      log.info("Order processed successfully", { orderId });
    } catch (error) {
      log.error("Order processing failed", {
        orderId,
        error: error.message,
      });
      throw error;
    }

    return "Order processed";
  },
});

Best Practices

Use Appropriate Log Levels

debug: Detailed diagnostic information
info: General informational messages
warn: Warning conditions
error: Error conditions

Include Context in Logs

Always log relevant context data:

log.info("Processing file", {
  filename: file.name,
  size: file.size,
  userId: session.userId,
});

Log at Key Points

Log at important stages:

Start of operations
Completion of operations
Error conditions
State changes

Avoid Logging Sensitive Data

Never log:

Passwords
API keys
Personal information (unless necessary and compliant)
Credit card numbers

Use Structured Logging

Prefer structured data over string concatenation:

// Good
log.info("User login", { userId, timestamp });

// Avoid
log.info(`User ${userId} logged in at ${timestamp}`);

Production Considerations

Log Rotation

For file-based logging, implement log rotation:

import * as fs from 'fs';
import * as path from 'path';

class RotatingFileLogger implements Logger {
  private logFile: string;
  private maxSize: number = 10 * 1024 * 1024; // 10MB
  private maxFiles: number = 5;

  constructor(logFile: string) {
    this.logFile = logFile;
  }

  private rotateIfNeeded(): void {
    if (!fs.existsSync(this.logFile)) return;

    const stats = fs.statSync(this.logFile);
    if (stats.size < this.maxSize) return;

    // Rotate logs
    for (let i = this.maxFiles - 1; i >= 0; i--) {
      const oldFile = `${this.logFile}.${i}`;
      const newFile = `${this.logFile}.${i + 1}`;
      if (fs.existsSync(oldFile)) {
        fs.renameSync(oldFile, newFile);
      }
    }

    fs.renameSync(this.logFile, `${this.logFile}.0`);
  }

  private logToFile(level: string, ...args: unknown[]): void {
    this.rotateIfNeeded();

    const timestamp = new Date().toISOString();
    const message = `[${timestamp}] [${level}] ${args.map(arg =>
      typeof arg === 'object' ? JSON.stringify(arg) : String(arg)
    ).join(' ')}\n`;

    fs.appendFileSync(this.logFile, message);
  }

  debug(...args: unknown[]): void {
    this.logToFile('DEBUG', ...args);
  }

  error(...args: unknown[]): void {
    this.logToFile('ERROR', ...args);
  }

  info(...args: unknown[]): void {
    this.logToFile('INFO', ...args);
  }

  log(...args: unknown[]): void {
    this.logToFile('LOG', ...args);
  }

  warn(...args: unknown[]): void {
    this.logToFile('WARN', ...args);
  }
}

Performance Monitoring

Log performance metrics:

server.addTool({
  name: "expensiveOperation",
  execute: async (args, { log }) => {
    const startTime = Date.now();

    log.info("Starting expensive operation", { args });

    try {
      // Do work...
      const result = await doWork();

      const duration = Date.now() - startTime;
      log.info("Operation completed", {
        duration,
        success: true,
      });

      return result;
    } catch (error) {
      const duration = Date.now() - startTime;
      log.error("Operation failed", {
        duration,
        error: error.message,
      });
      throw error;
    }
  },
});

Get Started

Core Concepts

Features

Guides

Deployment

Custom Logger

Logger Interface

Logging in Tools

Log Methods

Integration Examples

Real-World Example

Structured Logging

Best Practices

Production Considerations

Log Rotation

Performance Monitoring

Next Steps

Streaming

Authentication

Build docs developers (and LLMs) love

Get Started

Core Concepts

Features

Guides

Deployment

​Custom Logger

​Logger Interface

​Logging in Tools

​Log Methods

​Integration Examples

​Real-World Example

​Structured Logging

​Best Practices

​Production Considerations

​Log Rotation

​Performance Monitoring

​Next Steps

Streaming

Authentication

Build docs developers (and LLMs) love

Custom Logger

Logger Interface

Logging in Tools

Log Methods

Integration Examples

Real-World Example

Structured Logging

Best Practices

Production Considerations

Log Rotation

Performance Monitoring

Next Steps