Skip to content
Back to search

DebugMCP

Gift your VS Code agent a real debugger: breakpoints, stepping, inspection.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/microsoft/DebugMCP with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/microsoft/DebugMCP'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/microsoft--debugmcp/badge.svg)](/listings/microsoft--debugmcp)

HTML

<a href="/listings/microsoft--debugmcp"><img src="/api/listings/microsoft--debugmcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**[Install DebugMCP from VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=ozzafar.debugmcpextension)** or use the direct link: `vscode:extension/ozzafar.debugmcpextension`

**[Install DebugMCP from Open VSX Registry](https://open-vsx.org/extension/ozzafar/debugmcpextension)**

**[Install debugmcp-cli from npm](https://www.npmjs.com/package/debugmcp)**

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 641 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # DebugMCP (MCP Server) - Empowering AI Agents with Operational Debugging Capabilities
  2. Let AI agents debug your code inside VS Code - set breakpoints, step through execution, inspect variables, and evaluate expressions. Works with **Codex**, **GitHub Copilot**, **GitHub Copilot CLI**, **Claude Code**, **Cline**, **Cursor**, **Windsurf**, **Roo Code**, and any MCP-compatible assistant. Compatible with any VS Code supported coding language.
  3. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  4. [![VS Code](https://img.shields.io/badge/VS%20Code-1.104.0+-blue.svg)](https://code.visualstudio.com/)
  5. [![Version](https://img.shields.io/badge/version-2.4.4-green.svg)](https://github.com/microsoft/DebugMCP)
  6. [![VS Marketplace](https://img.shields.io/badge/VS%20Marketplace-Install-blue.svg)](https://marketplace.visualstudio.com/items?itemName=ozzafar.debugmcpextension)
  7. [![Open VSX](https://img.shields.io/badge/Open%20VSX-Install-blue.svg)](https://open-vsx.org/extension/ozzafar/debugmcpextension)
  8. [![npm](https://img.shields.io/badge/npm-debugmcp-red.svg)](https://www.npmjs.com/package/debugmcp)
  9. > 🚀 **DebugMCP CLI is now available on npm!** Debug directly from the
  10. > terminal **without requiring VS Code or any IDE at all** by connecting AI
  11. > coding agents to explicitly configured Debug Adapter Protocol (DAP) adapters.
  12. > The debug adapter and target process **run in the background**. Install it with
  13. > `npm install --global debugmcp`, then run
  14. > `debugmcp configure --agent copilot-cli`. The CLI also installs the
  15. > `debug-live` skill automatically. **[View the package on npm](https://www.npmjs.com/package/debugmcp)**
  16. > ⭐ **If you find DebugMCP useful, please [star the repo on GitHub](https://github.com/microsoft/DebugMCP)!** It helps others discover the project and motivates continued development.
  17. > **📢 Developers Notice**: This extension is maintained by [ozzafar@microsoft.com](mailto:ozzafar@microsoft.com) and [orbarila@microsoft.com](mailto:orbarila@microsoft.com). We welcome feedback and contributions to help improve this extension.
  18. > 🎬 Watch DebugMCP in action — your AI assistant autonomously sets breakpoints, steps through code, and inspects variables directly in VS Code.
  19. <p align="center">
  20. <img src="assets/DebugMCP.gif" width="800">
  21. </p>
  22. ## ✨ What's New
  23. ### 2.4
  24. - **Standalone DebugMCP CLI** — install [`debugmcp`](https://www.npmjs.com/package/debugmcp) from npm and give MCP-compatible agents direct access to explicitly configured DAP adapters without running VS Code. The CLI supports any language with a DAP adapter that communicates over stdio, configures supported agents, and installs the `debug-live` skill automatically.
  25. ### 2.2
  26. - **Cross-agent `debug-live` skill install** — the systematic debugging workflow ships as an [Agent Skill](https://agentskills.io) and is now installed into the **standard skills directories** — `~/.agents/skills/` (the cross-agent location honored by skills-compatible harnesses, including VS Code agent mode) and `~/.copilot/skills/` when present — so it's discoverable everywhere instead of being copied next to each agent's config where nothing scans it (fixes [#105](https://github.com/microsoft/DebugMCP/issues/105), where VS Code never loaded the skill). The server also advertises MCP `instructions` and the `start_debugging` tool points at the skill for the full workflow.
  27. - **Pause running programs** — new `pause_execution` tool interrupts a freely-running program and stops at its current location, even with no breakpoint set (great for busy loops and embedded/bare-metal targets), so you can then inspect state or step from there.
  28. - **Robust debugging via the VS Code Testing API** — `start_debugging` with a `testName` uses the VS Code Testing API to discover and launch the test, producing consistent breakpoint hits inside individual test cases across language test runners (pytest, Jest/Vitest, Java, .NET, Go, etc.).
  29. ## 🚀 Quick Install
  30. **[Install DebugMCP from VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=ozzafar.debugmcpextension)** or use the direct link: `vscode:extension/ozzafar.debugmcpextension`
  31. **[Install DebugMCP from Open VSX Registry](https://open-vsx.org/extension/ozzafar/debugmcpextension)**
  32. **[Install debugmcp-cli from npm](https://www.npmjs.com/package/debugmcp)**
  33. ## Table of Contents
  34. - [Overview](#overview)
  35. - [Features](#features)
  36. - [Installation](#installation)
  37. - [Quick Start](#quick-start)
  38. - [Supported AI Assistants](#supported-ai-assistants)
  39. - [Supported Languages](#supported-languages)
  40. - [Configuration](#configuration)
  41. - [FAQ](#faq)
  42. - [Troubleshooting](#troubleshooting)
  43. - [How It Works](#how-it-works)
  44. - [Contributing](#contributing)
  45. - [License](#license)
  46. ## Overview
  47. DebugMCP is an MCP server that gives AI coding agents full control over the VS Code debugger. Instead of reading logs or guessing, your AI assistant can autonomously set breakpoints, launch debug sessions, step through code line by line, inspect variable values, and evaluate expressions — just like a human developer would. It runs 100% locally, requires zero configuration, and works out of the box with any MCP-compatible AI assistant.
  48. ## Features
  49. ### 🔧 Tools
  50. | Tool | Description | Parameters |
  51. |------|-------------|------------|
  52. | **start_debugging** | Start a debug session for a source code file | `fileFullPath` (required)<br>`workingDirectory` (required)<br>`testName` (optional)<br>`configurationName` (optional) |
  53. | **stop_debugging** | Stop the current debug session | None |
  54. | **step_over** | Execute the next line (step over function calls) | None |
  55. | **step_into** | Step into function calls | None |
  56. | **step_out** | Step out of the current function | None |
  57. | **continue_execution** | Continue until next breakpoint | None |
  58. | **pause_execution** | Interrupt a freely-running program and stop at its current location (no breakpoint needed) | None |
  59. | **restart_debugging** | Restart the current debug session; a fresh stop without acknowledgement returns an explicit completion-unconfirmed result, not confirmed success | None |
  60. | **get_debug_status** | Read paused/running/no-session status, the active session ID, and selected-frame details when paused; optionally wait for a pause | `waitForPauseSeconds` (optional, 0-600; bounded by the operation timeout) |
  61. | **get_debug_output** | Read captured output for one session; requires user-enabled capture and at least one filter | `sessionId` (required)<br>`prefix` and/or `category` (required filter; both are ANDed)<br>`cursor` (optional)<br>`limit` (optional, 1-100) |
  62. | **add_breakpoint** | Add a breakpoint at a specific line (optionally conditional) | `fileFullPath` (required)<br>`line` (required, 1-based)<br>`condition` (optional) |
  63. | **add_logpoint** | Add a logpoint that logs a message (instead of pausing) when a line is reached | `fileFullPath` (required)<br>`line` (required, 1-based)<br>`logMessage` (required, `{expr}` interpolated)<br>`condition` (optional) |
  64. | **remove_breakpoint** | Remove a breakpoint from a specific line | `fileFullPath` (required)<br>`line` (required) |
  65. | **clear_all_breakpoints** | Remove all breakpoints at once | None |
  66. | **list_breakpoints** | List all active breakpoints | None |
  67. | **list_variable_names** | List names and types of variables in scope, without reading any values | `scope` (optional: 'local', 'global', 'all') |
  68. | **get_variables_values** | Get the values of specifically named variables at the current execution point | `variableNames` (required, e.g. `["user","response"]`)<br>`scope` (optional: 'local', 'global', 'all') |
  69. | **evaluate_expression** | Evaluate an expression in debug context; expandable children are listed by name and type without their values | `expression` (required) |
  70. > **Note:** The MCP server exposes **tools** for debugger actions, while the procedural
  71. > workflow guidance (when to debug, how to structure a root-cause investigation,
  72. > language-specific quirks) lives in the companion [Agent Skill](./skills/debug-live/SKILL.md).
  73. > Tool descriptions stay terse and behavioral; the extension installs the `debug-live` skill
  74. > into the standard skills directories (`~/.agents/skills/`, plus `~/.copilot/skills/` when
  75. > present) so skills-compatible harnesses load the full workflow on demand. The server also
  76. > advertises MCP `instructions` pointing agents at it before debugging.
  77. ### Debug output capture
  78. To read logpoint messages without pausing the program, enable
  79. `debugmcp.captureDebugOutput` in VS Code user settings before output is emitted.
  80. For the standalone CLI host, start it with `debugmcp serve --capture-output`.
  81. Capture is **off by default**, and MCP tools cannot enable it.
  82. Obtain `sessionId` from `get_debug_status` while the session is active, then call
  83. `get_debug_output`, for example:
  84. ```json
  85. {
  86. "sessionId": "<session-id-from-get_debug_status>",
  87. "prefix": "[orders]",
  88. "limit": 20
  89. }
  90. ```
  91. Provide a nonempty `prefix` (up to 256 characters), a `category` (`console`,
  92. `stdout`, `stderr`, or `important`), or both. Reuse the returned `nextCursor` as
  93. `cursor` with the same filters to read new entries; `hasMore` indicates additional
  94. entries to scan, and `truncated` reports evicted history. Only DAP output events
  95. are captured, not existing Debug Console contents.
  96. Output stays in memory, bounded to 8 sessions and 1,000 events/256 KiB per
  97. session. Events over 8 KiB are replaced by an omission marker. History can
  98. remain after termination until eviction, but changing the capture setting or
  99. disposing the host clears it; output is not persisted or logged by the capture
  100. feature. Credential-pattern redaction happens before retention, but is
  101. **heuristic and event-local, not a guarantee that every secret is removed**.
  102. Enable capture only for output you intend to make available to the agent.
  103. ### 🎯 Debugging Best Practices
  104. DebugMCP follows systematic debugging practices for effective issue resolution:
  105. - **Start with Entry Points**: Begin debugging at function entry points or main execution paths
  106. - **Follow the Execution Flow**: Use step-by-step execution to understand code flow
  107. - **Root Cause Analysis**: Don't stop at symptoms - find the underlying cause
  108. ### 🛡️ Security & Reliability
  109. - **Secure Communication**: All MCP communications use secure protocols
  110. - **Local Operation**: The MCP server runs 100% locally with no external communications and requires no credentials
  111. - **State Validation**: Robust validation of debugging states and operations
  112. ## Installation
  113. ### Standalone CLI (preview)
  114. The standalone host talks directly to explicitly configured DAP adapters and
  115. does not require VS Code. It never discovers, downloads, installs, or selects an
  116. adapter automatically.
  117. Install the published package:
  118. ```console
  119. npm install --global debugmcp
  120. ```
  121. For repository development, build and invoke the local bundle:
  122. ```console
  123. npm install
  124. npm run package
  125. node dist/debugmcp.js adapter add python --command "python -m debugpy.adapter"
  126. node dist/debugmcp.js adapter validate python
  127. node dist/debugmcp.js configure
  128. ```
  129. Adapter registrations are stored in `.debugmcp.json` by default. Add `--user`
  130. to `adapter add`, `adapter list`, or `adapter remove` to use the per-user
  131. configuration. Project registrations override registrations with the same name
  132. in user configuration.
  133. Language shorthands derive the DAP type and file extensions for `python`,
  134. `csharp`, `dotnet`, `cpp`, `c`, `javascript`, `typescript`, `node`, `java`,
  135. `go`, `rust`, `ruby`, `php`, `swift`, and `dart`. These are configuration
  136. conveniences, not a language support boundary. The command remains explicit so
  137. the selected environment determines which adapter installation is used.
  138. Languages without a shorthand provide `--type` and `--extensions` explicitly.
  139. Compiled-language registrations can provide the executable in `--launch`;
  140. values support `${workspaceFolder}`, `${file}`, `${fileDirname}`, and
  141. `${fileBasenameNoExtension}`.
  142. The current CLI supports adapters that speak DAP over stdio. A registration can
  143. provide adapter-specific launch properties with `--launch` followed by a JSON
  144. object. If multiple registered adapters claim the same file extension,
  145. `start_debugging.configurationName` must identify the adapter to use. Test
  146. discovery remains host-specific; configure the adapter launch properties to run
  147. the required test command.
  148. Adapter arguments beginning with `--` can follow `--args` directly. Use a
  149. standalone `--` after `--args` when an adapter argument has the same name as a
  150. DebugMCP option, for example `--args -- --user`.
  151. `debugmcp configure` presents the same agent choices as the VS Code extension's
  152. setup popup and writes the standalone stdio command for every selected agent.
  153. In automation, repeat `--agent <id>` to bypass the terminal prompt, for example
  154. `debugmcp configure --agent copilot-cli --agent codex`. Each configuration has
  155. one canonical `debugmcp` entry, so configuring the CLI replaces an existing
  156. extension HTTP entry rather than registering both.
  157. The command also installs the bundled `debug-live` skill into the standard
  158. personal skills directories. Restart configured agents to discover it.
  159. Use `debugmcp status` to inspect the GitHub Copilot CLI registration. The
  160. DebugMCP command configures only the standalone CLI. To use the interactive
  161. VS Code version, configure it through the DebugMCP extension's agent popup;
  162. the command line does not select or configure the extension.
  163. ### Quick Install Options
  164. **Option 1: Direct Link** (Fastest)
  165. - Click this link: [vscode:extension/ozzafar.debugmcpextension](vscode:extension/ozzafar.debugmcpextension)
  166. - Or copy and paste in your browser: `vscode:extension/ozzafar.debugmcpextension`
  167. **Option 2: VS Code Marketplace**
  168. - Visit: [https://marketplace.visualstudio.com/items?itemName=ozzafar.debugmcpextension](https://marketplace.visualstudio.com/items?itemName=ozzafar.debugmcpextension)
  169. - Click "Install"
  170. **Option 3: Within VS Code**
  171. 1. Open VSCode
  172. 2. Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
  173. 3. Search for "DebugMCP"
  174. 4. Click Install
  175. 5. The extension automatically activates and registers as an MCP server
  176. ### Verification
  177. After installation, you should see:
  178. - DebugMCP extension in your installed extensions
  179. - MCP server automatically running on port 3001 (configurable)
  180. - Debug tools available to connected AI assistants
  181. > **📝 Note**: No additional debugging rule instructions are needed - the extension works out of the box.
  182. > **💡 Tip**: Enable auto-approval for all debugmcp tools in your AI assistant to create seamless debugging workflows without constant approval interruptions.
  183. ## Quick Start
  184. 1. **Install the extension** (see [Installation](#installation))
  185. 2. **Open your project** in VSCode
  186. 3. **Ask your AI to debug** - it can now set breakpoints, start debugging, and analyze your code!
  187. ## Supported AI Assistants
  188. DebugMCP works with any MCP-compatible AI assistant. It auto-detects and offers to register itself with:
  189. | Assistant | Auto-Registration | Manual Config |
  190. |-----------|:-----------------:|:-------------:|
  191. | **GitHub Copilot** | ✅ | [See config](#github-copilot) |
  192. | **GitHub Copilot CLI** | ✅ | [See config](#github-copilot-cli) |
  193. | **Claude Code** | ✅ | [See config](#claude-code) |
  194. | **Cline** | ✅ | [See config](#cline) |
  195. | **Cursor** | ✅ | [See config](#cursor) |
  196. | **Codex** | ✅ | [See config](#codex) |
  197. | **Windsurf** | ✅ | [See config](#windsurf) |
  198. | **Roo Code** | ✅ | [See config](#roo-code) |
  199. | **Antigravity** | ✅ | [See config](#antigravity) |
  200. | Any MCP-compatible assistant | — | [See manual setup](#manual-mcp-server-registration-optional) |
  201. ## Supported Languages
  202. DebugMCP supports debugging for the following languages with their respective VSCode extensions:
  203. | Language | Extension Required | File Extensions | Status |
  204. |----------|-------------------|-----------------|---------|
  205. | **Python** | [Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python) | `.py` | ✅ Fully Supported |
  206. | **JavaScript/TypeScript** | Built-in / [JS Debugger](https://marketplace.visualstudio.com/items?itemName=ms-vscode.js-debug) | `.js`, `.ts`, `.jsx`, `.tsx` | ✅ Fully Supported |
  207. | **Java** | [Extension Pack for Java](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-pack) | `.java` | ✅ Fully Supported |
  208. | **C/C++** | [C/C++](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools) | `.c`, `.cpp`, `.cc` | ✅ Fully Supported |
  209. | **Go** | [Go](https://marketplace.visualstudio.com/items?itemName=golang.Go) | `.go` | ✅ Fully Supported |
  210. | **Rust** | [rust-analyzer](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer) | `.rs` | ✅ Fully Supported |
  211. | **PHP** | [PHP Debug](https://marketplace.visualstudio.com/items?itemName=xdebug.php-debug) | `.php` | ✅ Fully Supported |
  212. | **Ruby** | [Ruby](https://marketplace.visualstudio.com/items?itemName=Shopify.ruby-lsp) | `.rb` | ✅ Fully Supported |
  213. | **C#/.NET** | [C#](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csharp) | `.cs`, `.csproj` | ✅ Fully Supported |
  214. ## Configuration
  215. ### MCP Server Configuration (Recommended)
  216. The extension runs an MCP server automatically. It will pop up a message to auto-register the MCP server in your AI assistant.
  217. You can also trigger the registration manually via the Command Palette:
  218. - **`DebugMCP: Show Agent Selection Popup`**
  219. ### Manual MCP Server Registration (Optional)
  220. > **🔄 Auto-Migration**: If you previously configured DebugMCP with SSE transport, the extension will automatically migrate your configuration to the new Streamable HTTP transport on activation.
  221. #### Cline
  222. Add to your Cline settings or `cline_mcp_settings.json`:
  223. ```json
  224. {
  225. "mcpServers": {
  226. "debugmcp": {
  227. "type": "streamableHttp",
  228. "url": "http://localhost:3001/mcp",
  229. "description": "DebugMCP - AI-powered debugging assistant"
  230. }
  231. }
  232. }
  233. ```
  234. #### GitHub Copilot
  235. Add to your VS Code settings (`settings.json`):
  236. ```json
  237. {
  238. "mcp": {
  239. "servers": {
  240. "debugmcp": {
  241. "type": "http",
  242. "url": "http://localhost:3001/mcp",
  243. "description": "DebugMCP - Multi-language debugging support"
  244. }
  245. }
  246. }
  247. }
  248. ```
  249. #### GitHub Copilot CLI
  250. Add to `~/.copilot/mcp-config.json` (`${COPILOT_HOME}/mcp-config.json` if `COPILOT_HOME` is set):
  251. ```json
  252. {
  253. "mcpServers": {
  254. "debugmcp": {
  255. "type": "http",
  256. "url": "http://localhost:3001/mcp",
  257. "tools": ["*"]
  258. }
  259. }
  260. }
  261. ```
  262. #### Claude Code
  263. Register DebugMCP with Claude Code:
  264. ```bash
  265. claude mcp add --transport http --scope user debugmcp http://localhost:3001/mcp
  266. ```
  267. Or add the equivalent configuration to `~/.claude.json` (top-level `mcpServers`, for cross-project user-scope access — see the [Claude Code MCP docs](https://code.claude.com/docs/en/mcp)):
  268. ```json
  269. {
  270. "mcpServers": {
  271. "debugmcp": {
  272. "type": "http",
  273. "url": "http://localhost:3001/mcp"
  274. }
  275. }
  276. }
  277. ```
  278. > **Claude Desktop**: Claude Desktop connects to local/remote HTTP MCP servers through **Settings → Connectors → Add custom connector** rather than a static config file — paste `http://localhost:3001/mcp` there. DebugMCP doesn't auto-register with Desktop for this reason.
  279. #### Cursor
  280. Add to Cursor's MCP settings:
  281. ```json
  282. {
  283. "mcpServers": {
  284. "debugmcp": {
  285. "type": "streamableHttp",
  286. "url": "http://localhost:3001/mcp",
  287. "description": "DebugMCP - Debugging tools for AI assistants"
  288. }
  289. }
  290. }
  291. ```
  292. #### Codex
  293. Register DebugMCP with Codex:
  294. ```bash
  295. codex mcp add debugmcp --url http://localhost:3001/mcp
  296. ```
  297. Or add the equivalent configuration to `~/.codex/config.toml` (`${CODEX_HOME}/config.toml` if `CODEX_HOME` is set):
  298. ```toml
  299. [mcp_servers.debugmcp]
  300. url = "http://localhost:3001/mcp"
  301. ```
  302. #### Windsurf
  303. Add to Windsurf's MCP settings (`~/.windsurf/mcp_settings.json` or workspace `.windsurf/mcp_settings.json`):
  304. ```json
  305. {
  306. "mcpServers": {
  307. "debugmcp": {
  308. "type": "streamableHttp",
  309. "url": "http://localhost:3001/mcp",
  310. "description": "DebugMCP - Debugging tools for AI assistants"
  311. }
  312. }
  313. }
  314. ```
  315. #### Roo Code
  316. Add to Roo Code's MCP settings:
  317. ```json
  318. {
  319. "mcpServers": {
  320. "debugmcp": {
  321. "type": "streamableHttp",
  322. "url": "http://localhost:3001/mcp",
  323. "description": "DebugMCP - Debugging tools for AI assistants"
  324. }
  325. }
  326. }
  327. ```
  328. #### Antigravity
  329. Add to Antigravity's MCP settings:
  330. ```json
  331. {
  332. "mcpServers": {
  333. "debugmcp": {
  334. "type": "streamableHttp",
  335. "url": "http://localhost:3001/mcp",
  336. "description": "DebugMCP - Debugging tools for AI assistants"
  337. }
  338. }
  339. }
  340. ```
  341. ### Extension Settings
  342. Configure DebugMCP behavior in VSCode settings:
  343. ```json
  344. {
  345. "debugmcp.serverPort": 3001,
  346. "debugmcp.timeoutInSeconds": 180,
  347. "debugmcp.bindHost": ["127.0.0.1", "::1"],
  348. "debugmcp.captureDebugOutput": false
  349. }
  350. ```
  351. | Setting | Default | Description |
  352. |---------|---------|-------------|
  353. | `debugmcp.serverPort` | `3001` | Port number for the MCP server |
  354. | `debugmcp.timeoutInSeconds` | `180` | Timeout for debugging operations |
  355. | `debugmcp.bindHost` | `["127.0.0.1", "::1"]` | Network interface(s) the HTTP server binds to. Accepts a string or array of strings. See [Security model](#security-model) before changing. |
  356. | `debugmcp.captureDebugOutput` | `false` | User-controlled, machine-scoped capture of bounded debugger output. See [Debug output capture](#debug-output-capture); agents cannot enable capture through MCP. |
  357. ### Security model
  358. DebugMCP exposes powerful debugger primitives (`evaluate_expression`, `start_debugging`, …) over an unauthenticated local HTTP endpoint. To keep that surface safe, the server enforces four controls:
  359. 1. **Loopback-only bind.** The HTTP server binds to the IPv4 and IPv6 loopback addresses (`127.0.0.1` and `::1`) by default, so other hosts on your network cannot reach `http://<your-ip>:3001/mcp`. Binding both families ensures clients that resolve `localhost` to either family connect successfully. The `debugmcp.bindHost` setting (string or array of strings) lets you opt into a different interface (for example, when forwarding the port into a remote container), but doing so exposes the unauthenticated debugger to anything that can route to that address — do not point it at `0.0.0.0` or a LAN address on an untrusted network.
  360. 2. **Host / Origin header validation.** Every request must carry a `Host` header naming a loopback address (`localhost`, `127.0.0.1`, or `[::1]`); any port suffix in the `Host` must also match the server's listening port. Requests with any other `Host` — including those that arrive via DNS rebinding from a malicious webpage — are rejected with HTTP 403. The same loopback check is applied to the `Origin` header when present.
  361. 3. **Least-privilege variable inspection.** `get_variables_values` requires an explicit `variableNames` list (max 50, no wildcards) and returns only those variables. It no longer dumps every variable in scope, which previously handed the agent unrelated process state that it never asked for. Use `list_variable_names` to discover what exists; that tool returns names and types only and never reads a value.
  362. 4. **Secret redaction on variable inspection.** Values with credential-bearing names or values matching a known credential shape are replaced with `<redacted: possible secret>` before the response leaves the extension. The evaluated result returned by `evaluate_expression` is covered too. When `get_variables_values` or `evaluate_expression` expands a complex value, descendants are listed by name and type only. Use `evaluate_expression` with an exact descendant path when its value is needed. Recursive expansion is capped at 100 child fields total per response. Null-ish values (`None`, `undefined`, `''`) are never redacted so "my token is empty" bugs remain debuggable. Redaction is always on and cannot be turned off.
  363. ## FAQ
  364. <details>
  365. <summary><b>Which AI assistants are supported?</b></summary>
  366. DebugMCP works with any MCP-compatible AI assistant, including **GitHub Copilot**, **GitHub Copilot CLI**, **Claude Code**, **Cline**, **Cursor**, **Codex**, **Windsurf**, **Roo Code**, **Antigravity**, and others. If your assistant supports the Model Context Protocol, it can use DebugMCP. Claude Desktop can also connect via its Custom Connector UI (see [Claude Code](#claude-code) in the manual configuration section).
  367. </details>
  368. <details>
  369. <summary><b>Does it work with VS Code Remote SSH / Codespaces / WSL?</b></summary>
  370. Yes. DebugMCP runs as a VS Code extension with `extensionKind: workspace`, so it activates in the remote environment where your code lives. The MCP server runs on `localhost` within that remote context.
  371. </details>
  372. <details>
  373. <summary><b>Do I need to configure launch.json?</b></summary>
  374. No. DebugMCP automatically generates appropriate debug configurations based on the file's language/extension. If you have a `launch.json`, it will automatically pick the most relevant configuration.
  375. </details>
  376. <details>
  377. <summary><b>Is my code sent to any external service?</b></summary>
  378. No. DebugMCP runs 100% locally. The MCP server runs on `localhost`, and no code, variables, or debug data is sent to any external service. The AI assistant communicates with the MCP server entirely within your local machine.
  379. </details>
  380. <details>
  381. <summary><b>What if port 3001 is already in use?</b></summary>
  382. Change the port in VS Code settings: `"debugmcp.serverPort": 3002` (or any available port). Then update your AI assistant's MCP configuration to use the new port.
  383. </details>
  384. <details>
  385. <summary><b>Can I debug unit tests?</b></summary>
  386. Yes. Pass the `testName` parameter to `start_debugging` to debug a specific test method. DebugMCP will configure the debug session to run and pause at breakpoints within that test.
  387. </details>
  388. <details>
  389. <summary><b>Why is my AI assistant not using the debug tools?</b></summary>
  390. Make sure DebugMCP is registered in your AI assistant's MCP settings. The extension should auto-detect and offer to register itself. If not, see the [Manual MCP Server Registration](#manual-mcp-server-registration-optional) section. Also enable auto-approval for DebugMCP tools for a smoother workflow.
  391. </details>
  392. <details>
  393. <summary><b>Does it support ASP.NET / .csproj projects?</b></summary>
  394. Yes. DebugMCP supports `.cs` files and `.csproj` project files for C#/.NET debugging, including ASP.NET applications.
  395. </details>
  396. ## Troubleshooting
  397. ### Common Issues
  398. #### MCP Server Not Starting
  399. - **Symptom**: AI assistant can't connect to DebugMCP
  400. - **Solution**:
  401. - Check if port 3001 is available
  402. - Restart VSCode
  403. - Verify extension is installed and activated
  404. #### Debug Session Not Stopping at Breakpoints
  405. - **Symptom**: Breakpoints are set but execution doesn't pause
  406. - **Solution**:
  407. - Ensure the correct file is being debugged
  408. - Check that the breakpoint line number is correct
  409. - Verify the relevant language debugger extension is installed
  410. #### Another VS Code Window Takes Focus When Debugging Stops
  411. - **Symptom**: With multiple VS Code windows open, the window being debugged comes to the foreground when it hits a breakpoint or completes a step
  412. - **Solution**: Disable VS Code's native focus-on-break behavior in your user or workspace settings:
  413. ```json
  414. {
  415. "debug.focusWindowOnBreak": false,
  416. "debug.focusEditorOnBreak": false
  417. }
  418. ```
  419. `debug.focusWindowOnBreak` prevents the debugged window from taking operating-system focus. The optional `debug.focusEditorOnBreak` setting also prevents VS Code from moving focus into the stopped source editor. DebugMCP does not change these persistent preferences automatically.
  420. #### Configuration Not Auto-Detected
  421. - **Symptom**: Extension doesn't prompt to register with your AI assistant
  422. - **Solution**:
  423. - Run **`DebugMCP: Show Agent Selection Popup`** from the Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
  424. - Manually add the configuration (see [Manual MCP Server Registration](#manual-mcp-server-registration-optional))
  425. ## How It Works
  426. ### Architecture
  427. <p align="center">
  428. <img src="assets/architecture.png" alt="DebugMCP Architecture" width="800">
  429. </p>
  430. ```
  431. AI Agent (Copilot/Cline/Cursor/Codex) → MCP/Streamable HTTP → DebugMCPServer → DebuggingHandler → VS Code Debug API
  432. ```
  433. ### Launch Configuration Integration
  434. The extension handles debug configurations intelligently:
  435. - **Existing launch.json**: If a `.vscode/launch.json` file exists, it will:
  436. - Search for a relevant configuration
  437. - Honor `configurationName` when explicitly provided by the agent
  438. - Support JSONC (JSON with comments and trailing commas)
  439. - **Default Configuration**: If `configurationName` is omitted, or if no matching named configuration is found, it creates an appropriate default configuration for each language based on file extension detection
  440. ## Requirements
  441. - VSCode with appropriate language extensions installed:
  442. - **Python**: [Python extension](vscode:extension/ms-python.debugpy) for `.py` files
  443. - **JavaScript/TypeScript**: Built-in Node.js debugger or [JavaScript Debugger extension](vscode:extension/ms-vscode.js-debug)
  444. - **Java**: [Extension Pack for Java](vscode:extension/vscjava.vscode-java-pack)
  445. - **C#/.NET**: [C# extension](vscode:extension/ms-dotnettools.csharp)
  446. - **C/C++**: [C/C++ extension](vscode:extension/ms-vscode.cpptools)
  447. - **Go**: [Go extension](vscode:extension/golang.go)
  448. - **Rust**: [rust-analyzer extension](vscode:extension/rust-lang.rust-analyzer)
  449. - **PHP**: [PHP Debug extension](vscode:extension/xdebug.php-debug)
  450. - **Ruby**: [Ruby extension](vscode:extension/Shopify.ruby-lsp) and the [`debug` gem](https://github.com/ruby/debug)
  451. - MCP-compatible AI assistant (Copilot, Claude Code, Cline, Cursor, Codex, Windsurf, Roo Code, etc.)
  452. ## Development
  453. To build the extension:
  454. ```bash
  455. npm install
  456. npm run compile
  457. ```
  458. To run linting:
  459. ```bash
  460. npm run lint
  461. ```
  462. To run tests:
  463. ```bash
  464. npm test
  465. ```
  466. ## Contributing
  467. This project welcomes contributions and suggestions. Most contributions require you to agree to a
  468. Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
  469. the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
  470. When you submit a pull request, a CLA bot will automatically determine whether you need to provide
  471. a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions
  472. provided by the bot. You will only need to do this once across all repos using our CLA.
  473. This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
  474. For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
  475. contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
  476. ## Security
  477. Security vulnerabilities should be reported following the guidance at [https://aka.ms/SECURITY.md](https://aka.ms/SECURITY.md).
  478. Please do not report security vulnerabilities through public GitHub issues.
  479. ## Trademarks
  480. This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft
  481. trademarks or logos is subject to and must follow
  482. [Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general).
  483. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
  484. Any use of third-party trademarks or logos are subject to those third-party's policies.
  485. ## ⭐ Support DebugMCP
  486. If DebugMCP has helped you debug faster, please consider giving it a star on GitHub! Stars help the project gain visibility and attract contributors.
  487. **[⭐ Star DebugMCP on GitHub](https://github.com/microsoft/DebugMCP)**
  488. ### Star History
  489. <a href="https://star-history.dera.page/#microsoft/DebugMCP&Date">
  490. <picture>
  491. <source media="(prefers-color-scheme: dark)" srcset="https://star-history.dera.page/svg?repos=microsoft/DebugMCP&type=Date&theme=dark" />
  492. <source media="(prefers-color-scheme: light)" srcset="https://star-history.dera.page/svg?repos=microsoft/DebugMCP&type=Date" />
  493. <img alt="Star History Chart" src="https://star-history.dera.page/svg?repos=microsoft/DebugMCP&type=Date" />
  494. </picture>
  495. </a>
  496. ## License
  497. MIT License - See [LICENSE](LICENSE.txt) for details

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.