Edit

Troubleshoot WinDbg MCP setup and connection issues

Use this article when Visual Studio Code with GitHub Copilot or GitHub Copilot CLI can't register the WinDbg Model Context Protocol (MCP) server, can't connect to a WinDbg MCP session, or WinDbg MCP security controls block an operation. Registering adds the WinDbg MCP server to the AI client's configuration, while connecting associates the client with a specific WinDbg session.

For setup instructions, see Install and enable WinDbg MCP. For authoritative security and privacy guidance, see WinDbg MCP security and privacy considerations.

Start with the symptom that you observe, identify the likely cause, and complete the resolution steps.

Troubleshooting checklist

For MCP server registration issues:

  1. Open WinDbg. You don't need to load or attach to a debugging target to use Enable Server or Install MCP.
  2. Open MCP service settings, and confirm that you selected Enable Server.
  3. Confirm that you selected Visual Studio Code or GitHub Copilot CLI as the client.

For connection or session issues:

  1. Start MCP Service in the intended WinDbg window.
  2. If you're analyzing a target, load or attach to the debugging target as needed.

The MCP server list doesn't include WinDbg

The supported AI client's MCP server list doesn't include WinDbg.

Cause

Install MCP didn't register WinDbg with the client, or the client hasn't reloaded its MCP server configuration.

Resolution

  1. Restart the AI client, and then check its MCP server list.
  2. In WinDbg, open MCP service settings and select the correct supported client.
  3. Select Install MCP again.
  4. Complete any confirmation that the client displays.
  5. Restart the client, and then check its MCP server list again.

If WinDbg is still missing because Install MCP fails, register WinDbg manually.

Register a supported client manually

Use this fallback only when Install MCP doesn't register WinDbg with Visual Studio Code or GitHub Copilot CLI.

  1. In WinDbg, open MCP service settings.
  2. Select Custom to display the proxy configuration. Selecting Custom in this step only provides the proxy command for the supported-client configuration.
  3. Select Copy to Clipboard, and note the command path that WinDbg copies to the clipboard.

Configure the supported client:

  1. In your workspace, add the WinDbg server to .vscode/mcp.json. Replace the example command value with the path from the clipboard:

    {
  "servers": {
    "WinDbg": {
      "type": "stdio",
      "command": "C:\\path\\to\\DbgX.Mcp.Proxy.exe",
      "args": []
    }
  }
}

  2. Restart Visual Studio Code.

After the client restarts, see Verify the WinDbg MCP connection.

GitHub Copilot can't find the intended WinDbg session

Visual Studio Code with GitHub Copilot and GitHub Copilot CLI can't find the WinDbg session that contains the intended debugging target.

Cause

MCP Service isn't running in the intended WinDbg window, or more than one WinDbg session is available and the proxy can't select a session automatically.

Resolution

  1. In the intended WinDbg window, select MCP Service.
  2. Ask the AI client to use list_sessions.
  3. Identify the process ID for the intended WinDbg session.
  4. Ask the AI client to use connect_session with that process ID.
  5. Confirm that the target type and execution state that the client reports match those in the intended WinDbg window.

For more session-selection guidance, see Manage WinDbg sessions.

WinDbg session is unavailable because another client is connected

The intended WinDbg session appears unavailable when the AI client lists sessions or tries to connect.

Cause

Another AI client has an active connection to the WinDbg session. Only one active MCP client can connect to a WinDbg session at a time.

Resolution

  1. In the connected AI client, ask the client to use disconnect_session.
  2. Confirm that the client reports that it disconnected from the WinDbg session.
  3. In the intended AI client, ask the client to use list_sessions.
  4. Ask the intended client to use connect_session with the WinDbg session's process ID.
  5. Confirm that the client reports a connection to the intended session.

Access denied when WinDbg is elevated

The connection fails with an Access denied message when WinDbg is running as an administrator.

Cause

The elevated WinDbg session prevents the supported AI client from connecting through the proxy.

Resolution

  1. Close the elevated WinDbg session.
  2. Start WinDbg without selecting Run as administrator.
  3. Start MCP Service.
  4. Load or attach to the debugging target as needed.
  5. Open the supported AI client, and complete the steps in Verify the WinDbg MCP connection.

Prompt-injection protection blocks an operation

The AI client reports that prompt-injection protection blocked an operation or classified debugger output as unsafe.

Cause

WinDbg cross-prompt injection attack (XPIA) protection identified the debugger output as potentially unsafe and blocked the output.

Resolution

  1. Follow the error information that the AI client reports.
  2. Review the relevant output directly in WinDbg.
  3. Treat the output as untrusted, and don't send the blocked output to the AI client.
  4. Review Cross-prompt injection protection before you decide how to continue.

Prompt-injection classification can't run because the AI client doesn't support or permit MCP sampling

The AI client reports that prompt-injection classification can't run, and the protected operation fails without returning output.

Cause

The AI client doesn't support MCP sampling, or its configuration or organizational policy doesn't permit MCP sampling. WinDbg XPIA protection requires MCP sampling to request classification from the client's configured model service.

Resolution

  1. Confirm that the AI client supports MCP sampling.
  2. Confirm that the client configuration and your organizational policy permit MCP sampling.
  3. After sampling is available, run the operation again.
  4. If classification still can't run, review Cross-prompt injection protection and contact the administrator who manages the AI client's policy.

Verify the WinDbg MCP connection and report unresolved issues

  • Last updated on