MetaMCP Logging Levels: How to Configure Debug Output for Development and Production

MetaMCP supports four logging levels—DEBUG, INFO, WARN, and ERROR—and you can configure which levels appear in the console by setting the LOG_LEVEL environment variable to all, info, errors-only, or none.

MetaMCP (metatool-ai/metamcp) implements a dual-target logging architecture that persists all messages to files while allowing flexible console mirroring for real-time monitoring. Understanding how to configure MetaMCP logging levels is essential for troubleshooting development issues and controlling noise in production environments.

Understanding the Dual-File Logging Architecture

The MetaMCP backend writes logs to two distinct files based on severity. According to the implementation in apps/backend/src/utils/logger.ts, the system separates standard operational logs from critical errors:

• app.log: Receives DEBUG, INFO, and WARN messages
• error.log: Receives only ERROR level messages

This separation ensures high-severity events remain isolated and easily accessible without being buried in verbose debug output, regardless of your console configuration.

Configuring Console Output with LOG_LEVEL

While log files capture everything by default, console output is controlled exclusively through the LOG_LEVEL environment variable. The getValidLogLevel function in apps/backend/src/utils/logger.ts validates this variable against the supported enumeration.

The following values determine console mirroring behavior:

LOG_LEVEL value	Console output
all	Mirrors DEBUG, INFO, WARN, and ERROR (full set)
info	Mirrors only INFO messages
errors-only	Mirrors WARN and ERROR
none	Suppresses all console output
(unset)	Defaults to all (full mirroring)

To enable detailed debugging output, set LOG_LEVEL=all. For production deployments requiring quieter consoles, use info or errors-only.

Practical Configuration Examples

Local Development with Full Debugging

Run the following in your terminal before starting the stack to see all logging levels in real time:

export LOG_LEVEL=all   # Mirrors DEBUG, INFO, WARN, ERROR to console

pnpm dev               # Start the development stack

Docker Compose Configuration

In docker-compose.dev.yml, inject the variable with a default fallback to ensure consistent behavior across environments:

services:
  backend:
    image: metamcp/backend:dev
    environment:
      LOG_LEVEL: ${LOG_LEVEL:-all}   # Defaults to "all" if not set

Production Configuration

For quieter production consoles that only surface informational messages, modify your production docker-compose.yml:

services:
  backend:
    environment:
      LOG_LEVEL: info   # Only INFO messages appear on the console

Accessing Log Files Directly

When console output is insufficient or disabled, inspect the persistent log files directly:

# View the application log (includes DEBUG, INFO, WARN)

tail -f logs/app.log

# View the error log (only ERROR)

tail -f logs/error.log

Programmatic Log Level Access

You can access the validation logic directly within your application code. The getValidLogLevel utility in apps/backend/src/utils/logger.ts ensures type safety and handles invalid inputs:

import { getValidLogLevel } from './utils/logger';

const consoleLevel = getValidLogLevel(process.env.LOG_LEVEL);
if (consoleLevel === 'all') {
  console.debug('Verbose debugging enabled');
}

Summary

• MetaMCP recognizes four logging levels: DEBUG, INFO, WARN, and ERROR.
• Logs are persistently written to app.log (DEBUG/INFO/WARN) and error.log (ERROR) independent of console settings.
• The LOG_LEVEL environment variable controls console mirroring with supported values: all, info, errors-only, or none.
• The default behavior mirrors all levels (all) when LOG_LEVEL is unset or invalid.
• Validation logic resides in apps/backend/src/utils/logger.ts.

Frequently Asked Questions

What logging levels are available in MetaMCP?

MetaMCP supports four standard logging levels: DEBUG, INFO, WARN, and ERROR. These levels are routed to files based on severity, with DEBUG, INFO, and WARN directed to app.log while ERROR is isolated to error.log for immediate attention.

How do I enable debug logging in MetaMCP?

Set the environment variable LOG_LEVEL=all before starting the application. This configuration mirrors DEBUG, INFO, WARN, and ERROR messages to the console. In Docker deployments, define this in your .env file or directly in the docker-compose.dev.yml environment section.

Where are MetaMCP logs stored?

Logs are stored in two files within the application directory: logs/app.log contains DEBUG, INFO, and WARN messages, while logs/error.log contains only ERROR level entries. These files accumulate all logged events regardless of the LOG_LEVEL console setting.

What happens if I set an invalid LOG_LEVEL value?

If you provide an unrecognized value, the getValidLogLevel function in apps/backend/src/utils/logger.ts automatically falls back to the default value of all. This fail-safe ensures you receive full console output rather than experiencing silent failures or missing critical log messages.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}