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 an 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 when you need facts that the source code and logs do not reveal reliably, such as runtime values, branch decisions, call order, thread context, or whether the program ever runs a specific line.
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 .
Find the Debugger MCP Toolset plugin and click Enable.
How the debugger reaches agents
IntelliJ IDEA provides the debugger functions to agents in two ways:
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_andjvm_debug_. 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 theij-debuggerskill. All tools marked as router-only, including the debugger tools, are hidden from the agent and stay reachable only throughexecute_tool. 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.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_andjvm_debug_.
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 descriptions of router-only tools, including the debugger tools, out of the agent context until the agent needs them. The MCP server exposes one universal tool, execute_tool, and the agent loads the ij-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 .
Select the Enable router-only mode checkbox. The debugger tools stay reachable through
execute_tool, and theij-debuggerskill tells the agent when to use them. To turn router mode off, clear the checkbox.Router mode applies to the tools that have the Router-only option selected. By default, it is selected for the debugger tools.
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 .
Navigate to the Bundled skills section and locate the
ij-debuggerskill. 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.
Debug your code with an agent
Through the debugger tools, the agent can:
Start a debug session for a run configuration or a source location, reuse a running session, or attach the debugger to a running local process.
Set, mute, and remove breakpoints and logpoints, set method and exception breakpoints, and run to a specific line.
Step through the code, and pause, resume, or stop the session.
Inspect threads, call stacks, and variables, capture thread dumps, evaluate expressions, and change variable values.
Read the output of the debugged process.
The agent keeps track of the breakpoints that it sets and the ones that you set manually. When it finishes, it removes only its own breakpoints.
To start, open your project and describe the problem to the agent. The agent applies the ij-debugger skill on its own when a task needs runtime evidence. To invoke the skill explicitly, start the prompt with /ij-debugger in Claude Code or with $ij-debugger in Codex.
For example:
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.
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.