Skip to content

Troubleshooting

Common problems and fixes. If none of these help, enable verbose logging and open a GitHub issue with the details.

Tools do not appear in the client

  • Confirm MCP is enabled in the client (in VS Code: settings -> MCP -> enable in Copilot Chat) and restart it.
  • Check that the config file is valid JSON and in the right place, see Client configuration.
  • In VS Code, check Output -> Model Context Protocol for startup errors.

  • Verify the server runs at all:

    python -m mcp_windbg --help

CDB not found

The server auto-detects cdb.exe, but cannot if it is installed somewhere unusual.

  • Confirm it is reachable: cdb.exe -version.
  • Install Debugging Tools for Windows (WinDbg from the Microsoft Store, or the Windows SDK).

  • Point the server at it explicitly with --cdb-path:

    "args": ["--from", "git+https://github.com/svnscha/mcp-windbg", "mcp-windbg",
         "--cdb-path", "C:\\Program Files (x86)\\Windows Kits\\10\\Debuggers\\x64\\cdb.exe"]

Symbols do not load

Stack traces full of offsets and no function names mean symbols are not resolving.

  • Set _NT_SYMBOL_PATH in the client env, see Getting started:

    "env": {"_NT_SYMBOL_PATH": "SRV*C:\\Symbols*https://msdl.microsoft.com/download/symbols"}

  • For your own binaries, keep the matching .pdb next to the dump (the dump's directory is added automatically) or pass an extra path, see Symbols and CDB.

  • Confirm the machine can reach https://msdl.microsoft.com.

Command timeouts

A command that exceeds the per-command limit reports a timeout.

  • Raise it with --timeout, for example --timeout 120.
  • On large dumps, prefer targeted commands over broad analysis.
  • The timeout error includes the output read before CDB stopped responding. If the command produces more than the diagnostic limit, the response ends with a truncation note; increase the timeout or inspect the target directly for the complete output.

Module not found (pip installs)

No module named 'mcp_windbg' from a pip-based config:

  • Verify the install: pip list | findstr mcp-windbg.
  • For a virtual environment, point command at that interpreter, for example ${workspaceFolder}/.venv/Scripts/python.

Remote debugging issues

Cannot connect to a remote target:

  • Use a supported connection string format, for example tcp:Port=5005,Server=192.168.0.100.
  • Check network reachability to the target and that the debugging server is listening.
  • Check the target's firewall.
  • Timed out connecting to the debug server means the client reached neither the server nor an error within the timeout, which points at the network rather than the target. A refused connection fails fast with DebugConnect failed, and a target that is merely running is not a connect failure: the open breaks into it.
  • open_cdb_remote is user-mode only (-remote). For kernel targets (-k) use open_kd_session, see Debug a kernel target. A kernel connect that times out with no_debuggee means the target isn't transmitting or another debugger already holds the (point-to-point) connection.

HTTP transport will not connect

Using the streamable-http transport and the client cannot reach the server:

  • The endpoint includes the /mcp path, for example http://host:8000/mcp.
  • The server binds 127.0.0.1 by default. To reach it from another machine, start it with --host 0.0.0.0 and open the port in the host firewall.
  • There is no authentication, so keep it on localhost or a trusted network, see Debug from another machine.

Filter script stops the server from starting

A --filter-script that fails to load:

  • The script must define process_input and/or process_output; a file with neither is rejected. Check the path and that the file is valid Python.
  • Startup errors appear in the client's MCP output (in VS Code, Output -> Model Context Protocol).
  • A hook that raises at runtime is reported as a tool error, not a crash; check its logic.

Server crashes when run directly in a terminal

mcp-windbg speaks MCP over stdin/stdout; it is meant to be launched by a client, not typed into interactively. Run it through your MCP client, or with --help to see options.

Diagnostics

Enable verbose logging (goes to stderr, safe under stdio):

"args": ["--from", "git+https://github.com/svnscha/mcp-windbg", "mcp-windbg", "--verbose"]

Check the basics:

cdb.exe -version
python -m mcp_windbg --help