MCP server DebugMCP

DebugMCP (MCP Server) - Empowering AI Agents with Operational Debugging Capabilities

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.

🚀 DebugMCP CLI is now available on npm! Debug directly from the terminal without requiring VS Code or any IDE at all by connecting AI coding agents to explicitly configured Debug Adapter Protocol (DAP) adapters. The debug adapter and target process run in the background. Install it with npm install --global debugmcp, then run debugmcp configure --agent copilot-cli. The CLI also installs the debug-live skill automatically. View the package on npm

⭐ If you find DebugMCP useful, please star the repo on GitHub! It helps others discover the project and motivates continued development.

📢 Developers Notice: This extension is maintained by ozzafar@microsoft.com and orbarila@microsoft.com. We welcome feedback and contributions to help improve this extension.

🎬 Watch DebugMCP in action — your AI assistant autonomously sets breakpoints, steps through code, and inspects variables directly in VS Code.

✨ What's New

2.4

• Standalone DebugMCP CLI — install 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.

2.2

• Cross-agent debug-live skill install — the systematic debugging workflow ships as an Agent Skill 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, 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.
• 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.
• 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.).

🚀 Quick Install

Install DebugMCP from VS Code Marketplace or use the direct link: vscode:extension/ozzafar.debugmcpextension

Install DebugMCP from Open VSX Registry

Install debugmcp-cli from npm

Table of Contents

• Overview
• Features
• Installation
• Quick Start
• Supported AI Assistants
• Supported Languages
• Configuration
• FAQ
• Troubleshooting
• How It Works
• Contributing
• License

Overview

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.

Features

🔧 Tools

Tool	Description	Parameters
start_debugging	Start a debug session for a source code file	fileFullPath (required)workingDirectory (required)testName (optional)configurationName (optional)
stop_debugging	Stop the current debug session	None
step_over	Execute the next line (step over function calls)	None
step_into	Step into function calls	None
step_out	Step out of the current function	None
continue_execution	Continue until next breakpoint	None
pause_execution	Interrupt a freely-running program and stop at its current location (no breakpoint needed)	None
restart_debugging	Restart the current debug session; a fresh stop without acknowledgement returns an explicit completion-unconfirmed result, not confirmed success	None
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)
get_debug_output	Read captured output for one session; requires user-enabled capture and at least one filter	sessionId (required)prefix and/or category (required filter; both are ANDed)cursor (optional)limit (optional, 1-100)
add_breakpoint	Add a breakpoint at a specific line (optionally conditional)	fileFullPath (required)line (required, 1-based)condition (optional)
add_logpoint	Add a logpoint that logs a message (instead of pausing) when a line is reached	fileFullPath (required)line (required, 1-based)logMessage (required, {expr} interpolated)condition (optional)
remove_breakpoint	Remove a breakpoint from a specific line	fileFullPath (required)line (required)
clear_all_breakpoints	Remove all breakpoints at once	None
list_breakpoints	List all active breakpoints	None
list_variable_names	List names and types of variables in scope, without reading any values	scope (optional: 'local', 'global', 'all')
get_variables_values	Get the values of specifically named variables at the current execution point	variableNames (required, e.g. ["user","response"])scope (optional: 'local', 'global', 'all')
evaluate_expression	Evaluate an expression in debug context; expandable children are listed by name and type without their values	expression (required)

Note: The MCP server exposes tools for debugger actions, while the procedural workflow guidance (when to debug, how to structure a root-cause investigation, language-specific quirks) lives in the companion Agent Skill. Tool descriptions stay terse and behavioral; the extension installs the debug-live skill into the standard skills directories (~/.agents/skills/, plus ~/.copilot/skills/ when present) so skills-compatible harnesses load the full workflow on demand. The server also advertises MCP instructions pointing agents at it before debugging.

Debug output capture

To read logpoint messages without pausing the program, enable debugmcp.captureDebugOutput in VS Code user settings before output is emitted. For the standalone CLI host, start it with debugmcp serve --capture-output. Capture is off by default, and MCP tools cannot enable it.

Obtain sessionId from get_debug_status while the session is active, then call get_debug_output, for example:

{
  "sessionId": "<session-id-from-get_debug_status>",
  "prefix": "[orders]",
  "limit": 20
}

Provide a nonempty prefix (up to 256 characters), a category (console, stdout, stderr, or important), or both. Reuse the returned nextCursor as cursor with the same filters to read new entries; hasMore indicates additional entries to scan, and truncated reports evicted history. Only DAP output events are captured, not existing Debug Console contents.

