---
title: "Agent Client Protocol"
description: "基于 Cursor 官方 ACP 文档解释 agent acp、stdio JSON-RPC、认证、session 流程、permissions、MCP 限制和自定义客户端边界。"
verifiedAt: "2026-05-09"
---

ACP 是给高级集成和自定义客户端用的协议入口。普通终端工作流继续用 `agent`；只有你要把 Cursor Agent 接进自己的 editor、IDE、TUI（Terminal User Interface，终端图形化界面，如 Neovim / lazygit 风格）或自动化客户端时，才需要 `agent acp`。

> [!NOTE]
> **阅读目标**：读完本章，你应该能解释 ACP 的 transport、消息格式、session 生命周期、权限回调，以及为什么它不是普通用户的第一入口。

## 1. ACP 适合谁

| 需求 | 是否适合 ACP | 理由 |
| --- | --- | --- |
| 在终端里和 Agent 对话 | 不适合 | 直接用 `agent` 更简单 |
| 给自研 IDE 插件接 Cursor Agent | 适合 | 需要稳定协议和 UI 事件 |
| 给 Neovim / Zed 这类编辑器接入 Agent | 适合 | 由插件作为 ACP client |
| 在 CI 里跑一次审查 | 通常不需要 | `agent -p` 更直接 |
| 做多用户 SaaS 后台代理 | 高风险 | 需要认证、权限、租户隔离和审计设计 |

一句话：ACP 是集成界面（integration surface，给第三方编辑器 / IDE / TUI 接入 Cursor Agent 的协议入口），不是日常命令别名。

## 2. 启动方式和协议形态

启动 ACP server：

```bash
agent acp
```

官方定义的通信形态：

| 项目 | 行为 |
| --- | --- |
| Transport | `stdio` |
| Envelope | JSON-RPC 2.0 |
| Framing | newline-delimited JSON |
| Client input | client 写入 Cursor CLI 的 `stdin` |
| Agent output | Cursor CLI 向 `stdout` 写 responses / notifications |
| Logs | 可能写入 `stderr` |

这意味着你的客户端必须正确处理 stdout 的逐行 JSON，不能把日志、普通文本和协议消息混在一起解析。

## 3. 标准 session 流程

官方给出的典型 ACP 流程可以理解为：

```mermaid
sequenceDiagram
  participant Client
  participant Agent as agent acp
  Client->>Agent: initialize
  Client->>Agent: authenticate cursor_login
  Client->>Agent: session/new or session/load
  Client->>Agent: session/prompt
  Agent-->>Client: session/update notifications
  Agent-->>Client: session/request_permission
  Client-->>Agent: permission decision
  Client->>Agent: session/cancel optional
```

如果客户端不处理 `session/request_permission`，工具执行可能卡住。商业级客户端必须把权限请求做成明确 UI，而不是后台默认允许。

## 4. 认证方式

ACP 会使用 `cursor_login` 认证方法。你也可以在启动前通过 CLI 认证路径准备好身份：

```bash
agent login
agent --api-key "$CURSOR_API_KEY" acp
agent --auth-token "$CURSOR_AUTH_TOKEN" acp
```

还可以传 endpoint 和 TLS 相关选项：

```bash
agent -e https://api2.cursor.sh acp
agent -k acp
```

上线集成时不要把 `CURSOR_API_KEY` 或 `CURSOR_AUTH_TOKEN` 打进日志。ACP 客户端通常会处理更长的 stdout/stderr 流，更容易意外泄露环境变量和错误上下文。

## 5. Sessions、modes 和 permissions

ACP 支持创建或恢复 session：

| 能力 | 方法 |
| --- | --- |
| 新会话 | `session/new` |
| 恢复会话 | `session/load` |
| 发 prompt | `session/prompt` |
| 取消 | `session/cancel` |

核心 modes 与 CLI 一致：

| Mode | 含义 |
| --- | --- |
| `agent` | 完整工具访问 |
| `plan` | 计划模式，偏只读和方案确认 |
| `ask` | 问答/只读理解 |

