Skip to main content
mcp-use provides comprehensive logging for MCP servers, making it easy to understand server activity, debug issues, and monitor production deployments.

​
Log Levels

The server provides different logging levels through environment variables:

​
Production Mode (Default)

Clean, informative logs showing MCP operations: 
node server.js
Output: 
[MCP] Server mounted at /mcp (Streamable HTTP Transport)
[MCP] Session initialized: abc123
[MCP] tools/call:analyze-sentiment completed in 234ms
[MCP] Session closed: abc123

​
Debug Mode

Enable debug mode for development and troubleshooting: 
DEBUG=1 node server.js
Output: 
[MCP] Server initialized: my-server v1.0.0
[MCP] Registered tool: analyze-sentiment
[MCP] Registered resource: config://app-settings
[MCP] Session initialized: abc123
[MCP] tools/call:analyze-sentiment started
[MCP] tools/call:analyze-sentiment completed in 234ms

​
Verbose Debug Mode

Full request/response logging with JSON-RPC details: 
DEBUG=2 node server.js
Output: 
[MCP] Session initialized: abc123
[MCP] → Request: {
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "analyze-sentiment",
    "arguments": { "text": "I love this!" }
  }
}
[MCP] tools/call:analyze-sentiment completed in 234ms
[MCP] ← Response: {
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{ "type": "text", "text": "Sentiment: positive" }]
  }
}

​
Built-in Logging System

v1.12.0 Breaking Change: mcp-use replaced winston with a built-in SimpleConsoleLogger that works in both Node.js and browser environments. See the migration guide below.
The server uses a lightweight logging system that provides structured logs without external dependencies. This logger works seamlessly in both server and browser environments.

​
Logger Configuration API

Configure the logger programmatically using the Logger class: 
import { Logger } from "mcp-use/server";

// Configure logging level and format
Logger.configure({
  level: "debug", // Set log level
  format: "detailed", // Set output format
});

// Or set debug level using numeric values
Logger.setDebug(0); // Production mode (info level)
Logger.setDebug(1); // Debug mode (info level)
Logger.setDebug(2); // Verbose mode (debug level)

​
Log Levels

The logger supports seven log levels (from least to most verbose):
LevelUse Case
errorError conditions that need attention
warnWarning messages for potential issues
infoGeneral informational messages (default)
httpHTTP request/response logging
verboseVerbose informational messages
debugDetailed debugging information
sillyVery detailed debug information

​
Log Formats

Choose from three output formats:

​
Minimal Format (Default)

Clean, simple output with timestamp and level: 
14:23:45 [mcp-use] info: Server mounted at /mcp
14:23:46 [mcp-use] info: Session initialized: abc123

​
Detailed Format

More verbose output with full context: 
14:23:45 [mcp-use] INFO: Server mounted at /mcp (Streamable HTTP Transport)
14:23:46 [mcp-use] INFO: Session initialized: abc123

​
Using the Logger

Get a logger instance for custom logging: 
import { Logger } from "mcp-use/server";

const logger = Logger.get("my-component");

logger.info("Component initialized");
logger.debug("Processing request", { userId: 123 });
logger.error("Operation failed", new Error("Connection timeout"));

​
Browser Compatibility

The built-in logger works in both Node.js and browser environments without any configuration changes. This is a key improvement over the previous winston-based system, which was Node.js-only. 
// Same logger works everywhere
import { Logger } from "mcp-use/server";

// In Node.js
Logger.configure({ level: "debug", format: "detailed" });

// In browser (exact same API)
Logger.configure({ level: "info", format: "minimal" });

​
Migration from Winston

If you’re upgrading from mcp-use < v1.12.0, replace winston with the new Logger: Before (winston - removed in v1.12.0): 
import winston from "winston";

const logger = winston.createLogger({
  level: "info",
  transports: [new winston.transports.Console()],
});

logger.info("Server started");
After (SimpleConsoleLogger): 
import { Logger } from "mcp-use/server";

Logger.configure({
  level: "info",
  format: "minimal",
});

const logger = Logger.get();
logger.info("Server started");

​
Tool Logging with ctx.log

Tools can send log messages directly to clients during execution using ctx.log(). This allows real-time visibility into what your tool is doing, which is especially useful for long-running operations or debugging tool behavior. 
server.tool(
  {
    name: "process_data",
    description: "Process data with progress logging",
    schema: z.object({
      items: z.array(z.string()),
    }),
  },
  async ({ items }, ctx) => {
    // Log the start of processing
    await ctx.log("info", "Starting data processing");

    // Debug-level logging for detailed information
    await ctx.log("debug", `Processing ${items.length} items`, "my-tool");

    for (const item of items) {
      // Log warnings when needed
      if (!item.trim()) {
        await ctx.log("warning", "Empty item found, skipping");
        continue;
      }

      try {
        await processItem(item);
      } catch (err) {
        // Log errors without throwing
        await ctx.log("error", `Failed to process item: ${err.message}`);
      }
    }

    await ctx.log("info", "Processing completed");
    return text("All items processed");
  }
);

​
Log Levels

The ctx.log() function supports eight log levels, from least to most severe:
LevelUse Case
debugDetailed debugging information, verbose output
infoGeneral informational messages about progress
noticeNormal but significant events
warningWarning messages for recoverable issues
errorError messages for failures that don’t stop execution
criticalCritical conditions requiring immediate attention
alertAction must be taken immediately
emergencySystem is unusable

​
Parameters

ctx.log(level, message, logger?)
  • level (required): One of the eight log levels listed above
  • message (required): The log message content as a string
  • logger (optional): Logger name for categorization (defaults to 'tool')