Agent Client Protocol (ACP): Connect Any AI Agent to Any Editor

TL;DR

The Agent Client Protocol (ACP) is a JSON-RPC 2.0 standard that lets any AI coding agent run inside any supporting editor: JetBrains, Zed, Neovim, Emacs. Think LSP, but for AI agents instead of language servers. The registry already lists 50 agents (Claude Code, Gemini CLI, Codex, GitHub Copilot, Goose, and more). This tutorial walks through real setup in JetBrains and Zed, custom agent config, and what ACP gets right versus where it still needs work.

My Weekend ACP Setup Across Three Editors

I use JetBrains for Go and Python, Zed for quick edits, and Neovim when I’m SSH’d into a server. Until a few months ago, that meant three completely separate AI setups: Copilot in JetBrains, Zed’s built-in assistant, and nothing in Neovim because I couldn’t be bothered to configure yet another integration.

Then I set up ACP in all three editors over a weekend. By Monday, I had Claude Code, Gemini CLI, and Codex available in every editor through the same protocol. I could switch between agents mid-session depending on the task. Claude for architecture reasoning (especially with subagents), Gemini for quick multi-file edits, Codex for throwaway scripts. The configuration files are nearly identical across editors.

That weekend convinced me ACP is the first protocol I’ve used that reduced complexity instead of adding it.

What Is the Agent Client Protocol?

Every AI coding tool used to require its own editor plugin. Cursor baked its agent into a VS Code fork. GitHub Copilot needed the Copilot extension. Claude Code ran only in the terminal. If you wanted to use three agents, you needed three separate integrations. And if your editor of choice didn’t have a plugin for your preferred agent, you were out of luck.

ACP fixes this with a simple idea borrowed from LSP: define a standard wire protocol between editors and agents, so any agent can plug into any editor.

The protocol works like this:

1. The editor (client) spawns the agent as a subprocess
2. The agent communicates back over JSON-RPC 2.0 on stdin/stdout (local agents) or HTTP/WebSocket (remote agents, still in development)
3. Work organizes into sessions (a conversation with shared context) and turns (individual prompt-response cycles)
4. The agent can request file access, terminal execution, and tool calls, all through the protocol

Zed Industries created ACP in August 2025. JetBrains joined shortly after. By January 2026, they co-launched the ACP Registry, a directory of compatible agents built into both editors. As of June 2026, 50 agents and a growing list of editors implement the spec. Zed and JetBrains have native support; Neovim, Emacs, and VS Code have community plugins.

ACP vs MCP

If you’ve worked with the Model Context Protocol (MCP), you might wonder why we need another protocol. The confusion is understandable because both involve AI agents and JSON-RPC. But they sit on different sides of the agent.

MCP gives agents access to tools: databases, APIs, file systems, browser automation. ACP gives agents access to editors: file trees, terminals, diff views, user prompts.

The two protocols stack rather than compete. A typical setup looks like this: Zed (ACP client) launches Claude Code (ACP agent), which then connects to an MCP server for database access. ACP handles the editor-to-agent communication; MCP handles the agent-to-tool communication.

If you’ve already built MCP servers for your workflow, those still work under ACP. The agent sits in the middle and bridges both protocols.

The ACP Registry: 50 Agents

The ACP Registry is a curated directory that editors query directly. When you open JetBrains or Zed and browse available agents, you’re reading from this registry. It auto-updates hourly from npm, PyPI, and GitHub Releases.

Here are some agents worth knowing about:

The full list has 50 entries. Most are installable in one click from JetBrains or Zed. Custom agents that aren’t in the registry can be added manually through config files (covered below).

Setting Up Claude Code via ACP in JetBrains

This is the setup I use daily. JetBrains ships native ACP support across all their IDEs: IntelliJ IDEA, PyCharm, WebStorm, GoLand, the lot. No subscription required for ACP itself (the agents may need their own API keys).

Step 1: Open the agent panel

Open the AI Chat tool window (usually on the right sidebar). Click the dropdown at the top, which shows your current agent/model.

Step 2: Install from registry

Click “Install From ACP Registry” in the dropdown. Scroll to Claude Agent and select it.

The IDE downloads the agent binary and creates a config entry automatically. You’ll be prompted for your Anthropic API key. Paste it in.

Step 3: Verify