权限请求会通过 `session/request_permission` 回到 client。官方列出的决策包括：

- `allow-once`
- `allow-always`
- `reject-once`

商业级客户端要默认 `allow-once` 起步，只有稳定低风险命令才允许用户显式选择长期允许。

## 6. MCP 支持和限制

ACP 可以使用项目级或用户级 `.cursor/mcp.json` 里的 MCP servers。启动 `agent` 时应从项目目录启动，并审批需要的 servers。

当前官方文档明确限制：Cursor dashboard 配置的 team-level MCP servers 不支持 ACP mode。

这对企业集成很重要。不要假设编辑器里可用的 team MCP，在 ACP 自定义客户端里也能用。

## 7. Cursor extension methods

Cursor 会发送一组扩展方法，让自定义客户端呈现更完整的 UI。

| Method | Type | 用途 |
| --- | --- | --- |
| `cursor/ask_question` | Blocking | 多选问题，需要用户回答 |
| `cursor/create_plan` | Blocking | 请求用户批准计划 |
| `cursor/update_todos` | Notification | 更新 todo 状态 |
| `cursor/task` | Notification | 通知 subagent task 完成 |
| `cursor/generate_image` | Notification | 通知生成图片输出 |

Blocking method 必须响应，否则 Agent 会等待。Notification 可以展示，但不需要回复。

一个最小权限响应的思路：

```json
{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "outcome": {
      "outcome": "selected",
      "optionId": "allow-once"
    }
  }
}
```

不要在客户端里把 permission request 静默变成 `allow-always`。这会绕过用户审查，也会让企业权限策略失去意义。

## 8. IDE 和自定义客户端

官方文档列出的典型集成方向包括：

- JetBrains IDE：通过 JetBrains integration guide 接入。
- Neovim：例如 avante.nvim 通过 ACP provider 连接 `agent acp`。
- Zed：由 Zed extension spawn `agent acp` 并处理 stdio。
- Custom editors：自己实现 ACP client。

实现一个客户端至少要覆盖：

1. spawn `agent acp`。
2. 按行读写 JSON-RPC。
3. 处理 streaming `session/update`。
4. 处理 `session/request_permission`。
5. 根据需要实现 Cursor extension methods。
6. 安全处理认证、日志和退出。

<details>
<summary>深读：ACP 客户端最容易漏掉什么</summary>

最容易漏的是“等待用户决定”的阻塞方法。比如计划审批、问题回答、权限请求，如果客户端只展示文本流，不处理这些事件，Agent 看起来就像卡住。

第二个常见问题是把 stdout 当普通文本流。ACP 的 stdout 是协议流，必须逐行解析 JSON-RPC；日志和调试输出应该走 stderr 或单独面板。
</details>

## 本章自检

完成本章后，用这 3 个问题检查自己是否真正理解：

1. 为什么普通终端用户不应该优先使用 ACP？
2. `session/request_permission` 如果不响应会发生什么？
3. team-level MCP servers 为什么不能直接假设在 ACP mode 可用？

通过标准：你能画出一个最小 ACP client 的数据流，并说明认证、session、permission、streaming update 和日志隔离怎么处理。

## 官方来源

- [Cursor ACP](https://cursor.com/docs/cli/acp.md) —— 官方 ACP overview、启动方式、transport、request flow、authentication、sessions、permissions、MCP、extension methods 和 IDE integrations。
- [Agent Client Protocol](https://agentclientprotocol.com/) —— ACP 官方协议说明。
- [Cursor MCP](https://cursor.com/docs/mcp.md) —— Cursor MCP 配置和使用背景。

## 接下来去哪

<Cards>
  <Card title="Headless 模式" description="继续学习 scripts 和 automation 中如何使用 print mode。" href="/docs/cursor/official/03-cli-automation/35-headless" />
  <Card title="MCP 与扩展" description="回到 Cursor MCP 配置和工具边界。" href="/docs/cursor/official/02-context-customization/21-mcp" />
</Cards>
