JetBrains ACP Setup: Add AI Agents to IntelliJ IDEA and Rider

JetBrains ACP support lets IntelliJ IDEA, Rider and the other JetBrains IDEs host coding agents from different vendors behind one chat and one diff viewer. If you want the background first, read how the ACP Agent Registry changes vibe coding. This post is the hands-on part: what to click, what to put in the config file, and what to check when an agent will not start. The steps follow the JetBrains AI Assistant documentation; menu names can shift between IDE versions, so treat the official help for your build as the source of truth.

Before you start

• A recent JetBrains IDE with the AI Assistant plugin (IntelliJ IDEA, Rider, PyCharm and so on use the same AI Chat). Our earlier article cites IDE 2025.3.2 or newer with a current JetBrains AI plugin as the baseline for the registry; newer builds only add more.
• An account or API key for the agent you want. A JetBrains AI subscription is not required just to connect ACP agents.
• Not on WSL: the documentation lists ACP agents as unsupported there.
• On a managed team setup, an administrator using JetBrains IDE Services can limit the registry, disable agents or block custom ones. If options are missing, ask them first.

Step 1: install an agent from the ACP Registry

1. Open the AI Chat tool window.
2. Open the chat mode selector (the chevron) and pick Install From ACP Registry. Alternatively go to Settings | Tools | AI Assistant | Agents.
3. Install the agent you want. Two optional switches decide what the agent can use: Pass custom MCP servers and Pass IntelliJ MCP server.
4. Click OK. The IDE downloads the agent and, if needed, a Node.js or Python runtime (or reuses one you already have).
5. Pick the agent in AI Chat and send a first message. Many agents ask you to authenticate at that point.

Some agents ship with the IDE (the JetBrains docs list Junie, Claude Agent and Codex, plus GitHub Copilot as an option), so you may be able to start without any registry step. Updates and removal live on the same Agents page: click Update when the blue dot appears, or Uninstall.

Step 2: add a custom ACP agent

If the agent is not in the registry, such as an internal tool or a fresh open-source project like OpenCode, register it yourself:

1. In AI Chat click the more (three dots) button and choose Add Custom Agent. This creates and opens ~/.jetbrains/acp.json.
2. Add an entry under agent_servers. The key becomes the agent's name in AI Chat.
3. Save the file and select the agent in AI Chat.

{
  "default_mcp_settings": {
    "use_idea_mcp": true,
    "use_custom_mcp": true
  },
  "agent_servers": {
    "My Internal Agent": {
      "command": "/full/path/to/your-agent",
      "args": ["acp"],
      "env": { "SOME_VAR": "value" }
    }
  }
}

The fields are simple: command is the executable (use the full path), args are the arguments that switch the agent into ACP mode (often acp, but check your agent's documentation), and env sets environment variables for the process. The IDE can also detect agents already installed on your machine and offer an Add to configuration button.

Step 3: authenticate without leaking secrets

Registry agents may ask for an API key on first use. Most custom agents do not need one in the config: run the agent once in a terminal, sign in as its instructions say, and the IDE-launched process reuses that login. Credentials you type into the IDE are stored in your user configuration. Keep API keys out of any acp.json you commit or share, and review each agent's license and privacy terms before giving it access to a private repository; each one has its own.

Step 4: give the agent tools with MCP

An agent that can only read files is limited. The default_mcp_settings block controls what local agents may use: use_custom_mcp exposes the MCP servers you configured (default on), use_idea_mcp exposes the IDE's own MCP server (default off), and idea_mcp_allowed_tools can narrow the IDE tools to a short allow-list. You can override this per agent on the Agents page.

This is where it gets useful for debugging: connect the LogNroll MCP server and the same agent can pull a real recorded user session and its console and network logs while it edits your code. That turns "users say checkout is broken" into a reproducible starting point; see debugging frontend bugs with session replay.

Troubleshooting

Tips for working with several agents

Features such as plans, modes, slash commands and session loading differ per agent, so do not expect identical behavior. Keep diff review inside the IDE and treat the agent as swappable: if one provider has an outage or a model underperforms on a task, switch to another configured agent in the same project. Put shared project rules in one file that every agent reads. To decide which agents deserve a slot, see our OpenCode vs Claude Code vs Cursor comparison, and for the privacy side read local vs remote AI agents.

Next: give your agent real user sessions

An IDE agent is only as good as its context. LogNroll records real sessions, console errors and network calls, so your ACP agent can start from the exact failing journey. New to the idea? Read what session replay is and how it works.

Frequently asked questions