---
title: "ACP server"
description: "Run fx from editors and clients that support Agent Client Protocol."
canonical_url: https://fx.sh/docs/using-fx/acp
markdown_url: https://fx.sh/docs/using-fx/acp.md
---

# ACP server

Run fx as an Agent Client Protocol (ACP) server to use the fx agent from compatible editors and clients.

## Configure an ACP client

Start the server from the project that should be the primary workspace:

```bash
cd /absolute/path/to/project && fx acp
```

Configure the client to launch the absolute binary path when possible:

```json
{
  "command": "/absolute/path/to/fx",
  "args": ["acp"]
}
```

The client process working directory becomes the primary workspace. Launch a separate server process for each primary workspace.

`fx acp` accepts two options:

| Option | Behavior |
| --- | --- |
| `--model <id>` | Override the model for the server process, including loaded sessions. |
| `--log-file <path>` | Write ACP diagnostics to an absolute file path. |

Global workspace flags such as `--add-dir`, `--no-additional-dirs`, and `--context-limit` must appear before `acp`.

## Authentication and fx settings

ACP uses the existing fx authentication and configuration. Complete [Authentication](https://fx.sh/docs/getting-started/authentication.md) before the client starts the server. Initialization fails when no usable AI Gateway credential is available.

The server uses the same settings, project instructions, skills, sessions, permissions, sandbox, and tools as interactive fx.

## Supported ACP methods

The client must call `initialize` first. fx responds with ACP protocol version `1` and supports these methods:

| Method | Behavior |
| --- | --- |
| `initialize` | Negotiate protocol capabilities and initialize the connection. |
| `session/new` | Create and activate a saved session. |
| `session/load` | Load an exact session ID and replay its history. |
| `session/resume` | Reconnect to a saved session without replaying its history. |
| `session/close` | Close the active session. |
| `session/list` | List sessions for the primary workspace. |
| `session/prompt` | Run one turn in the active session. |
| `session/cancel` | Cancel the active prompt. |
| `session/set_config_option` | Change the active model or mode. |
| `session/set_mode` | Change the active mode. |

Each connection has one active session and one active prompt.

## Sessions, models, and permissions

New and loaded sessions expose model and mode selectors. Model changes are saved to the active session, while a process-level `--model` override takes precedence over the model stored in a loaded session.

| Mode | Permission behavior |
| --- | --- |
| `ask` | Request approval for unresolved sensitive tool calls. |
| `code` | Automatically review unresolved sensitive tool calls. |

Both modes expose the available runtime tools. Before the client selects a mode, fx uses the permission mode from the active configuration.

An **Allow for this session** approval remains active only for the current session. It is not written to settings or restored when the session is loaded again.

## Prompt and MCP support

`session/prompt` accepts text and embedded resource blocks. ACP does not accept image or audio blocks; use interactive fx or `fx ask --image` for visual input.

Clients receive streamed user and agent messages, tool status updates, and permission requests.

ACP sessions use only the `mcpServers` supplied by the client. They do not inherit servers from `~/.fx/mcp.json`; omitting `mcpServers` starts the session without MCP servers. Clients can provide stdio, HTTP, or SSE servers.

## Protocol limits

ACP uses newline-delimited JSON-RPC 2.0 over stdin and stdout. Each input message is limited to 8 MiB.

> **Protect the protocol stream**
>
> Stdout is reserved for ACP messages. Write diagnostics to `--log-file` or `FX_TRACE_LOG` instead.

---

[Browse all fx documentation](https://fx.sh/llms.txt)