vscode-debug-mcp

Let AI agents drive the VS Code debugger.

A two-part toolkit that gives coding agents (Claude Code, Cursor, Codex, or plain curl) full control of VS Code's debugging engine: set breakpoints, launch/attach sessions, step through code, inspect call stacks and variables, and evaluate expressions in the paused frame — all inside the editor the human is already looking at.

AI Agent ──(stdio MCP)──> MCP Server ──(HTTP 127.0.0.1:7779)──> VS Code Extension ──> vscode.debug API
   └──────────────(or plain curl, no MCP config needed)──────────────┘

Why an editor bridge instead of a standalone DAP client? The debug session lives in the user's VS Code window: breakpoints are visible, the paused file opens at the exact line, and the human can take over the Run and Debug UI at any moment. Agent and human share one debugging surface. This powers live "feature tour" walkthroughs where an agent narrates newly written code while stepping through it in a real app.

Setup

1. Install the VS Code extension

From the Marketplace / Open VSX (search "Debug MCP Bridge"), or from a local build:

code --install-extension vscode-debug-mcp-bridge-0.1.0.vsix   # cursor --install-extension works too

The bridge auto-starts when a window opens and binds 127.0.0.1:7779 (change via the debugMcpBridge.port setting). Command Palette: Debug MCP Bridge: Start Server / Stop Server.

Verify:

curl http://127.0.0.1:7779/health
# → {"status":"ok","version":"0.1.0"}

2. Configure the MCP server (optional)

Skip this if you prefer driving the bridge with plain HTTP — see Zero-config HTTP mode.

Claude Code (~/.claude.json or project .mcp.json):

{
  "mcpServers": {
    "vscode-debugger": {
      "command": "npx",
      "args": ["-y", "vscode-debug-mcp"]
    }
  }
}

Cursor (~/.cursor/mcp.json or project .cursor/mcp.json) uses the same shape. Codex (~/.codex/config.toml):

[mcp_servers.vscode-debugger]
command = "npx"
args = ["-y", "vscode-debug-mcp"]

Optional: set a custom bridge port with the VSCODE_DEBUG_PORT env var (default 7779).

Related MCP server: MCP JS Debugger

MCP tools

Zero-config HTTP mode

Everything the MCP server does is also reachable directly — useful for agents that can run shell commands but have no MCP configuration:

Example — attach to a running Chrome and break on a click handler:

curl -s -X POST http://127.0.0.1:7779/debug/launch -H "Content-Type: application/json" -d '{
  "config": {
    "type": "chrome", "request": "attach", "name": "agent attach",
    "port": 9222, "webRoot": "/abs/path/to/project",
    "urlFilter": "http://localhost:3000/*"
  }
}'
curl -s -X POST http://127.0.0.1:7779/breakpoint -d '{"file":"/abs/path/src/App.tsx","line":42}'
curl -s http://127.0.0.1:7779/state   # poll until "stopped"

Operational notes

• One window owns the port. The bridge binds 7779 per VS Code window; with multiple windows open, the first to activate wins. Paused files open in the owning window. Find the owner with ps -p $(lsof -t -iTCP:7779 -sTCP:LISTEN) -o command= (the workspace name appears in the process title), then stop/start the bridge via the Command Palette in the window you want.

• Start the bridge before launching debug sessions. The DAP tracker only observes sessions created after the bridge is running. If state looks stale after IDE-driven steps, call GET /state to re-sync.

• Single session (current limitation). Only the active debug session is tracked. Multi-session setups (e.g. Next.js server + client) follow the focused session — see TODO.md.

• The bridge listens on 127.0.0.1 only and is never exposed externally.

Development

pnpm install          # workspace root
pnpm typecheck        # both packages
pnpm build            # both packages
pnpm package          # build the .vsix (vscode-extension/)

# E2E (requires a VS Code window with this repo open and the bridge running)
cd e2e && node e2e-test.mjs

Releasing

# VS Code Marketplace + Open VSX (PATs injected via 1Password)
pnpm publish:stores:dry-run
pnpm publish:stores

# npm (mcp-server)
pnpm publish:npm

.env.1password maps VSCE_PAT / OVSX_PAT to 1Password items (op run injects them at publish time). The npm publish uses your logged-in npm account (npm login first).

License

MIT © Laststance.io