Output stays in memory, bounded to 8 sessions and 1,000 events/256 KiB per session. Events over 8 KiB are replaced by an omission marker. History can remain after termination until eviction, but changing the capture setting or disposing the host clears it; output is not persisted or logged by the capture feature. Credential-pattern redaction happens before retention, but is heuristic and event-local, not a guarantee that every secret is removed. Enable capture only for output you intend to make available to the agent.

🎯 Debugging Best Practices

DebugMCP follows systematic debugging practices for effective issue resolution:

• Start with Entry Points: Begin debugging at function entry points or main execution paths
• Follow the Execution Flow: Use step-by-step execution to understand code flow
• Root Cause Analysis: Don't stop at symptoms - find the underlying cause

🛡️ Security & Reliability

• Secure Communication: All MCP communications use secure protocols
• Local Operation: The MCP server runs 100% locally with no external communications and requires no credentials
• State Validation: Robust validation of debugging states and operations

Installation

Standalone CLI (preview)

The standalone host talks directly to explicitly configured DAP adapters and does not require VS Code. It never discovers, downloads, installs, or selects an adapter automatically.

Install the published package:

npm install --global debugmcp

For repository development, build and invoke the local bundle:

npm install
npm run package
node dist/debugmcp.js adapter add python --command "python -m debugpy.adapter"
node dist/debugmcp.js adapter validate python
node dist/debugmcp.js configure

Adapter registrations are stored in .debugmcp.json by default. Add --user to adapter add, adapter list, or adapter remove to use the per-user configuration. Project registrations override registrations with the same name in user configuration.

Language shorthands derive the DAP type and file extensions for python, csharp, dotnet, cpp, c, javascript, typescript, node, java, go, rust, ruby, php, swift, and dart. These are configuration conveniences, not a language support boundary. The command remains explicit so the selected environment determines which adapter installation is used. Languages without a shorthand provide --type and --extensions explicitly. Compiled-language registrations can provide the executable in --launch; values support ${workspaceFolder}, ${file}, ${fileDirname}, and ${fileBasenameNoExtension}.

The current CLI supports adapters that speak DAP over stdio. A registration can provide adapter-specific launch properties with --launch followed by a JSON object. If multiple registered adapters claim the same file extension, start_debugging.configurationName must identify the adapter to use. Test discovery remains host-specific; configure the adapter launch properties to run the required test command.

Adapter arguments beginning with -- can follow --args directly. Use a standalone -- after --args when an adapter argument has the same name as a DebugMCP option, for example --args -- --user.

debugmcp configure presents the same agent choices as the VS Code extension's setup popup and writes the standalone stdio command for every selected agent. In automation, repeat --agent <id> to bypass the terminal prompt, for example debugmcp configure --agent copilot-cli --agent codex. Each configuration has one canonical debugmcp entry, so configuring the CLI replaces an existing extension HTTP entry rather than registering both. The command also installs the bundled debug-live skill into the standard personal skills directories. Restart configured agents to discover it.

Use debugmcp status to inspect the GitHub Copilot CLI registration. The DebugMCP command configures only the standalone CLI. To use the interactive VS Code version, configure it through the DebugMCP extension's agent popup; the command line does not select or configure the extension.

Quick Install Options

Option 1: Direct Link (Fastest)

• Click this link: vscode:extension/ozzafar.debugmcpextension
• Or copy and paste in your browser: vscode:extension/ozzafar.debugmcpextension

Option 2: VS Code Marketplace

• Visit: https://marketplace.visualstudio.com/items?itemName=ozzafar.debugmcpextension
• Click "Install"

Option 3: Within VS Code

1. Open VSCode
2. Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
3. Search for "DebugMCP"
4. Click Install
5. The extension automatically activates and registers as an MCP server

Verification

After installation, you should see:

• DebugMCP extension in your installed extensions
• MCP server automatically running on port 3001 (configurable)
• Debug tools available to connected AI assistants

📝 Note: No additional debugging rule instructions are needed - the extension works out of the box.

💡 Tip: Enable auto-approval for all debugmcp tools in your AI assistant to create seamless debugging workflows without constant approval interruptions.

Quick Start

1. Install the extension (see Installation)
2. Open your project in VSCode
3. Ask your AI to debug - it can now set breakpoints, start debugging, and analyze your code!

Supported AI Assistants

DebugMCP works with any MCP-compatible AI assistant. It auto-detects and offers to register itself with:

Assistant	Auto-Registration	Manual Config
GitHub Copilot	✅	See config
GitHub Copilot CLI	✅	See config
Claude Code	✅	See config
Cline	✅	See config
Cursor	✅	See config
Codex	✅	See config
Windsurf	✅	See config
Roo Code	✅	See config
Antigravity	✅	See config
Any MCP-compatible assistant	—	See manual setup

