DebugMCP: Give AI Coding Agents Real Debugger Control in VS Code

What DebugMCP Solves and Why It Matters

AI coding assistants typically debug by reading log output and suggesting print statements. They cannot set a breakpoint at line 47, run to it, and inspect the value of a specific variable in the live program state. DebugMCP closes that gap.

The extension exposes the VS Code debugger to any MCP-compatible AI assistant through the Model Context Protocol. Instead of guessing from logs, the assistant can start a debug session, step through code line by line, read variable values at a specific call frame, evaluate an arbitrary expression in the current debug context, and stop the session when done. The process looks from the inside like a human developer working with the VS Code debugger; from the outside, it is an AI agent calling a set of defined tools.

The intended users are developers who already use MCP-compatible AI coding tools and want those tools to debug code rather than only generate it. The extension is compatible with Codex, GitHub Copilot, GitHub Copilot CLI, Claude Code, Cline, Cursor, Windsurf, Roo Code, and any other assistant that speaks MCP. It works with any programming language that VS Code's debugger supports.

The extension is published under the microsoft GitHub organisation and is maintained by Oz Zafar and Ori Barila at Microsoft. The README invites bug reports and contributions through the repository's issue tracker.

How the MCP-to-Debugger Bridge Works

VS Code's debugger sits on top of the Debug Adapter Protocol, a language-agnostic protocol that separates the editor UI from language-specific debugger implementations. DebugMCP inserts itself as an MCP server that translates MCP tool calls from an AI assistant into DAP operations.

When an assistant calls start_debugging, DebugMCP launches a debug session inside VS Code (or via the standalone CLI, through a configured DAP adapter) for the specified file. The debug adapter for that language handles the actual execution; DebugMCP mediates between the adapter's DAP events and the MCP tool responses the assistant receives.

For test debugging, start_debugging with a testName parameter uses the VS Code Testing API to discover and launch the specific test, producing consistent breakpoint hits inside individual test cases across test runners including pytest, Jest, Vitest, Java, .NET, and Go. This is more reliable than launching the test file directly and manually stepping to the right point.

The MCP server runs 100% locally. No code or debug state is sent to an external service.

Installing DebugMCP in VS Code

The VS Code extension installs from the Marketplace with one click. The direct marketplace link is:

vscode:extension/ozzafar.debugmcpextension

This can be pasted into a browser's address bar or opened from VS Code's Install from URL option. The extension activates on startup and on any debug session start. It registers the MCP server automatically; no manual MCP configuration is required in most cases.

For agents that need explicit MCP server configuration (such as those that do not auto-discover extensions), the extension installs the debug-live Agent Skill into the standard skills directories:

- ~/.agents/skills/ (the cross-agent location) - ~/.copilot/skills/ (when present)

Installing the skill there makes it discoverable to any skills-compatible harness that scans those directories, rather than requiring it to be copied next to each individual agent's configuration.

VS Code 1.104.0 or newer is required.

The Standalone CLI for Non-VS Code Environments

Version 2.4 added a standalone CLI that runs without VS Code. Install it globally:

npm install --global debugmcp

After installation, configure it for a specific agent:

debugmcp configure --agent copilot-cli

The CLI connects MCP-compatible agents to any DAP adapter that communicates over stdio. The debug adapter and target process run in the background. The CLI also installs the debug-live skill automatically. This path is useful in environments where VS Code is not available, such as a remote development server, a CI runner, or a workflow that uses only terminal-based AI agents.

The npm package is available at npmjs.com/package/debugmcp. The extension and the CLI share the same tool surface.

The 17 Debugger Tools

DebugMCP exposes 17 tools to AI assistants. Session control: start_debugging (with fileFullPath, workingDirectory, optional testName and configurationName), stop_debugging, and restart_debugging.

Execution control: step_over (execute the next line, stepping over function calls), step_into (enter function calls), step_out (return from the current function), continue_execution (run until the next breakpoint), and pause_execution (interrupt a freely running program at its current location, useful for busy loops and embedded targets).

Breakpoint management: add_breakpoint (file, 1-based line number, optional condition expression), add_logpoint (file, line, log message with {expr} interpolation, optional condition), remove_breakpoint, clear_all_breakpoints, and list_breakpoints.

Inspection: list_variable_names (names and types in scope, without reading values), get_variables_values (values of specifically named variables at the current execution point), and evaluate_expression (evaluate an expression in debug context; expandable children are listed by name and type without their values to keep responses manageable).

The separation between list_variable_names and get_variables_values is deliberate. An AI assistant can first enumerate what is in scope without reading values (which could be large objects), then selectively request values for the variables it cares about. This avoids flooding the context window with irrelevant data.

The debug-live Agent Skill

The 17 MCP tools handle individual debugger actions, but the skill of debugging requires knowing when to set a breakpoint, how to structure a root-cause investigation, and how to handle language-specific quirks. That workflow guidance lives in the companion debug-live Agent Skill.

The skill is installed into the standard cross-agent directories when the extension or CLI installs, so any skills-compatible harness loads it automatically. The README explains the design choice: keeping tool descriptions terse and behavioural while the skill carries the procedural workflow guidance. The skill file is at skills/debug-live/SKILL.md in the repository.

The start_debugging tool description points at the skill for the full workflow, so an AI assistant that loads the skill before debugging will use the recommended approach rather than improvising a strategy.

Supported Languages and AI Assistants

DebugMCP supports any language that has a VS Code debug adapter, because it mediates between the MCP protocol and the Debug Adapter Protocol rather than implementing language-specific debugging logic itself. Practically, this means Python (debugpy), JavaScript and TypeScript (Node.js debugger), Java (JDWP), .NET (C# extension), Go, Ruby, PHP, and any other language with a VS Code extension that provides a debug adapter.

The AI assistants listed in the README as supported are Codex, GitHub Copilot, GitHub Copilot CLI, Claude Code, Cline, Cursor, Windsurf, and Roo Code. Any assistant that implements the MCP tool-calling protocol works, including assistants not listed here.

The extension's package.json declares compatibility with VS Code 1.104.0 and newer. The display name is DebugMCP, Agentic Debugging for VS Code, Cursor and More, and it is categorised as a Debugger, AI, and Chat extension in the Marketplace.

Limitations and What DebugMCP Cannot Do

DebugMCP gives an AI assistant the same debugger interface a human developer uses in VS Code. It does not give the AI the ability to read the file system, run arbitrary shell commands, or modify source files; those capabilities depend on the AI assistant's own tool set, not on DebugMCP.

The MCP server runs locally inside the VS Code host process. Remote debugging, where the debug adapter runs on a different machine from VS Code, depends on VS Code's existing remote debugging support. The README does not document limitations specific to remote debugging configurations.

The evaluate_expression tool returns expandable children by name and type without their values. Getting values of nested properties requires additional get_variables_values calls. This is a deliberate design choice to keep context window use manageable, but it means inspecting deeply nested objects requires multiple round-trips.

For comparison, debugpy (the Python debugger for VS Code) is the underlying DAP adapter for Python debugging; DebugMCP does not replace it but exposes its capabilities through MCP. The difference from using a debugger REPL directly is that DebugMCP makes the debugger accessible to an AI assistant operating through tool calls, not through a terminal prompt.

The README also notes an important design separation: tool descriptions are kept terse and behavioural, while the how-to-debug workflow guidance lives in the companion debug-live skill file. This means a misconfigured agent that has the MCP tools loaded but not the skill will have the mechanical capability to debug but not the strategic workflow for root-cause investigation.

The project is MIT-licensed and maintained by Oz Zafar and Ori Barila at Microsoft. The last push was on 2026-09-27.

Editorial conclusion

DebugMCP is worth installing immediately if you use GitHub Copilot, Claude Code, Cline, Cursor, or any MCP-compatible assistant for debugging work in VS Code. The extension installs in seconds from the VS Code Marketplace and requires no configuration. For teams or CI pipelines that cannot use VS Code, the standalone CLI (npm install --global debugmcp) provides the same tools over any DAP adapter that communicates over stdio. The project is maintained under the microsoft GitHub organisation by Oz Zafar and Ori Barila at Microsoft, with the last push on 2026-09-27.

Frequently asked questions

Official sources

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