MCP Debugger

create_debug_session

Start a debugging session to launch or attach to a running process for step-through debugging. Pass a port, processId, or debugger URI to attach in the same call.

Instructions

Create a new debugging session. Passing port, processId or an adapterConfig that names a target (a debugger URI: vmServiceUri, websocketAddress, vmServiceInfoFile; or a Flutter deviceId, for an app running on an Android device) attaches to a running process in the same call, with every attach argument attach_to_process takes (host alone does not); omit them for launch mode. Attaching pauses the target unless stopOnEntry is false

Input Schema

Name	Required	Description
`host`	No	Attach mode only: host to attach to (the adapter defaults it, usually 127.0.0.1). Does not trigger attach mode by itself
`name`	No	Optional session name
`port`	No	Debug port to attach to (triggers attach mode)
`timeout`	No	Attach mode only: connection timeout in milliseconds, forwarded as-is; js-debug honours it (its own default is 10 s) and COBOL uses it as its manifest-build budget, the other adapters ignore it. A value longer than verifyTimeout means the verify deadline is what you hit
`language`	Yes	Programming language for debugging
`processId`	No	Process ID for local attach, language-specific (triggers attach mode)
`justMyCode`	No	Attach mode only: only debug user code (skip library code)
`sourcePaths`	No	Attach mode only: source paths for code mapping
`stopOnEntry`	No	Attach mode only: same as attach_to_process.stopOnEntry — omitted means true, the target is paused after attach (possibly late, reported as pending:true). Pass false to attach to a live service without stopping it
`adapterConfig`	No	Attach mode only: adapter-specific attach configuration merged into the attach config (see attach_to_process). Triggers attach mode when it names a debugger URI (vmServiceUri, websocketAddress) or vmServiceInfoFile
`verifyTimeout`	No	Attach mode only: how long to wait (ms) for the debugger to report at least one thread after attaching before failing the attach (default: 20000, max: 600000)
`executablePath`	No	Path to language executable (optional, will auto-detect if not provided)
`breakOnExceptions`	No	Attach mode only: break when exceptions are thrown: "uncaught" pauses at uncaught exceptions at the crash site; "all" also pauses on caught/raised exceptions (language-dependent). Default "none" — attach sessions never apply a language default (unlike launch)

Schema Changelog

Changes observed during successful MCP inspections.

Changed9 schema fields changedv0.26.0Oct 31, 2026

changedInput schema / properties / adapterConfig / description

Previous value: -"Attach mode only: adapter-specific attach configuration merged into the attach config (see attach_to_process)"New value: +"Attach mode only: adapter-specific attach configuration merged into the attach config (see attach_to_process). Triggers attach mode when it names a debugger URI (vmServiceUri, websocketAddress) or vmServiceInfoFile"

addedInput schema / properties / breakOnExceptions

Added value: +{
+  "description": "Attach mode only: break when exceptions are thrown: \"uncaught\" pauses at uncaught exceptions at the crash site; \"all\" also pauses on caught/raised exceptions (language-dependent). Default \"none\" — attach sessions never apply a language default (unlike launch)",
+  "enum": [
+    "uncaught",
+    "all",
+    "none"
+  ],
+  "type": "string"
+}

changedInput schema / properties / host / description

Previous value: -"Host to attach to for remote debugging (optional, triggers attach mode)"New value: +"Attach mode only: host to attach to (the adapter defaults it, usually 127.0.0.1). Does not trigger attach mode by itself"

addedInput schema / properties / justMyCode

Added value: +{
+  "description": "Attach mode only: only debug user code (skip library code)",
+  "type": "boolean"
+}

changedInput schema / properties / language / enum

Previous value: -[
-  "mock",
-  "python",
-  "javascript",
-  "ruby",
-  "rust",
-  "go",
-  "java",
-  "dotnet",
-  "cpp",
-  "cobol"
-]New value: +[
+  "mock",
+  "python",
+  "javascript",
+  "ruby",
+  "rust",
+  "go",
+  "java",
+  "dotnet",
+  "cpp",
+  "cobol",
+  "dart"
+]

changedInput schema / properties / port / description

Previous value: -"Debug port to attach to for remote debugging (optional, triggers attach mode)"New value: +"Debug port to attach to (triggers attach mode)"

