start_debug_session
Initiates a PHP debugging session by executing a command and listening for XDebug connections to pause execution at breakpoints, entry points, or exceptions.
Instructions
Starts a new PHP debugging session by listening for XDebug connections and executing a trigger command.
WORKFLOW - Call tools in this order:
get_session_status - Check if a session is already active
set_breakpoint - Set breakpoints at locations you want to inspect
start_debug_session - Start the session with your trigger command
inspect_variable / control_execution - Debug at breakpoints
BEFORE CALLING:
Call get_session_status first. If a session is active, use control_execution with action="stop" to end it.
Set breakpoints BEFORE calling this (unless using stop_on_entry or stop_on_exception).
XDEBUG TRIGGERING: For xdebug.start_with_request=trigger (common in Docker), append the trigger to your URL:
Query param: ?XDEBUG_SESSION=1
Example: curl 'http://localhost/api/users?XDEBUG_SESSION=1' The trigger is NOT auto-added - you must include it in your command.
HOW IT WORKS:
Starts listening on port 9003 (or XDEBUG_MCP_PORT)
Executes your trigger command in a subprocess
Waits for XDebug to connect (timeout: 30s)
Pauses when a breakpoint is hit, exception thrown, or entry reached
LIMITATIONS:
Only one session can be active at a time
Only listens on one port (cannot debug multiple services simultaneously)
COMMON ERRORS:
"SESSION_ALREADY_ACTIVE": Call control_execution with action="stop" first
Timeout: Ensure XDebug is configured and ?XDEBUG_SESSION=1 is in your URL
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| command | Yes | The command to trigger PHP execution. IMPORTANT: Include ?XDEBUG_SESSION=1 in URLs for trigger mode. Examples: 'curl http://localhost/api/users?XDEBUG_SESSION=1' or 'php artisan test --filter=UserTest' | |
| stop_on_entry | No | If true, pauses at the very first line of execution. Use when you dont know where to set breakpoints. | |
| stop_on_exception | No | If true, pauses automatically when an Error or Exception is thrown. Recommended for debugging crashes and 500 errors. | |
| working_directory | No | Working directory for the trigger command. Defaults to project root. |