What is ACP? Claude Code, Codex, Cursor and Grok Build

By

ACP is how an editor drives a coding agent over stdin and stdout. Cursor and Grok Build speak it. Claude Code and Codex document a different programmatic path.

ACP (Agent Client Protocol) is how an editor drives a coding agent as a child process. The editor writes JSON-RPC on the agent’s stdin. The agent writes responses on stdout. You stay in the editor. The agent still does the file and shell work.

It is not MCP. MCP is how the agent calls a tool server. ACP is how the editor calls the agent. Headless mode is the other programmatic path: one prompt in, one result out, no editor in the middle.

How ACP works

The editor spawns the agent binary with an ACP argument. Messages are JSON-RPC 2.0, one JSON object per line. Logs can go to stderr, so they stay out of the protocol stream.

A typical session has the same shape on the clients that document it. The client sends initialize. It authenticates. It opens a session with session/new, or resumes one with session/load. It sends the user’s text with session/prompt. Assistant text comes back as session/update notifications while the model streams. If a tool needs a decision, the agent sends session/request_permission and waits. The client can send session/cancel to stop the turn.

If the client never answers a permission request, the tool call sits there. ACP does not skip the approval the interactive CLI would have asked for.

How an editor talks to an agent over ACPThe editor starts the agent process. It writes JSON-RPC on stdin. The agent writes session updates on stdout. The editor shows that text and answers permission requests.Editor starts theagentJSON-RPC on stdinAgent writes updateson stdoutEditor shows thetext

ACP in each tool

Cursor and Grok Build document an ACP server command. Claude Code and Codex document other ways for a program to drive the agent. Those other ways are not described as ACP.

Claude CodeCodexCursorGrok Build
ACP commandNot documentedNot documentedagent acpgrok agent stdio
TransportNot documentedNot documented as ACPstdio, newline-delimited JSON-RPC 2.0stdin and stdout, JSON-RPC
Auth the page namesNot documentedNot documented as ACPcursor_login, or a key you passed at startupA local login, or XAI_API_KEY
Where assistant text arrivesNot documentedNot documented as ACPsession/updatesession/update chunks. session/prompt returns completion metadata

Claude Code

Claude Code’s docs index does not list ACP. The programmatic interface it does document is headless mode: claude -p, or the Agent SDK. That is a prompt and a result. It is not a JSON-RPC session an editor attaches to.

See Claude Code headless mode.

OpenAI Codex

The Codex app-server page describes a JSON-RPC interface for rich clients, including the VS Code extension. Transports there include stdio. That page does not call the protocol ACP, and it does not list session/prompt or session/update. Treat app-server as its own interface. The page is Codex app-server.

Cursor

agent acp starts the CLI as an ACP server. Cursor’s page says to use plain agent for a normal terminal session. ACP is for a custom client or another editor.

The documented flow is initialize, then authenticate with methodId set to cursor_login, then session/new or session/load, then session/prompt. The sample initialize sends protocolVersion: 1. While the model streams, the client reads session/update. A permission request expects one of allow-once, allow-always, or reject-once.

You can log in first with agent login. You can also pass --api-key (or CURSOR_API_KEY) or --auth-token (or CURSOR_AUTH_TOKEN) on the same command line as acp. agent -e https://api2.cursor.sh acp sets the endpoint. agent -k acp is the documented TLS option on that page.

Modes match the CLI: agent for full tools, plan for read-only planning, ask for read-only questions. MCP servers come from a project or user .cursor/mcp.json. Team MCP servers from the Cursor dashboard are not supported in ACP.

Cursor also sends extension methods. cursor/ask_question and cursor/create_plan block until the client responds. cursor/update_todos, cursor/task, and cursor/generate_image are notifications.

Zed can spawn agent acp. JetBrains and Neovim (avante.nvim) are the other editor examples on the page. The Neovim block points command at ~/.local/bin/agent, passes acp as the only argument, and sets auth_method to cursor_login.

See Cursor’s ACP docs.

Grok Build

grok agent stdio runs Grok as an ACP agent. Use it when an editor or another tool should own the UI. A terminal session stays on grok.

The docs assume grok is already authenticated, or that XAI_API_KEY is set. Assistant text arrives as session/update chunks with sessionUpdate set to agent_message_chunk. session/prompt itself returns completion metadata.

Sessions are the same records the TUI and headless mode use, under ~/.grok/sessions/. In a script or in CI, pass --no-auto-update, or set auto_update = false under [cli] in ~/.grok/config.toml, so a background update check does not run.

How to use Grok Build walks through this command next to the JSON-RPC shape. How to use fx is a different agent that also speaks ACP, via fx acp.

See Grok Build headless and ACP.

Details checked against each vendor’s documentation in November 2026.

A real example

You want Neovim to drive Cursor’s agent, and you already ran agent login. The providers table from Cursor’s avante.nvim example is the piece that starts ACP:

acp_providers = {
  cursor = {
    command = os.getenv("HOME") .. "/.local/bin/agent",
    args = { "acp" },
    auth_method = "cursor_login",
  },
},

The rest of that plugin spec, including provider = "cursor" and mode = "agentic", is on the ACP page. Adjust command if agent is not at ~/.local/bin/agent.

For Grok in a script, the documented launch is:

grok --no-auto-update agent stdio

CLI Tools Cabinet lists the agent binaries on the machine, which is the command an editor has to spawn. The CLI tools tutorial is the habit of reading that catalog before guessing a binary name.

When to use ACP

Use it when the editor is the UI and the coding agent should be a process it starts and stops. Cursor’s own examples are JetBrains, Neovim, and Zed. Grok’s page says the same thing in fewer words: IDE or tool integration, rather than a terminal session.

Use agent or grok when you are the client. Use headless mode when a script needs one answer and does not want to implement JSON-RPC.

Pitfalls

A client that prints the agent’s stdout to the user will also print protocol frames, unless it parses each line and only shows agent_message_chunk text. Cursor’s sample client does that split. Logs belong on stderr.

ACP does not import every MCP server the desktop app can see. Cursor’s page says dashboard team servers are out. Launch agent from the project directory so the project .cursor/mcp.json is the one it reads.

session/request_permission blocks the tool. Auto-approving allow-once in a client you do not watch is the same decision as approving that tool in the terminal. Read the request before the client answers it.

Claude Code and Codex can both be driven by a program. Wiring either one up as if it spoke Cursor’s ACP methods will fail, because those docs do not describe that server.

  • How to use Grok Build shows grok agent stdio and how session/update differs from session/prompt.
  • How to use fx shows fx acp as the editor entry point for a different agent that speaks the same protocol.
  • Headless mode is the one-prompt programmatic path, for scripts that should not speak ACP.
  • CLI Tools Cabinet catalogs the installed agent CLIs an editor would put in command.
  • Headless mode: Headless mode runs a coding agent from a script, with no chat UI. How claude -p, codex exec, the Cursor CLI and grok -p differ on permissions.
  • Plugins: A plugin bundles skills, hooks and tools you install together. How plugins and marketplaces work in Claude Code, Codex, Cursor and Grok Build.
  • Sessions: A session is a saved coding-agent conversation you can resume later. How Claude Code, Codex, the Cursor CLI and Grok Build store, name, resume and fork one.
  • Slash commands: Slash commands are the /name controls inside a coding agent session. How they work in Claude Code, Codex, Cursor and Grok Build, and how to add your own.

All AI glossary entries →

Want me to talk about your product? You can sponsor this site.