MCP Debugger

attach_to_process

Attach a debugger to a running process for live debugging. Verifies target by polling for threads; fails if none appear within timeout.

Instructions

Attach to a running process for debugging. After the handshake the target is verified by polling for threads; if none are reported within verifyTimeout (~20s default) the attach fails and the proxy is torn down. When a requested post-attach pause is accepted but no stopped event arrives within its bounded wait, returns state "running" with pending:true; the late event alone changes the session to "paused"

Input Schema

TableJSON Schema

Name	Required	Description
`host`	No	Host to attach to (default: localhost)
`port`	No	Debug port to attach to
`timeout`	No	Connection timeout in milliseconds (default: 30000)
`processId`	No	Process ID (for local attach, language-specific)
`sessionId`	Yes	Debug session ID
`justMyCode`	No	Only debug user code (skip library code)
`sourcePaths`	No	Source paths for code mapping
`stopOnEntry`	No	Pause the target after attaching. Default true when omitted (thread verification, then a pause request; if the stop lands after the response you get pending:true and the target still freezes on its next dispatch). Pass false to attach without stopping — required when attaching to a live service
`adapterConfig`	No	Adapter-specific attach configuration merged into the attach config before the adapter transforms it (e.g. C/C++/LLDB: program — the binary path for symbol resolution when /proc/<pid>/maps paths are not openable, as in a kubectl-debug ephemeral container — or initCommands like "settings set target.exec-search-paths /proc/<pid>/root"). Reserved keys request/__attachMode are ignored; set stopOnEntry via the top-level parameter. Keys the adapter does not recognize are still forwarded to the debugger and named in the response warning — a near-miss of a supported key gets a did-you-mean suggestion. js-debug pins its attach orchestration keys (address/port/continueOnAttach/attachExistingChildren) over caller values; its autoAttachChildProcesses defaults to false on attach — child processes the target forks run undebugged (set it true to auto-attach children; only one child can be adopted at a time, further children are resumed undebugged)
`verifyTimeout`	No	How long to wait (ms) for the debugger to report at least one thread after attaching before failing the attach (default: 20000, max: 600000). Decrease for fast failure-by-design probes; increase for targets that are exceptionally slow to become debuggable
`breakOnExceptions`	No	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.

Changed4 schema fields changedv0.25.1Sep 30, 2026

addedInput schema / properties / adapterConfig

Added value: +{
+  "additionalProperties": true,
+  "description": "Adapter-specific attach configuration merged into the attach config before the adapter transforms it (e.g. C/C++/LLDB: program — the binary path for symbol resolution when /proc/<pid>/maps paths are not openable, as in a kubectl-debug ephemeral container — or initCommands like \"settings set target.exec-search-paths /proc/<pid>/root\"). Reserved keys request/__attachMode are ignored; set stopOnEntry via the top-level parameter. Keys the adapter does not recognize are still forwarded to the debugger and named in the response warning — a near-miss of a supported key gets a did-you-mean suggestion. js-debug pins its attach orchestration keys (address/port/continueOnAttach/attachExistingChildren) over caller values; its autoAttachChildProcesses defaults to false on attach — child processes the target forks run undebugged (set it true to auto-attach children; only one child can be adopted at a time, further children are resumed undebugged)",
+  "type": "object"
+}

addedInput schema / properties / breakOnExceptions

Added value: +{
+  "description": "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 / stopOnEntry / description

Previous value: -"Stop on entry after attaching"New value: +"Pause the target after attaching. Default true when omitted (thread verification, then a pause request; if the stop lands after the response you get pending:true and the target still freezes on its next dispatch). Pass false to attach without stopping — required when attaching to a live service"

addedInput schema / properties / verifyTimeout

Added value: +{
+  "description": "How long to wait (ms) for the debugger to report at least one thread after attaching before failing the attach (default: 20000, max: 600000). Decrease for fast failure-by-design probes; increase for targets that are exceptionally slow to become debuggable",
+  "type": "number"
+}

Addedv0.20.0May 4, 2026

TDQS

B3.2/5.0

Behavior3/5

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

With no annotations, the description carries the full burden, and it does disclose real behavior: a thread-polling handshake, attach failure plus proxy teardown on verifyTimeout, and the async pending:true pause semantics. However, it omits other behavioral essentials for a mutation-style session tool, such as required permissions or what the response object contains. Solid partial disclosure, not complete.

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

Conciseness3/5

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

The purpose is correctly front-loaded in a short first sentence. The second sentence, however, is a dense run-on with nested clauses ('accepted but no stopped event arrives within its bounded wait... pending:true; the late event alone changes the session...') that is hard to parse for what is essentially a two-state edge case. Informative but structurally heavy.

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

Completeness4/5

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

For an 11-parameter tool with a nested adapterConfig object, the description plus the very rich schema entries cover most of what an agent needs, and no output schema exists so return-state description (running/paused, pending) is a genuine plus. The gap is that overall response shape and side-effect scope are not summarized, leaving it just short of fully self-sufficient.

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 description coverage is 100%, so the schema already documents all 11 parameters in depth. The description's mentions of verifyTimeout (~20s default) and post-attach pause duplicate what the schema says rather than adding syntax or meaning beyond it. Baseline 3 applies.

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?

The description opens with a specific verb and resource: 'Attach to a running process for debugging.' That clearly separates it from siblings like launch-oriented tools and from detach_from_process. It stops short of naming which sibling to use instead (e.g. create_debug_session or start_debugging), so it is clear but not differentiating.

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

Usage Guidelines2/5

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

There is no when-to-use guidance in the description itself: no prerequisites, no statement of when attaching is preferable to launching, and no named alternative. The useful conditional advice ('required when attaching to a live service') lives in the stopOnEntry schema entry, not the description. An agent gets context only by reading the schema.

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

attach_to_process

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools