Problem

Workflow runs using the Copilot CLI engine were experiencing MCP server loading issues with insufficient diagnostic information to determine the root cause. When MCP servers failed to load or initialize, there was no way to see detailed connection attempts, server spawn logs, or communication errors.

Solution

This PR enables maximum logging for MCP servers in Copilot CLI workflows by adding debug environment variables and creating dedicated log directories. These changes provide comprehensive diagnostic capabilities without affecting workflow behavior.

Changes Made

1. Added Debug Environment Variables

Two new environment variables are now automatically set for all Copilot engine workflows:

• DEBUG="*" - Enables verbose debug logging for all Node.js-based MCP servers, showing connection attempts, server spawning, and inter-process communication
• XDG_STATE_HOME=/tmp/gh-aw/.copilot/state - Provides a dedicated directory for MCP server state and log files

2. Created MCP Logs Directory

Modified the MCP configuration rendering to create /tmp/gh-aw/mcp-logs directory, providing a centralized location for MCP server-specific logs.

3. Verified Output Paths

Confirmed that Copilot CLI output correctly flows to agent-stdio.log via the tee command, while detailed debug logs go to /tmp/gh-aw/.copilot/logs/ via the --log-level all flag (already configured).

Logging Output Locations

With these changes, MCP-related logs are now available in multiple locations for comprehensive debugging:

1. /tmp/gh-aw/agent-stdio.log - Main stdout/stderr from Copilot CLI (via tee)
2. /tmp/gh-aw/.copilot/logs/ - Copilot CLI debug logs (via --log-dir flag)
3. /tmp/gh-aw/.copilot/state/ - MCP server state and logs (via XDG_STATE_HOME)
4. /tmp/gh-aw/mcp-logs/ - Additional MCP server logs (via mkdir)
5. Console debug output - All MCP server debug info (via DEBUG="*")

All these directories are collected as workflow artifacts and can be downloaded for analysis when investigating MCP server issues.

Example Impact

Before this change, a workflow with MCP servers would have minimal logging:

env:
  COPILOT_AGENT_RUNNER_TYPE: STANDALONE
  GITHUB_TOKEN: ${{ secrets.COPILOT_CLI_TOKEN }}
  XDG_CONFIG_HOME: /home/runner

After this change, comprehensive logging is enabled:

env:
  COPILOT_AGENT_RUNNER_TYPE: STANDALONE
  DEBUG: "*"                                    # NEW: Enable verbose debug logs
  GITHUB_TOKEN: ${{ secrets.COPILOT_CLI_TOKEN }}
  XDG_CONFIG_HOME: /home/runner
  XDG_STATE_HOME: /tmp/gh-aw/.copilot/state    # NEW: MCP state/log directory

Testing

• ✅ Added comprehensive tests for new environment variables
• ✅ Added test for MCP logs directory creation
• ✅ All existing tests continue to pass
• ✅ All 64 workflows recompile successfully
• ✅ Code formatted and passed automated code review

Benefits

When investigating MCP server issues like the one in run 18418361861, developers can now:

• See detailed MCP server connection logs
• Diagnose server spawn failures
• View inter-process communication errors
• Analyze server initialization problems
• Debug configuration issues

This comprehensive logging enables faster diagnosis and resolution of MCP-related workflow failures.

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.