LOG_OUTPUT=console Not Working with stdio Transport and Logs in Unreadable JSON Format on stderr&console

[ivan-gudak]

LOG_OUTPUT=console Not Working with stdio Transport and Logs in Unreadable JSON Format

Problem

When setting LOG_OUTPUT=console with LOG_LEVEL=debug in VS Code (stdio transport), debug logs were not visible in the Output panel. Additionally, when logs did appear on console outputs, they were in JSON format which was difficult to read.

Current Behavior (Before Fix)

1. LOG_OUTPUT=console with stdio transport: Logs disappeared completely

   • Users set LOG_OUTPUT=console and LOG_LEVEL=debug
   • Expected to see debug logs in VS Code Output panel
   • Only saw VS Code's own messages, no MCP server logs

2. Logs in JSON format: When logs did reach console (stderr or HTTP mode), they were unreadable:

   {"level":"info","message":"Starting Dynatrace Managed MCP","timestamp":"2026-02-05T14:02:01.467Z"}
   {"level":"debug","message":"Loading configuration from file: .ai/mcp/dt-config.yaml","timestamp":"2026-02-05T14:02:01.470Z"}

3. No guidance: Documentation didn't explain:

   • Why LOG_OUTPUT=console doesn't work with stdio transport
   • Which LOG_OUTPUT to use for stdio vs HTTP transport
   • No warning when using wrong configuration

Root Cause

With stdio transport (default for VS Code):

• stdout is reserved for MCP protocol messages - winston logs to stdout are consumed by the protocol parser and never displayed
• stderr is the only viable channel for human-readable logs
• Winston was configured to always output JSON format, which is hard to read for humans

Expected Behavior

1. Clear documentation on which LOG_OUTPUT works with which transport
2. Runtime warning when user sets incompatible LOG_OUTPUT configuration
3. Human-readable format for console/stderr output (save JSON for file output)

Solution

1. Add Human-Readable Console Format (src/utils/logger.ts)

• Detect when LOG_OUTPUT targets console/stderr
• Use readable format: 2026-02-05 14:02:01.467 [info] Starting Dynatrace Managed MCP
• Keep JSON format for file output (machine parsing)

2. Add Runtime Warning (src/index.ts)

When stdio transport detects LOG_OUTPUT=console/stdout/file+console/file+stdout:

WARNING: LOG_OUTPUT=console won't show logs in stdio transport. 
Stdout is reserved for MCP protocol. Use LOG_OUTPUT=stderr-all or LOG_OUTPUT=file instead.

3. Update Documentation (README.md)

• Document which LOG_OUTPUT works with stdio vs HTTP transport
• Provide clear examples for VS Code setup
• Add IMPORTANT callout box explaining stdout limitation
• Recommend LOG_OUTPUT=stderr-all for VS Code with stdio transport

Impact

• Severity: Medium - Users couldn't debug issues effectively
• Affected Users: Anyone using stdio transport (VS Code, Claude Desktop) trying to see debug logs
• Workaround (before fix): Use LOG_OUTPUT=file and tail the log file

Files Changed

• src/utils/logger.ts - Add human-readable format for console output
• src/index.ts - Add runtime warning for incompatible LOG_OUTPUT with stdio
• README.md - Document LOG_OUTPUT behavior with transport types

Testing

Verify the following scenarios:

Stdio transport (VS Code):

• ✅ LOG_OUTPUT=stderr-all LOG_LEVEL=debug - logs visible and readable in Output panel
• ✅ LOG_OUTPUT=file LOG_LEVEL=debug - logs written to file in JSON format
• ✅ LOG_OUTPUT=console - shows warning message to stderr

HTTP transport:

• ✅ LOG_OUTPUT=console LOG_LEVEL=debug - logs visible and readable in terminal
• ✅ LOG_OUTPUT=file LOG_LEVEL=debug - logs written to file in JSON format