Debug Sessions

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

Tool	Use it for	Notes
`create_debug_session`	create or return a session by id	safe to call repeatedly
`list_debug_sessions`	inspect active sessions	returns metadata for all sessions
`close_debug_session`	close a session and stop its `pwncli` driver	releases GDB resources
`get_session_info`	inspect cached state without issuing a new GDB command	includes `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

Tool	Use it for	Notes
`set_file`	load an executable into GDB	resolve paths under `/workspace`
`attach`	attach to an already running PID	returns attach result plus context snapshots
`set_breakpoint`	insert a symbol, address, or `file:line` breakpoint	optional condition supported
`execute`	run raw GDB or pwndbg commands	best 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

string

required

Debug session to operate on. Required for nearly every debugger tool on this page.

string

Target binary path. Use a path that resolves under /workspace.

string

Breakpoint or jump target, such as a symbol, file:line, or address expression.

string

Raw GDB or pwndbg command for execute, or a stepping verb such as c, n, s, ni, or si for step_control.

string

Argument string passed to the inferior when using run.

number

Target process id for attach.

Execution control tools

Tool	Use it for	Notes
`run`	start the loaded inferior	supports `args` and `start`
`step_control`	continue or step execution	supports `c`, `n`, `s`, `ni`, `si`
`gdb_poll`	drain pending async GDB notifications	useful after async activity
`gdb_interrupt`	interrupt a running inferior and wait for stop events	useful when you need control back
`finish`	run until the current function returns	wrapper around MI `-exec-finish`
`jump`	resume execution at a location	supports symbol, `file:line`, or address
`return_from_function`	force the current function to return	wrapper around MI `-exec-return`
`until`	run until a location or next source line	optional `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

Create the session

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

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"}}

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

I got 'session_id is required' or 'session not found'

Create the session first with create_debug_session, then pass the same session_id on all later calls.

I got 'No binary selected' or 'Use set_file first'

Load a file with set_file before calling run, or pass binary_path where the tool supports it.

My attach flow returns more than one thing

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

boolean

required

Whether the tool call succeeded.

string

Session that the tool actually operated on.

string

Current debugger or inferior state after the operation, when provided by the backend.

string

Resolved binary path after set_file or other file-sensitive operations.

string

Session-specific runtime directory returned by get_session_info.

string

Short actionable error message when the call fails.

string

Exception type returned by the shared error wrapper on failures.

Debugger and Inspection

Automation and Exploit I/O

Session lifecycle tools

Load, attach, and raw command tools

Common debugger parameters

Execution control tools

Typical flow

Common edge cases

Common debugger response fields

​Session lifecycle tools

​Load, attach, and raw command tools

​Common debugger parameters

​Execution control tools

​Typical flow

​Common edge cases

​Common debugger response fields

Session lifecycle tools

Load, attach, and raw command tools

Common debugger parameters

Execution control tools

Typical flow

Common edge cases

Common debugger response fields