Supported Languages

DebugMCP supports debugging for the following languages with their respective VSCode extensions:

Language	Extension Required	File Extensions	Status
Python	Python	.py	✅ Fully Supported
JavaScript/TypeScript	Built-in / JS Debugger	.js, .ts, .jsx, .tsx	✅ Fully Supported
Java	Extension Pack for Java	.java	✅ Fully Supported
C/C++	C/C++	.c, .cpp, .cc	✅ Fully Supported
Go	Go	.go	✅ Fully Supported
Rust	rust-analyzer	.rs	✅ Fully Supported
PHP	PHP Debug	.php	✅ Fully Supported
Ruby	Ruby	.rb	✅ Fully Supported
C#/.NET	C#	.cs, .csproj	✅ Fully Supported

Configuration

MCP Server Configuration (Recommended)

The extension runs an MCP server automatically. It will pop up a message to auto-register the MCP server in your AI assistant.

You can also trigger the registration manually via the Command Palette:

• DebugMCP: Show Agent Selection Popup

Manual MCP Server Registration (Optional)

🔄 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.

Cline

Add to your Cline settings or cline_mcp_settings.json:

{
  "mcpServers": {
    "debugmcp": {
      "type": "streamableHttp",
      "url": "http://localhost:3001/mcp",
      "description": "DebugMCP - AI-powered debugging assistant"
    }
  }
}

GitHub Copilot

Add to your VS Code settings (settings.json):

{
  "mcp": {
    "servers": {
      "debugmcp": {
        "type": "http",
        "url": "http://localhost:3001/mcp",
        "description": "DebugMCP - Multi-language debugging support"
      }
    }
  }
}

GitHub Copilot CLI

Add to ~/.copilot/mcp-config.json (${COPILOT_HOME}/mcp-config.json if COPILOT_HOME is set):

{
  "mcpServers": {
    "debugmcp": {
      "type": "http",
      "url": "http://localhost:3001/mcp",
      "tools": ["*"]
    }
  }
}

Claude Code

Register DebugMCP with Claude Code:

claude mcp add --transport http --scope user debugmcp http://localhost:3001/mcp

Or add the equivalent configuration to ~/.claude.json (top-level mcpServers, for cross-project user-scope access — see the Claude Code MCP docs):

{
  "mcpServers": {
    "debugmcp": {
      "type": "http",
      "url": "http://localhost:3001/mcp"
    }
  }
}

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.

Cursor

Add to Cursor's MCP settings:

{
  "mcpServers": {
    "debugmcp": {
      "type": "streamableHttp",
      "url": "http://localhost:3001/mcp",
      "description": "DebugMCP - Debugging tools for AI assistants"
    }
  }
}

Codex

Register DebugMCP with Codex:

codex mcp add debugmcp --url http://localhost:3001/mcp

Or add the equivalent configuration to ~/.codex/config.toml (${CODEX_HOME}/config.toml if CODEX_HOME is set):

[mcp_servers.debugmcp]
url = "http://localhost:3001/mcp"

Windsurf

Add to Windsurf's MCP settings (~/.windsurf/mcp_settings.json or workspace .windsurf/mcp_settings.json):

{
  "mcpServers": {
    "debugmcp": {
      "type": "streamableHttp",
      "url": "http://localhost:3001/mcp",
      "description": "DebugMCP - Debugging tools for AI assistants"
    }
  }
}

Roo Code

Add to Roo Code's MCP settings:

{
  "mcpServers": {
    "debugmcp": {
      "type": "streamableHttp",
      "url": "http://localhost:3001/mcp",
      "description": "DebugMCP - Debugging tools for AI assistants"
    }
  }
}

Antigravity

Add to Antigravity's MCP settings:

{
  "mcpServers": {
    "debugmcp": {
      "type": "streamableHttp",
      "url": "http://localhost:3001/mcp",
      "description": "DebugMCP - Debugging tools for AI assistants"
    }
  }
}

Extension Settings

Configure DebugMCP behavior in VSCode settings:

{
  "debugmcp.serverPort": 3001,
  "debugmcp.timeoutInSeconds": 180,
  "debugmcp.bindHost": ["127.0.0.1", "::1"],
  "debugmcp.captureDebugOutput": false
}

Setting	Default	Description
debugmcp.serverPort	3001	Port number for the MCP server
debugmcp.timeoutInSeconds	180	Timeout for debugging operations
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 before changing.
debugmcp.captureDebugOutput	false	User-controlled, machine-scoped capture of bounded debugger output. See Debug output capture; agents cannot enable capture through MCP.

Security model

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:

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.
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.
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.
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.