addedInput schema / properties / processId

Added value: +{
+  "description": "Process ID for local attach, language-specific (triggers attach mode)",
+  "type": [
+    "number",
+    "string"
+  ]
+}

addedInput schema / properties / sourcePaths

Added value: +{
+  "description": "Attach mode only: source paths for code mapping",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

changedInput schema / properties / timeout / description

Previous value: -"Connection timeout in milliseconds for attach mode (default: 30000)"New value: +"Attach mode only: connection timeout in milliseconds, forwarded as-is; js-debug honours it (its own default is 10 s) and COBOL uses it as its manifest-build budget, the other adapters ignore it. A value longer than verifyTimeout means the verify deadline is what you hit"

Changed4 schema fields changedv0.25.1Sep 30, 2026

addedInput schema / properties / adapterConfig

Added value: +{
+  "additionalProperties": true,
+  "description": "Attach mode only: adapter-specific attach configuration merged into the attach config (see attach_to_process)",
+  "type": "object"
+}

changedInput schema / properties / language / enum

Previous value: -[
-  "mock",
-  "python",
-  "javascript",
-  "rust",
-  "go",
-  "java",
-  "dotnet"
-]New value: +[
+  "mock",
+  "python",
+  "javascript",
+  "ruby",
+  "rust",
+  "go",
+  "java",
+  "dotnet",
+  "cpp",
+  "cobol"
+]

addedInput schema / properties / stopOnEntry

Added value: +{
+  "description": "Attach mode only: same as attach_to_process.stopOnEntry — omitted means true, the target is paused after attach (possibly late, reported as pending:true). Pass false to attach to a live service without stopping it",
+  "type": "boolean"
+}

addedInput schema / properties / verifyTimeout

Added value: +{
+  "description": "Attach mode only: how long to wait (ms) for the debugger to report at least one thread after attaching before failing the attach (default: 20000, max: 600000)",
+  "type": "number"
+}

Changed4 schema fields changedv0.20.0May 4, 2026

addedInput schema / properties / host

Added value: +{
+  "description": "Host to attach to for remote debugging (optional, triggers attach mode)",
+  "type": "string"
+}

changedInput schema / properties / language / enum

Previous value: -[
-  "mock",
-  "python",
-  "javascript",
-  "rust"
-]New value: +[
+  "mock",
+  "python",
+  "javascript",
+  "rust",
+  "go",
+  "java",
+  "dotnet"
+]

addedInput schema / properties / port

Added value: +{
+  "description": "Debug port to attach to for remote debugging (optional, triggers attach mode)",
+  "type": "number"
+}

addedInput schema / properties / timeout

Added value: +{
+  "description": "Connection timeout in milliseconds for attach mode (default: 30000)",
+  "type": "number"
+}

First observedDec 29, 2025

TDQS

A3.6/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description bears full disclosure burden. It does surface a real side effect ('Attaching pauses the target unless stopOnEntry is false') and the mode-selection semantics, but says nothing about session lifecycle, failure behavior, or what a created session yields, which matters for a 13-param stateful tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded in the first clause, followed by the mode rule. The long nested parenthetical listing debugger URIs is dense but each clause carries real information; nothing is filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 13 parameters, no annotations, and no output schema, the description covers mode selection but not the return value (presumably a session reference used by list_debug_sessions/close_debug_session) or error/pending outcomes beyond a brief nod to pending:true in the schema. Adequate but notably thin for a tool this complex.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so every parameter is already documented (including 'triggers attach mode' and stopOnEntry's default). The description's added value is the cross-parameter synthesis — grouping port/processId/adapterConfig as the attach trigger set and noting host alone is insufficient — plus the Flutter deviceId example, but most individual claims restate the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Create a new debugging session') and explains the two modes (launch vs. attach) that the tool spans. It names attach_to_process as the related sibling and clarifies that this tool can do attach in one call, but it never contrasts with start_debugging, so the launch-mode boundary is left implicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit trigger rule: supplying port, processId, or a target-naming adapterConfig selects attach mode; omitting them selects launch mode, and 'host alone does not' trigger attach. What's missing is when to call create_debug_session instead of attach_to_process or start_debugging directly — the alternative is referenced but never routed to.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_debug_session

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools