DebugMCP: Giving MCP Agents Control of the VS Code Debugger

The gap DebugMCP fills: agents that reason about runtime state they cannot see

An agent asked to fix a failing function has two sources of truth available to it: the source text and whatever the program prints. Neither shows the value of a variable at the moment a branch was taken. The README frames the problem directly, contrasting its approach with assistants that end up "reading logs or guessing". DebugMCP's answer is to hand the agent the same instrument a human developer uses, the VS Code debugger, and expose it as MCP tools. The intended user is not a person clicking through a debug session. It is an agent runtime (the README names Codex, GitHub Copilot, Copilot CLI, Cline, Cursor, Windsurf and Roo Code) that needs to stop a program, look at state, and continue. The extension is maintained by two named Microsoft engineers, and the repository is TypeScript under MIT. Anyone expecting a standalone debugger should look elsewhere: this is a bridge, and the debugger it bridges to is the one already installed in VS Code.

How the tools map onto a debug session

The mechanism is a session lifecycle plus a set of state operations, all mediated by the VS Code debugger. A session begins with start_debugging, which takes a required fileFullPath and workingDirectory, plus optional testName and configurationName. From there the agent has the usual navigation verbs: step_over, step_into, step_out, continue_execution, restart_debugging and stop_debugging, none of which take parameters. The 2.2 release adds pause_execution, which the README describes as interrupting a freely running program and stopping at its current location even with no breakpoint set, aimed at busy loops and embedded or bare-metal targets. Breakpoints are managed separately: add_breakpoint takes a 1-based line and an optional condition, add_logpoint takes a logMessage with {expr} interpolation plus an optional condition, and remove_breakpoint, clear_all_breakpoints and list_breakpoints round out the set. Inspection is deliberately split in two. list_variable_names returns names and types without values; get_variables_values takes an explicit variableNames array and returns only those. evaluate_expression evaluates an expression but, per the tool table, lists expandable children by name and type without their values. That split is the most interesting design decision in the project, because it forces an agent to ask for a value rather than receive a dump of everything in scope.

Installation and the configuration surface

There are two install paths in the README. The Marketplace listing is itemName ozzafar.debugmcpextension, and the direct link is vscode:extension/ozzafar.debugmcpextension. The badge states VS Code 1.104.0 or newer. The README claims zero configuration and local operation, and the material does not document any settings keys, so treat the configuration section as thin: the parameters you actually control are the tool arguments, chiefly configurationName when a launch configuration must be selected by name and testName when a test should be launched. The 2.2 notes describe testName as routing through the VS Code Testing API to discover and launch the test, which the notes say produces consistent breakpoint hits inside individual test cases across pytest, Jest/Vitest, Java, .NET and Go. The same release installs the debug-live skill into ~/.agents/skills/ and, when present, ~/.copilot/skills/, and the server advertises MCP instructions pointing agents at that skill. That split matters operationally: the tools are terse and behavioural, while the procedural guidance about when to debug and how to structure a root-cause investigation lives in the skill file.

Where the design pushes back on the agent

The tool descriptions are intentionally minimal, and the README says so: tool descriptions stay terse while workflow guidance lives in the companion skill. An agent that only reads the tool schema will know it can call add_breakpoint but not why it should start at a function entry point or follow execution flow, which is the guidance the README places under debugging best practices. The 2.2 note about issue #105 is the clearest admission of a real failure mode: the skill was previously copied next to each agent's config, where nothing scanned it, and VS Code never loaded it. The fix moved installation to standard skills directories, but the underlying dependency remains. If your harness does not scan ~/.agents/skills/ or ~/.copilot/skills/, the procedural half of DebugMCP is invisible and you are left with raw tools. The value-splitting in the inspection tools has a similar edge. list_variable_names and evaluate_expression deliberately withhold values, so an agent that does not follow up with get_variables_values learns types and structure but not content. That is a reasonable guard against context flooding, and it is also a place where a poorly prompted agent stalls.

When DebugMCP is the wrong instrument

Every tool routes through the VS Code debugger, so the extension host is a hard boundary. An agent running on a remote host, in a CI container, or against a process VS Code cannot attach to gets nothing from this project. The README's compatibility claim is broad (any VS Code supported coding language), but that phrase inherits the constraint: a language needs a working debug adapter and, for start_debugging to succeed, a launch configuration the extension can identify by name or a test it can discover through the Testing API. If your project has no launch.json entry and no discoverable test, the first tool call has nothing to start. The pause_execution tool is described as useful for embedded and bare-metal targets, which suggests the maintainers expect non-standard setups, but the README does not explain how such a target is attached in the first place. For pure log-analysis work, or for bugs that reproduce only under production load, a debugger session is the wrong tool regardless of how well the MCP layer works.

How it differs from the obvious alternative

The alternative most teams already have is the debug adapter protocol directly, driven by a script or a custom harness rather than by an agent. DAP gives a client the same primitives DebugMCP exposes: launch, breakpoints, stepping, stack frames, variable requests. The difference in approach is who holds the session. A DAP client owns the connection and must implement launch configuration handling, breakpoint state and variable reference resolution itself; DebugMCP instead assumes VS Code owns the session and the agent issues calls into it, which is why its tool list can stay small and why the extension must be installed and the editor running. The trade is portability for simplicity. A DAP harness can run headless on a build machine; DebugMCP cannot, because there is no VS Code debugger to drive. The second alternative is the agent's existing loop of reading code, adding print statements and re-running. That loop needs no extension and works anywhere, but it changes the program under test and cannot inspect a value without a rebuild. DebugMCP's inspection tools, particularly the name-then-value split, exist precisely to avoid that cycle.

Maintenance, licence and what the material does not settle

The licence is MIT, which permits commercial use and modification provided the copyright notice and permission notice are retained; this is a description of the licence text, not legal advice, and organisations with strict policy should read the file in the repository. The repository is not archived and the last push recorded here is 2026-09-09, with the README badge showing version 2.3.5 while the What's New section stops at 2.2. No releases were retrieved, so there is no changelog to check for breaking changes between those versions, and that gap is worth noting before pinning a version. Maintenance cost looks low in steady state, since the extension installs from the Marketplace and the README claims zero configuration, but the upgrade path has one moving part: the debug-live skill is installed into directories outside the extension, so a harness that caches or copies skills may need those directories rechecked after an upgrade. The README also does not document the MCP server's transport or how the extension registers it with each assistant, so the first integration step for an unsupported harness is unverified here and should be confirmed against the repository rather than assumed from the compatibility list.

Editorial conclusion

Adopt DebugMCP if your agent already runs inside VS Code and you keep hitting bugs that logs and stack traces do not explain; the tool list is narrow enough to reason about and the licence is MIT. Skip it if your agent operates over SSH, in a container without the extension host, or on a language whose debug adapter the extension cannot launch, because every tool call routes through the VS Code debugger. Before wiring it into a workflow, verify three things in this order: that the extension installs on your VS Code build (1.104.0 or newer per the badge), that a manual debug session for your language starts from a launch configuration the extension can name, and that the agent harness loads the debug-live skill from ~/.agents/skills/, since the 2.2 release notes describe that directory as the fix for VS Code never loading the skill.

Official sources

1. Issues
2. License: MIT
3. microsoft/DebugMCP on GitHub
4. README