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:

{
  "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:

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

Authentication and fx settings

Connect a provider 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 below.

Supported ACP methods

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

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.

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:

{
  "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.

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

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