Debugging MCP servers in VS Code

Pattern 1: Launch with the MCP Inspector

The cleanest debugging workflow is to use the MCP Inspector as the client and have VS Code launch the server with the Node debugger enabled. This gives you full control — you can set breakpoints before the first tool call and step through initialization:

// .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug MCP Server (via Inspector)",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/dist/index.js",
      "runtimeArgs": ["--inspect-brk"],
      "env": {
        "DATABASE_URL": "postgres://localhost/mydb",
        "NODE_ENV": "development",
        "DEBUG": "mcp:*"
      },
      "outFiles": ["${workspaceFolder}/dist/**/*.js"],
      "sourceMaps": true,
      "console": "integratedTerminal",
      // Pipe stdin from the Inspector; stdout to Inspector
      // Run Inspector separately: npx @modelcontextprotocol/inspector node dist/index.js
      "preLaunchTask": "build"
    }
  ]
}

With --inspect-brk, the server pauses at startup until a debugger attaches. VS Code attaches automatically when you hit F5. Then in a separate terminal, run the MCP Inspector to connect as the client: npx @modelcontextprotocol/inspector node dist/index.js. Set breakpoints in your tool handlers and use the Inspector's playground to trigger tool calls — VS Code breaks on the breakpoint in your handler code.

Note: use --inspect-brk (break at start) during initialization debugging. Use --inspect (don't break at start) when you only want to break at a specific handler breakpoint.

TypeScript source maps

VS Code needs to map between compiled JavaScript (in dist/) and your TypeScript source (in src/) to show breakpoints on the right lines. Two approaches:

With ts-node (no build step)

{
  "name": "Debug MCP Server (ts-node)",
  "type": "node",
  "request": "launch",
  "runtimeExecutable": "node",
  "runtimeArgs": [
    "--loader", "ts-node/esm",
    "--inspect-brk"
  ],
  "program": "${workspaceFolder}/src/index.ts",
  "env": {
    "TS_NODE_PROJECT": "${workspaceFolder}/tsconfig.json",
    "DATABASE_URL": "postgres://localhost/mydb"
  },
  "sourceMaps": true,
  "console": "integratedTerminal"
}

ts-node transpiles TypeScript on the fly and generates inline source maps, so VS Code can show breakpoints in the .ts source directly. No build step needed — faster iteration during debugging.

With compiled output (tsc)

{
  "name": "Debug MCP Server (compiled)",
  "type": "node",
  "request": "launch",
  "program": "${workspaceFolder}/dist/index.js",
  "runtimeArgs": ["--inspect-brk"],
  "outFiles": ["${workspaceFolder}/dist/**/*.js"],
  "sourceMaps": true,
  "env": { "DATABASE_URL": "postgres://localhost/mydb" },
  "preLaunchTask": "tsc: build - tsconfig.json"
}

Ensure your tsconfig.json has "sourceMap": true (not inlineSourceMap) and "outDir": "./dist". VS Code finds the .map files in dist/ and maps line numbers back to your TypeScript source.

Pattern 2: Attach to a running server

If the server is already running under Claude Desktop and you want to debug a live issue, use the attach pattern. Add the --inspect flag to your Claude Desktop config and then attach VS Code:

// claude_desktop_config.json — add --inspect to the server's node args
{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["--inspect=9229", "/absolute/path/to/dist/index.js"],
      "env": {
        "DATABASE_URL": "postgres://localhost/mydb"
      }
    }
  }
}

// .vscode/launch.json — attach to the running process
{
  "name": "Attach to MCP Server",
  "type": "node",
  "request": "attach",
  "port": 9229,
  "localRoot": "${workspaceFolder}",
  "remoteRoot": "${workspaceFolder}",
  "outFiles": ["${workspaceFolder}/dist/**/*.js"],
  "sourceMaps": true,
  "restart": true  // re-attach if server restarts
}

Restart Claude Desktop after changing claude_desktop_config.json. The server starts with the debugger listening on port 9229. Hit F5 in VS Code to attach — you'll see "Debugger attached" in the VS Code debug console. Now set a breakpoint in a tool handler and ask Claude to call that tool — VS Code breaks on the breakpoint with the full call stack.

Setting effective breakpoints

MCP tool handlers are async functions called from the MCP SDK's request dispatcher. Breakpoints work the same as in any async Node.js code, but a few patterns are worth knowing:

• Break at tool call entry: set the breakpoint on the first line of the handler function body — after the function signature, before any async operations. This lets you inspect the incoming args object before any processing.
• Break on error: use VS Code's "Uncaught Exceptions" breakpoint (the breakpoints panel → "Add Exception Breakpoint") to break automatically when the handler throws. This is faster than manually placing breakpoints on every error path.
• Inspect args: in the VS Code Variables panel, expand the args object to see every argument the AI model sent. This is the ground truth for what Claude actually sent vs what you expected.
• Step through async code: use "Step Over" (F10) to skip await calls and "Step Into" (F11) to enter the awaited function. VS Code handles async stack traces correctly in Node 22+.

Using the VS Code MCP Output panel

VS Code (with the MCP extension or as a built-in MCP client) shows raw protocol messages in an Output panel. To access it: open the Command Palette (Cmd+Shift+P), type "MCP", and look for "MCP: Show Output" or check the Output dropdown for an "MCP" channel.

The MCP Output panel shows:

• The initialize request/response pair — useful for verifying capability negotiation
• The tools/list response — the exact tool manifest VS Code received
• Each tools/call request and response — the raw JSON-RPC for every tool invocation
• Protocol errors — if the server returns a JSON-RPC error, it appears here with the error code and message

The Output panel shows client-side events — what VS Code sent and received. Your server's stderr output appears in the server process's terminal or in the VS Code launch console, not in the MCP Output panel.

Common VS Code MCP debugging issues

Related pages

• Debug logging for MCP servers
• MCP Inspector tool
• Debugging stdio transport MCP servers
• TypeScript-specific MCP debugging
• Debugging MCP servers in Cursor