Skip to main content

​
Overview

MCPcat can write detailed logs to ~/mcpcat.log to help you troubleshoot integration issues. Debug mode is off by default and needs to be enabled in your tracking configuration. The log file includes information about event batching, session management, telemetry delivery, and any errors the SDK encounters.

​
Enabling Debug Mode

Pass the debug option when calling mcpcat.track(): 
import * as mcpcat from "mcpcat"

mcpcat.track(mcpServer, "proj_abc123xyz", {
  debug: true
})

​
Environment Variable

You can also enable debug mode with an environment variable instead of changing your code: 
MCPCAT_DEBUG_MODE=true
This accepts true, 1, yes, or on (case-insensitive).

​
Reading the Log File

Logs are written to ~/mcpcat.log. You can tail the file while your server is running to see output in real time: 
tail -f ~/mcpcat.log

​
When to Use Debug Mode

Debug mode is useful when:
  • Events aren’t showing up in the MCPcat dashboard
  • You want to verify that tracking is set up correctly
  • You need to confirm that user identification is working
  • You’re troubleshooting exporter or telemetry delivery issues
Debug mode is meant for development and troubleshooting. In production, leave it off to avoid unnecessary disk writes.