Back in the AI Chat panel, select “Claude Agent” from the dropdown. Type a message. If you see Claude responding with code awareness (file context, project structure), the agent is connected and reading your workspace through ACP.

Step 4: Configure MCP servers (optional)

If you already use MCP servers (a Chrome DevTools MCP server or a FastMCP server, for example), you can wire them into the ACP agent. Edit ~/.jetbrains/acp.json:

{
  "default_mcp_settings": {
    "use_custom_mcp": true,
    "use_idea_mcp": false
  },
  "agent_servers": {
    "Claude Agent": {
      "command": "/usr/local/bin/claude-acp",
      "args": ["acp"],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

The use_custom_mcp: true flag tells the agent to use your MCP config instead of the IDE’s built-in tool servers. Restart the IDE after editing.

Setting Up Gemini CLI via ACP in Zed

Zed was the first editor to support ACP (they created the protocol), so the integration is smooth.

Step 1: Open the agent panel

Press Cmd+? (macOS) or Ctrl+? (Linux/Windows). This opens the agent panel on the right side.

Step 2: Add Gemini CLI

Click the + button in the top-right corner. Select Gemini CLI from the registry list.

You’ll be asked for your Google AI API key on first use. Paste it, and the agent starts.

Step 3: Use it

Gemini CLI now has full access to your project through ACP. File reading, terminal execution, and diff generation all go through the protocol. If you haven’t used Gemini CLI before, our Gemini CLI tutorial covers the initial setup and a real Python project walkthrough. You can keep multiple agents active simultaneously: select a different agent from the panel’s dropdown to switch, or open a second agent panel for side-by-side comparisons.

Custom agent config in Zed

If you want to customize the agent’s environment or add an agent that isn’t in the registry, edit ~/.config/zed/settings.json:

{
  "agent_servers": {
    "Gemini CLI": {
      "type": "registry",
      "env": {
        "GOOGLE_API_KEY": "AIza..."
      }
    },
    "My Custom Agent": {
      "type": "custom",
      "command": "/path/to/my-agent",
      "args": ["acp"],
      "env": {
        "MY_API_KEY": "..."
      }
    }
  }
}

Registry agents use "type": "registry" and the registry name as the key. Custom agents use "type": "custom" with a command path. Both communicate over stdio using the same ACP JSON-RPC protocol.

Custom Agent Configuration

Both JetBrains and Zed support custom agents that aren’t in the registry. The config format is nearly identical.

JetBrains: ~/.jetbrains/acp.json

{
  "agent_servers": {
    "OpenCode": {
      "command": "/usr/local/bin/opencode",
      "args": ["acp"],
      "env": {
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Zed: ~/.config/zed/settings.json

{
  "agent_servers": {
    "OpenCode": {
      "type": "custom",
      "command": "/usr/local/bin/opencode",
      "args": ["acp"]
    }
  }
}

Neovim: community plugins

Neovim support comes through community plugins like CodeCompanion.nvim and avante.nvim. The config follows the same pattern: a command path, args, and environment variables. Neovim spawns the agent as a subprocess and pipes JSON-RPC over stdio, same as the other editors.

The key thing across all three editors: you specify a command that accepts an acp argument, the editor spawns it, and they talk JSON-RPC. If your agent binary can speak the protocol, it works.

Building Your Own ACP Agent

If you’re building a custom coding tool and want it to work in every ACP editor, official SDKs exist in five languages:

The minimal contract: implement the initialize handshake, handle session/new and session/prompt methods, and send back content updates. The SDKs ship with example agents you can fork.

Here’s the skeleton in Python using the official SDK:

from acp import Agent, PromptResponse, run_agent

class MyAgent(Agent):
    async def prompt(self, prompt, session_id, message_id):
        user_message = prompt.content
        # ... call your LLM, read files, run terminal commands
        return PromptResponse(content="Here's my response...")

if __name__ == "__main__":
    run_agent(MyAgent())

Run this with python my_agent.py acp and point your editor’s config at it. The SDK handles JSON-RPC framing, capability negotiation, and session lifecycle.

The ACP specification covers file system access, terminal execution, slash commands, tool calls, and authentication. You don’t need to implement all of them. Agents declare their capabilities during the initialize handshake, and editors adapt their UI accordingly.

When ACP Falls Short

I’ve been using ACP daily for several months now, and it works well for what it covers. But there are gaps.

The HTTP/WebSocket transport for remote agents is still work-in-progress. Every ACP agent runs as a local subprocess right now. That’s fine for Claude Code or Gemini CLI, which run local binaries that call cloud APIs. It doesn’t work for Devin-style cloud agents that need long-running sandboxed environments. There’s an active RFC for remote transport, but nothing stable yet.

Microsoft hasn’t committed to native ACP support in VS Code. Their agent mode standardized on MCP for tool integration, and as of June 2026, Microsoft’s position is that MCP covers their needs. The world’s most popular editor requires community plugins for ACP. Those plugins exist but don’t match the polish of native support in JetBrains or Zed.

WSL isn’t supported for ACP agents in JetBrains, which stings if your dev environment is WSL-based. You’ll need to run agents in Windows-native mode or find workarounds. Zed on Windows handles ACP agents more cleanly, but Zed itself is newer on that platform.

The registry is curated: all 50 agents must support user authentication. Experimental or internal agents need the manual config path. And the registry doesn’t show usage stats, reviews, or compatibility notes. Just names and versions.

I also found that agent quality varies. ACP standardizes the wire protocol, not what the agent does with it. Claude Agent, Gemini CLI, and Goose were reliably useful. Some of the smaller agents in the registry crashed on complex project structures or produced worse code than their non-ACP versions.

FAQ

What is the Agent Client Protocol (ACP)?

ACP is an open JSON-RPC 2.0 standard that lets AI coding agents communicate with code editors through a single protocol. Created by Zed Industries in August 2025 and co-maintained with JetBrains, it works like LSP but for AI agents instead of language servers. One agent implementation works across Zed, JetBrains, Neovim, and Emacs without separate plugins for each.

How does ACP compare to MCP?

They complement each other. ACP connects editors to agents (how an editor drives an AI assistant). MCP connects agents to tools (how an agent calls databases, APIs, or browser automation). In a typical stack, the editor uses ACP to talk to the agent, and the agent uses MCP to talk to external tools. You don’t choose between them; you use both.

Which editors support ACP?

As of June 2026: Zed (native, created the protocol), JetBrains IDEs (native, including IntelliJ, PyCharm, GoLand, WebStorm), Neovim (community plugin), and Emacs (community plugin). VS Code has community support through third-party extensions, but Microsoft hasn’t added native ACP to VS Code itself.

Which AI coding agents support ACP?

The ACP Registry lists 50 agents including Claude Code, Gemini CLI, Codex CLI, GitHub Copilot, Cursor, Goose, Kiro, Junie, OpenCode, Grok Build, Mistral Vibe, and Qwen Code. The registry auto-updates hourly. Any agent not in the registry can be added manually through config files.

How do I set up an ACP agent in my editor?

In JetBrains: open AI Chat > Install From ACP Registry > select your agent > enter your API key. In Zed: press Cmd+? > click + > select your agent. For custom agents, edit ~/.jetbrains/acp.json (JetBrains) or ~/.config/zed/settings.json (Zed) with the agent’s command path and args.

Sources

• Agent Client Protocol specification — official protocol documentation and getting started guide
• ACP GitHub repository — specification source, SDKs, and governance (3.3k stars, Apache 2.0)
• ACP Registry — the 50-agent registry with auto-updated versions
• JetBrains ACP documentation — setup guide for JetBrains IDEs
• Zed external agents documentation — ACP setup in Zed
• Marc Nuri: ACP introduction — technical overview of ACP architecture and ACP vs MCP comparison

Bottom Line

ACP is the most practical improvement to my AI coding workflow since MCP. The N×M problem (N editors times M agents, each needing a bespoke integration) was real, and ACP solves it. I run Claude Code in JetBrains, Gemini CLI in Zed, and switch between them depending on the task. The config files are ten lines of JSON.

The protocol isn’t finished. Remote agents need stable transport, VS Code needs native support, and the registry needs quality signals beyond “exists and authenticates.” But the core promise (write one agent, run it everywhere) already works for the 50 agents and dozen-plus editor integrations that have adopted it.

If you use more than one editor or more than one AI agent (and our terminal agent comparison suggests you should), set up ACP this weekend. It takes 15 minutes and saves you from maintaining three separate AI configurations that do the same thing.