---
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

`fx acp` connects fx to editors that support Agent Client Protocol (ACP). The editor sends prompts and displays replies and tool activity; fx runs the agent.

## Configure an ACP client

Configure your client to launch fx with the `acp` argument. Use the executable and arguments fields in its agent settings:

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

Set the server process's working directory to your project. Clients can supply an absolute `cwd` with `session/new`, `session/load`, or `session/resume` to bind that session to another workspace. File access, project instructions, skills, and project MCP servers follow that directory.

`fx acp` accepts these options:

| Option | Description |
| --- | --- |
| `--model <id>` | Set the startup model, overriding the saved model when loading a session. |
| `--ultrafast` / `--no-ultrafast` | Request or disable the higher-priced [Ultrafast tier](https://fx.sh/docs/configure-fx/models.md#ultrafast-mode) for this process. Overrides `FX_ULTRAFAST` and saved preferences. |
| `--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

[Connect a provider](https://fx.sh/docs/getting-started/authentication.md) before starting the client. ACP uses your fx provider settings and credentials.

Project instructions and personal settings also apply when you use fx through an editor. MCP servers follow the [client-specific rules](#mcp-servers) below.

## Supported ACP methods

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

| Method | Description |
| --- | --- |
| `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 saved sessions across workspaces, or filter by an absolute `cwd`. |
| `session/prompt` | Run one turn in the active session. |
| `session/cancel` | Cancel the active prompt. |
| `session/set_config_option` | Change provider, model, mode, supported reasoning effort, or eligible Ultrafast mode. |
| `session/set_mode` | Change the active mode. |

Each connection runs one session and one prompt at a time. Wait for the prompt response, including after cancellation, before sending another prompt.

## Sessions, models, and permissions

Clients can select a provider, model, and mode. Models that support reasoning also expose an `effort` selector. Supported OpenAI models through AI Gateway expose an `ultrafast` selector for the higher-priced inference tier. Provider, model, and effort choices are saved with the session.

| ACP mode | Permission mode |
| --- | --- |
| `ask` | [`ask`](https://fx.sh/docs/configure-fx/permissions.md#modes): ask for approval. |
| `code` | [`auto`](https://fx.sh/docs/configure-fx/permissions.md#auto-mode): run routine work and review other actions. |

Mode changes apply to the active session. When creating or loading a session, fx starts with the configured permission mode until the client selects one.

**Allow for this session** approvals last until the session closes and are not restored on load.

### Ultrafast per session

Ultrafast is a higher-priced OpenAI tier through AI Gateway. Select an eligible model before opting in. For a process-only launch request, set your client's arguments to `["acp", "--model", "openai/gpt-6-astra", "--ultrafast"]`. `FX_ULTRAFAST` and the profile's `ultrafast_mode` also apply to the server.

For eligible models, the returned `configOptions` include a select option with `id: "ultrafast"`. After `session/new`, use its returned session ID in `session/set_config_option`:

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "session/set_config_option",
  "params": {
    "sessionId": "your-session-id",
    "configId": "ultrafast",
    "value": "true"
  }
}
```

Use the string `"false"` to disable it before the next prompt. JSON booleans and other values are rejected with `-32602`. Enabling it for an unsupported model is also rejected before a completion request.

Client changes are saved with the session and restored on load or resume. Launch flags and environment overrides remain process-local and can override that saved preference. An enabled option means the tier was requested, not that Gateway confirmed it was served. See [Ultrafast eligibility and confirmation](https://fx.sh/docs/configure-fx/models.md#eligibility-and-served-tier-confirmation).

## Prompt and MCP support

`session/prompt` accepts text, embedded resources, and inline images. Images use the selected model's image support or the [vision fallback](https://fx.sh/docs/capabilities/vision.md#how-vision-works) and are saved for history replay. Unsupported images return `-32602`; audio is not supported.

### Steering and instructions

Send a text `session/prompt` with `_meta.fx.steer: true` to guide an active turn without cancelling its current work. Check `agentCapabilities._meta.fx.steering` first. fx applies the message at the next safe model boundary; the steering request completes with the active turn.

To add session instructions, supply `systemPrompt` as text content blocks with `session/new`. Only append mode is supported; instructions follow fx's own system prompt and are restored with the session. The combined text is limited to 64 KiB. `_meta.fx.systemPrompt` is accepted for clients that cannot send the standard field; do not send both.

### Session updates

Clients receive streamed messages, tool activity, permission requests, session titles, and context usage.

| Update | Content |
| --- | --- |
| Message chunks | Text with a stable `messageId`, also used during history replay. |
| `tool_call` | Tool name, kind, pending status, and redacted JSON arguments. |
| `tool_call_update` | Tool completion or failure. |
| `session_info_update` | Session title after a prompt or when loading history. |
| `usage_update` | Provider-confirmed context usage when the context window is known; cost when fully available. |

Cancellation also stops pending permission and MCP input requests.

### MCP servers

Clients can supply stdio, HTTP, SSE, or `type: "acp"` servers through `mcpServers`. ACP servers use the existing client connection rather than a separate process or HTTP transport. fx combines client entries with approved servers from the project's `.mcp.json`; a client entry wins a same-name project entry.

Profile servers from `~/.fx/mcp.json` are not inherited unless the client sets `_meta.fx.profileMcpServers: true` when creating, loading, or resuming a session. See [MCP protocol reference](https://fx.sh/docs/capabilities/mcp/protocol.md#discovery-and-isolation) for authentication and isolation details.

## Protocol limits

ACP uses newline-delimited JSON-RPC 2.0 over stdin and stdout. Input messages are limited to 8 MiB; each inline image's padded base64 data is limited to 5 MiB. Oversized images return `-32602` before they are saved or sent to the model.

Stdout carries ACP messages. Send diagnostics to `--log-file` or `FX_TRACE_LOG`.

---

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