Agentic debugging

IntelliJ IDEA exposes its debugger to external AI agents through the integrated MCP server. With the debugger tools connected, an agent such as Claude, Codex, or Junie can drive a IntelliJ IDEA debug session on its own: start and stop it, manage breakpoints, step through code, inspect threads and variables, and evaluate expressions.

Instead of stepping through the code yourself, you describe the problem in natural language and let the agent collect the runtime evidence. This helps you locate issues that are hard to spot from the source code and logs alone, such as an incorrect value that appears only at run time.

Enable the Debugger MCP Toolset plugin

This functionality relies on the Debugger MCP Toolset plugin, which is bundled and enabled in IntelliJ IDEA by default. If the relevant features are not available, make sure that you did not disable the plugin.

Press Ctrl+Alt+S to open settings and then select Plugins.
Open the Installed tab, find the Debugger MCP Toolset plugin, and select the checkbox next to the plugin name.

How the debugger reaches agents

IntelliJ IDEA provides the debugger functions to agents in two ways:

Shared MCP server: The debugger tools are served over the MCP server together with the analysis, formatting, and other IDE tools. Their descriptions are part of the agent context at all times, even when you do not debug. The debugger tools are prefixed with xdebug_. This option is available in IntelliJ IDEA 2026.1.3 and later.
Router mode: The MCP server exposes one universal tool, execute_tool, together with the ij-debugger skill. The commands, parameters, and debugging scenarios live in the skill, and the agent loads them only when it needs the debugger. Because the debugger descriptions stay out of the agent context until then, router mode lowers token consumption. Router mode works with the GDB, LLDB, and DAP-based debuggers and is used by agents such as Claude Code and Codex. This option is available in IntelliJ IDEA 2026.2 and later.

Connect an agent to the debugger

The debugger tools are served over the IntelliJ IDEA MCP server, so a client gains access to them as soon as the server is enabled.

Enable the MCP server and set up your client as described in MCP Server.
Restart the client so that it picks up the IntelliJ IDEA tools, including the debugger tools prefixed with xdebug_.

You can review the exposed tools and turn individual tools on or off in the MCP Server settings.

Turn on router mode

In router mode, IntelliJ IDEA keeps the debugger command descriptions out of the agent context until the agent needs them. The MCP server exposes one universal tool, execute_tool, and the agent loads the clion-debugger skill on demand. Router mode suits longer sessions, where the always-on tool descriptions take up context that the agent could spend on the task.

In the main menu, go to Settings | Tools | MCP Server | Exposed Tools.
Select the Enable router-only mode checkbox. The debugger tools stay reachable through execute_tool, and the clion-debugger skill tells the agent when to use them. To turn router mode off, clear the checkbox.

Install the debugger skill

To improve how external clients use the IDE's debugger tools, you can install a specific skill for them. This skill comes bundled with the IDE and guides an external client on when to apply the debugger tools.

To install the skill for an external client:

Go to Settings | Tools | AI Assistant | Skills.
Navigate to the Bundled skills section and locate the ij-debugger skill. It is enabled by default, but is available only to the agents inside the IDE.
To use the skill in Claude Code or Codex outside the IDE, you need to install it for those clients explicitly. To do this, click and select Claude Agent (Global) or Codex (Global), depending on which client you want to use.

Depending on the target you select, the skill is installed into the following folders:

Claude Code:
%USERPROFILE%\.claude\skills\ij-debugger\
~/.claude/skills/ij-debugger/
~/.claude/skills/ij-debugger/
Codex:
%USERPROFILE%\.codex\skills\ij-debugger\
~/.codex/skills/ij-debugger/
~/.codex/skills/ij-debugger/

To invoke the skill in the external client, use /ij-debugger, or let it activate automatically when relevant.

What an agent can do

Through the debugger tools, an agent runs the same runtime investigation that you would perform manually:

Start a debug session for a run configuration or a source location, and check the status of running sessions (xdebug_start_debugger_session, xdebug_get_debugger_status).
List, set, and remove breakpoints, and run to a specific line (xdebug_list_breakpoints, xdebug_set_breakpoint, xdebug_remove_breakpoint, xdebug_run_to_line).
Control execution by stepping, resuming, pausing, or stopping the session (xdebug_control_session).
Read local variables, frame values, and nested fields, and evaluate or change expressions (xdebug_get_frame_values, xdebug_get_value_by_path, xdebug_evaluate_expression, xdebug_set_variable).
Inspect threads and their call stacks (xdebug_get_threads, xdebug_get_stack).

Debug your code with an agent

Open your project, then describe the problem to the agent and ask it to debug the code. For example:

Adding a pet whose name only differs in case from one an owner
already has is not rejected as a duplicate. Start a debug session,
set a breakpoint in Owner.getPet(), and find out why the duplicate
check misses it.
        

The agent sets the breakpoints it needs, starts the debug session, and waits for the program to pause. When execution stops, it reads the call stack, the local variables, and the expressions it needs to test its hypothesis, and then reports what it finds.

IntelliJ IDEA paused at a breakpoint in getPet(), with the Debug tool window showing the call stack and the mismatched name and compName variable values

The agent controls the standard IntelliJ IDEA debugger, so you can follow the session in the Debug tool window and take over at any point.

31 July 2026