Skip to main content
Most debugger operations are scoped by session_id. Create or pick a session first, then load a binary or attach to a running process.
Except for create_debug_session and list_debug_sessions, the debugger tool family expects an existing session. Use explicit session names for every serious workflow.

​
Session lifecycle tools

ToolUse it forNotes
create_debug_sessioncreate or return a session by idsafe to call repeatedly
list_debug_sessionsinspect active sessionsreturns metadata for all sessions
close_debug_sessionclose a session and stop its pwncli driverreleases GDB resources
get_session_infoinspect cached state without issuing a new GDB commandincludes runtime_dir
{"tool":"create_debug_session","arguments":{"session_id":"chal-a"}}
{"tool":"list_debug_sessions","arguments":{}}
{"tool":"get_session_info","arguments":{"session_id":"chal-a"}}

​
Load, attach, and raw command tools

ToolUse it forNotes
set_fileload an executable into GDBresolve paths under /workspace
attachattach to an already running PIDreturns attach result plus context snapshots
set_breakpointinsert a symbol, address, or file:line breakpointoptional condition supported
executerun raw GDB or pwndbg commandsbest for low-level escape hatches
{"tool":"set_file","arguments":{"binary_path":"/workspace/chal","session_id":"chal-a"}}
{"tool":"set_breakpoint","arguments":{"location":"main","condition":"$rax == 0","session_id":"chal-a"}}
{"tool":"execute","arguments":{"command":"info registers","session_id":"chal-a"}}

​
Common debugger parameters

​
session_id
string
required
Debug session to operate on. Required for nearly every debugger tool on this page.
​
binary_path
string
Target binary path. Use a path that resolves under /workspace.
​
location
string
Breakpoint or jump target, such as a symbol, file:line, or address expression.
​
command
string
Raw GDB or pwndbg command for execute, or a stepping verb such as c, n, s, ni, or si for step_control.
​
args
string
Argument string passed to the inferior when using run.
​
pid
number
Target process id for attach.

​
Execution control tools

ToolUse it forNotes
runstart the loaded inferiorsupports args and start
step_controlcontinue or step executionsupports c, n, s, ni, si
gdb_polldrain pending async GDB notificationsuseful after async activity
gdb_interruptinterrupt a running inferior and wait for stop eventsuseful when you need control back
finishrun until the current function returnswrapper around MI -exec-finish
jumpresume execution at a locationsupports symbol, file:line, or address
return_from_functionforce the current function to returnwrapper around MI -exec-return
untilrun until a location or next source lineoptional locspec
{"tool":"run","arguments":{"args":"--demo","start":true,"session_id":"chal-a"}}
{"tool":"step_control","arguments":{"command":"ni","session_id":"chal-a"}}
{"tool":"gdb_interrupt","arguments":{"timeout":1.0,"session_id":"chal-a"}}
{"tool":"until","arguments":{"locspec":"main","session_id":"chal-a"}}

​
Typical flow

1

Create the session

{"tool":"create_debug_session","arguments":{"session_id":"chal-a"}}
2

Load the binary and stop at main

{"tool":"set_file","arguments":{"binary_path":"/workspace/chal","session_id":"chal-a"}}
{"tool":"set_breakpoint","arguments":{"location":"main","session_id":"chal-a"}}
{"tool":"run","arguments":{"session_id":"chal-a"}}
3

Inspect and continue

{"tool":"execute","arguments":{"command":"info registers","session_id":"chal-a"}}
{"tool":"step_control","arguments":{"command":"n","session_id":"chal-a"}}

​
Common edge cases

Create the session first with create_debug_session, then pass the same session_id on all later calls.
Load a file with set_file before calling run, or pass binary_path where the tool supports it.
The MCP attach tool returns the attach result plus a context snapshot list. If you want a single wrapper object instead, use the attach sidecar API described in Attach API.

​
Common debugger response fields

​
success
boolean
required
Whether the tool call succeeded.
​
session_id
string
Session that the tool actually operated on.
​
state
string
Current debugger or inferior state after the operation, when provided by the backend.
​
binary_path
string
Resolved binary path after set_file or other file-sensitive operations.
​
runtime_dir
string
Session-specific runtime directory returned by get_session_info.
​
error
string
Short actionable error message when the call fails.
​
type
string
Exception type returned by the shared error wrapper on failures.