MCP Tools

Model Context Protocol tools for AI-assisted debugging

Pointbreak exposes debugging capabilities to AI assistants through the Model Context Protocol (MCP). These tools allow AI assistants to control your debugger programmatically.

These tools are designed for AI assistants to use. You don’t need to call them directly unless you’re building a custom MCP client.

Session Management

ide_start_debugging

Start a new debug session with your IDE.

Parameters:

• configuration (required): Debug configuration object (follows VS Code launch.json format)
• breakpoints (optional): Array of breakpoints to set before starting
• registrationId (optional): IDE registration ID (auto-detected by default)

Example:

{
  "configuration": {
    "type": "python",
    "request": "launch",
    "program": "${file}",
    "stopOnEntry": false
  },
  "breakpoints": [{
    "source": {"uri": "file:///path/to/file.py"},
    "breakpoints": [{"line": 42}]
  }]
}

ide_list_sessions

List all active debug sessions.

Returns: Array of session objects with state, thread info, and capabilities.

ide_terminate_session

End a debug session.

Parameters:

• sessionId (optional): Session to terminate (defaults to current)
• registrationId (optional): IDE registration (auto-detected)

Breakpoints

ide_set_breakpoints

Set or replace breakpoints in a source file.

Parameters:

• source (required): Source file object with uri field
• breakpoints (required): Array of breakpoint specifications
• sessionId (optional): Debug session ID

Breakpoint options:

• line (required): Line number (1-indexed)
• column (optional): Column number
• condition (optional): Break only if expression is true (e.g., x > 0)
• hitCondition (optional): Break after N hits (e.g., 5)
• logMessage (optional): Print message without stopping (e.g., Value: {x})

ide_get_breakpoints

List all breakpoints for a session.

Parameters:

• sessionId (optional): Filter by session
• registrationId (optional): Filter by IDE

Execution Control

ide_continue_session

Resume execution after hitting a breakpoint.

Parameters:

• sessionId (optional): Auto-detected from paused session
• registrationId (optional): Auto-detected

ide_pause_session

Pause a running debug session to inspect state.

ide_step_over

Execute the current line and pause on the next line, without entering function calls.

Use this to: Follow execution line-by-line instead of adding print statements.

ide_step_in

Step into the next function call to trace execution inside functions.

Use this to: Understand what happens inside a function instead of adding prints at function entry/exit.

ide_step_out

Run until the current function returns.

Variable Inspection

ide_get_variables

Get variable values from the current debug state.

Two modes:

Mode 1: Get specific variables (recommended)

{
  "sessionId": "abc-123",
  "variableNames": ["result", "error", "config"]
}

Mode 2: Get all local variables

{
  "sessionId": "abc-123"
}

Returns: Variable values with type information and scope context.

Features:

• Smart thread/frame selection (skips runtime internals)
• Auto-searches scopes (Locals → Globals)
• Expands nested objects/arrays
• 80% faster than traditional multi-call pattern

ide_evaluate

Evaluate any expression when paused at a breakpoint, without modifying code.

Parameters:

• expression (required): JavaScript/Python/etc. expression to evaluate
• frameId (optional): Stack frame to evaluate in (defaults to current)
• sessionId (optional): Auto-detected

Use this instead of: Adding console.log/print statements to inspect values.

Examples:

• Variable values: user_input or config.settings.debug
• Expressions: x > 0 && y < 10 or items.length
• Function calls: calculate_total(items)
• Nested properties: response.data.users[0].email

ide_get_stack_trace

Get the complete call stack showing how execution reached the current point.

Parameters:

• threadId (required): Thread to inspect
• sessionId (optional): Auto-detected

Returns: Array of stack frames ordered from top (current location) to bottom (entry point).

Use this to: Understand call flow instead of adding prints in every function.

ide_get_scopes

Get variable scopes for a stack frame (e.g., ‘Locals’, ‘Globals’).

Parameters:

• frameId (required): Frame from stack trace
• sessionId (optional): Auto-detected

ide_get_threads

List all threads in a debug session.

Returns: Thread IDs and names. Use with ide_get_stack_trace.

Watch Expressions

ide_add_watch

Add a watch expression that persists across steps.

Parameters:

• expression (required): Expression to watch
• frameId (optional): Frame context
• sessionId (optional): Auto-detected

ide_get_watches

Re-evaluate and list all stored watch expressions.

ide_remove_watch

Remove a watch expression by ID.

Data Breakpoints (Watchpoints)

ide_add_data_breakpoint

Break when a variable is read or written.

Parameters:

• dataId (required): From ide_get_data_breakpoint_info
• accessType (required): 'read', 'write', or 'readWrite'
• condition (optional): Break only if condition is true

Note: Requires supportsDataBreakpoints capability.

ide_get_data_breakpoint_info

Check if a variable supports data breakpoints.

Parameters:

• variablesReference (required): From variable inspection
• name (required): Variable name

ide_get_data_breakpoints

List all active data breakpoints.

ide_remove_data_breakpoint

Remove a data breakpoint by ID.

Exception Breakpoints

ide_set_exception_breakpoints

Configure when to break on exceptions.

Parameters:

• filters (required): Array of filter IDs (e.g., ['uncaught'])
• exceptionOptions (optional): Fine-grained exception rules

ide_get_exception_breakpoints

View current exception breakpoint configuration.

Capabilities

ide_get_capabilities

Query what actions/features are supported by the debug adapter.

Use when: Unsure if stepping/breakpoints/data breakpoints are available.

ide_discover_connection

Discover parent IDE (usually not needed - auto-detected).

ide_list_registrations

List all available IDE registrations.

Use when: Running outside IDE terminal or multiple IDEs are open.

Advanced Tools

ide_get_step_in_targets

Get list of functions available to step into (if adapter supports it).

ide_restart_frame

Restart execution from a specific stack frame (if adapter supports it).

ide_set_variable

Modify a variable value during debugging.

Parameters:

• variablesReference (required): From scope/variable
• name (required): Variable name
• value (required): New value as string

ide_send_custom_request

Execute a raw Debug Adapter Protocol (DAP) command.

Use when: A capability is not covered by higher-level tools (power-user escape hatch).

Console Output

ide_get_console

Fetch buffered console output for a debug session.

Parameters:

• sessionId (required): Debug session
• category (optional): Filter by ‘stdout’, ‘stderr’, ‘console’, or ‘telemetry’

ide_clear_console

Remove all buffered console entries (cannot be undone).

Best Practices

Use breakpoints instead of console.log/print statements. Inspect values on demand without modifying code.

Use ide_get_variables with variableNames for 80% faster inspection than calling multiple tools.

Frame IDs change after stepping. Always call ide_get_stack_trace to get fresh frame IDs before calling ide_evaluate or ide_get_scopes.

Logpoint expressions evaluate at line start. Variables declared on the same line are NOT accessible. Place logpoints on the next line or use regular breakpoints with ide_evaluate.

Common Patterns

“Why is this variable wrong?”

1. ide_set_breakpoints - Pause where variable is used
2. ide_continue_session - Run to breakpoint
3. ide_get_variables({variableNames: ["result", "error"]})

“What’s happening in this loop?”

1. ide_set_breakpoints with condition "i == 3"
2. ide_step_over - Step through loop body
3. ide_get_variables({variableNames: ["i", "item", "total"]})

“Where does this value come from?”

1. ide_set_breakpoints where value is wrong
2. ide_get_stack_trace - See call chain
3. ide_step_out then ide_step_over in callers

Resources

• Debug Adapter Protocol
• Model Context Protocol
• Troubleshooting Guide