MCP Debugger

attach_to_process

Attach a debug session to a running process by host, port, or process ID, verify threads, and optionally pause on entry for step-through debugging.

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" — call wait_for_stop to block until it does

Input Schema

Name	Required	Description
`host`	No	Host to attach to; the adapter defaults it, usually 127.0.0.1
`port`	No	Debug port to attach to
`timeout`	No	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
`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.

Changed2 schema fields changedv0.26.0Oct 31, 2026

changedInput schema / properties / host / description

Previous value: -"Host to attach to (default: localhost)"New value: +"Host to attach to; the adapter defaults it, usually 127.0.0.1"

changedInput schema / properties / timeout / description

Previous value: -"Connection timeout in milliseconds (default: 30000)"New value: +"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": "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

A4.3/5.0

Behavior5/5

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

With no annotations, the description carries the full burden and does: the thread-polling verification handshake, the ~20s verifyTimeout failure path that tears down the proxy, and the pending:true / 'running' state that only a late stop event transitions to 'paused.' It also discloses that unrecognized adapterConfig keys are forwarded and reported in a response warning, and that js-debug pins its own orchestration keys.

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, and every subsequent sentence carries real behavioral content with no filler. The dense em-dash-heavy sentences and nested parentheticals make it harder to scan than it needs to be, keeping it from a 5.

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

Completeness5/5

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

For an 11-parameter, nested-object tool with no annotations and no output schema, the description covers the failure mode, the asynchronous state model, and the follow-up tool an agent must call. Nothing needed to invoke it correctly or interpret a pending response is missing.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema doesn't: the interaction where a late stop yields pending:true with the target still freezing on next dispatch, and the timeout-vs-verifyTimeout precedence. That extra state semantics is enough to lift it above baseline.

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?

Opens with a specific verb+resource: 'Attach to a running process for debugging,' which implicitly contrasts with the launch path (start_debugging) among the siblings. It does not explicitly name a sibling or state the attach-vs-launch decision, so it stops short of 5.

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?

Gives concrete routing guidance: it names wait_for_stop as the tool to call when the post-attach pause lands late, and warns that stopOnEntry must be false 'when attaching to a live service.' It never states when to choose attach over start_debugging, so it lacks a full when/when-not framing.

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