VSCode MCP DAP Debugger

VSCode MCP DAP Debugger exposes VS Code's Debug Adapter Protocol (DAP) through the Model Context Protocol (MCP) and an integrated CLI.

This enables AI coding agents (such as Claude Code, Kilo Code, Gemini CLI, Cursor, Roo Code, Codex, and others) to interact programmatically with the active VS Code debugger: setting breakpoints, stepping through execution, inspecting runtime variables, and evaluating expressions against running processes.

Features

• Launcher Auto-Configuration: Analyzes the workspace (Node.js, TypeScript, Python, Go, Rust, etc.) and generates or updates .vscode/launch.json configurations prior to starting a debug session - including attach configurations for a service running inside Docker Compose, inspecting the referenced compose file for exposed debug ports and container names.

• Breakpoint Management: Programmatically adds, removes, and lists breakpoints, conditional breakpoints, and logpoints.

• Execution Control: Controls step-over, step-into, step-out, pause, continue, and stop operations.

• Variable Inspection: Reads local, global, closure, and nested variable states across active stack frames.

• Expression Evaluation: Evaluates expressions directly in the context of the paused frame.

• Multi-Session & Multi-Thread Support: Tracks all active debug sessions and worker threads with explicit sessionId and threadId routing.

• Exception & Log Capture: Retrieves raw DAP protocol messages, debug console output, and exception traces.

• Monitor Panel: A status dashboard (server state, port, workspace config) with an AI Agent Skills table to install, reinstall, or check the status of the skill guide per environment (Claude Code, Gemini CLI, Kilo Code, AGENTS.md) without touching files by hand.

Getting Started

1. Install the Extension:

   • Open VS Code.

   • Open the Extensions view (Cmd+Shift+X on macOS / Ctrl+Shift+X on Windows/Linux).

   • Search for VSCode MCP DAP Debugger and click Install.

2. Open a Project:

   • Open your project folder in VS Code.

   • Verify the status bar shows ● Debug MCP:8891 (the MCP server starts automatically by default upon workspace load).

   

   • If the project already has a .claude, .gemini, or .kilo folder (or an AGENTS.md), a prompt asks permission before writing the AI-agent skill guide there - this only appears once per workspace. You can also install/reinstall it anytime from the Monitor Panel's "AI Agent Skills" table (Debug MCP: Open Monitor Panel).

3. Launch your AI Assistant & Approve MCP:

   • Open a terminal inside your project directory.

   • Launch your AI coding assistant (e.g. claude or kilo).

   • When prompted by the assistant CLI to approve the new MCP server/tools, grant permission.

4. Debug with AI:

   • Ask your AI assistant to debug a specific issue (e.g. "Set a breakpoint in app.js and trace the calculation error").

   • The agent will discover the tools and control the active VS Code debugger.

   • This also covers launcher setup itself - e.g. "Configure my launcher to debug the service in docker-compose.yml and set a breakpoint in src/worker.py" - the agent inspects the compose file for the service's exposed debug port before writing the attach configuration.

Note on approval prompts: Claude Code (and similar CLIs) treat project-scoped MCP servers declared in .mcp.json as untrusted until explicitly approved — this is a security gate, not a bug. The prompt only appears when the CLI starts a new session in the project directory: if a session was already running before the server was configured, it won't show up retroactively. Start (or restart) your AI assistant session in the project folder to trigger the prompt, then approve dap-proxy (or your configured server name) when asked. Check the current state anytime with claude mcp list.

Tutorial & Sample Projects

Ready-to-run sample projects demonstrating debugging workflows from simple to advanced:

• AI Debugging Tutorial: Step-by-step walkthrough covering breakpoint inspection, asynchronous exceptions, and multi-threaded debugging.

• Sample 1: Basic Calculation Bug: Setting breakpoints and inspecting variables in synchronous code.

• Sample 2: Async Data Pipeline: Trapping unhandled exceptions and stepping through asynchronous streams.

• Sample 3: Multi-Threaded Workers: Inspecting worker threads and evaluating expressions across threads.

Extension Settings

All configuration options are available under the vscodeMcpDapDebugger.* namespace in settings.json:

Security & Architecture

• Local Loopback Only: The HTTP server binds exclusively to 127.0.0.1.

• DNS Rebinding Protection: Enforced on all incoming requests.

• Per-Instance Token Authentication: A cryptographic token is generated at startup and written to .vscode/mcp-dap-debugger.json with restricted file permissions (0o600).

• Discovery Isolation: The CLI discovers active instances by reading the workspace configuration (.vscode/mcp-dap-debugger.json) or querying the per-user active registry (~/.vscode-mcp-dap-debugger/active-configs.json).

Development & Contributing

For instructions on building from source, testing the CLI standalone, or running the extension in development mode, refer to DEVELOPMENT.md.

Credits & License

This project is a from-scratch rewrite inspired by mcp-debug-tools by Hwanyong Yoo. The VS Code integration points and CLI discovery approach were used as a reference, while the DAP tracking, session lifecycle, atomic server startup, and security models were redesigned.

Licensed under the GPL-3.0 License.