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:

OptionDescription
--permission-mode <mode>Set the mode new, loaded, and resumed sessions start in: ask, auto, or full-access. Overrides the saved mode for this process without saving it. --ask, --auto, and --full-access are shortcuts, and --yolo means --full-access.
--provider <name>Use gateway, codex, grok, or a configured connection for this process.
--model <id>Set the startup model, overriding the saved model when loading a session.
--effort <level>Set the reasoning effort new sessions start with. A loaded or resumed session keeps its saved effort.
--fast / --no-fastEnable or disable Fast mode for new sessions when the model supports it. A loaded or resumed session keeps its saved setting.
--ultrafast / --no-ultrafastRequest or disable the higher-priced Ultrafast tier for this process. Overrides FX_ULTRAFAST and saved preferences.
--log-file <path>Write ACP diagnostics to an absolute file path.

These are the same flags fx ask takes, except --provider-order and --provider-strict: ACP sessions don't apply AI Gateway provider routing. If the startup model doesn't support the requested effort, Fast mode, or Ultrafast, the client's initialize request fails with error -32602.

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:

MethodDescription
initializeNegotiate protocol capabilities and initialize the connection.
session/newCreate and activate a saved session.
session/loadLoad an exact session ID and replay its history.
session/resumeReconnect to a saved session without replaying its history.
session/closeClose the active session.
session/listList saved sessions across workspaces, or filter by an absolute cwd.
session/promptRun one turn in the active session.
session/cancelCancel the active prompt.
session/set_config_optionChange provider, model, mode, supported reasoning effort, Fast mode, or eligible Ultrafast mode.
session/set_modeChange 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. Until then, session/list, session/set_config_option, and a session/prompt that isn't a steering message fail with -32600. session/new, session/load, session/resume, and session/close cancel the running prompt first. A $/cancel_request notification that names the prompt's request ID cancels it like session/cancel.

Sessions, models, and permissions

Clients can select a provider, model, and mode. Models that support reasoning also expose an effort selector, and models with a Fast lane expose a fast selector. Supported OpenAI models through AI Gateway expose an ultrafast selector for the higher-priced inference tier. fast and ultrafast take the strings "true" and "false", and turning one on turns the other off. Switching to a model or provider that doesn't support the current speed turns it off. Provider, model, effort, Fast, and Ultrafast choices are saved with the session and restored on load or resume.

ACP modePermission mode
autoauto: run routine work and review other actions.
askask: ask for approval.
full-accessfull-access: run every action without fx permission checks.

A mode change applies to the active session and is saved as your permission mode in ~/.fx/settings.json, so later CLI and ACP sessions start in it. Each new, loaded, or resumed session starts in the saved mode, or in the mode set by --permission-mode when the server was launched with it.

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. fx skips audio and resource_link blocks.

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. Steering takes text blocks only, up to 64 KiB. Its response reports _meta.fx.steering: "absorbed" when the turn took the message, or "dropped" when a cancellation ended the turn first. If the turn ends on its own before taking the message, the request fails with -32600 so you can send it as a new prompt.

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, retry status, and context usage.

UpdateContent
Message chunksagent_message_chunk and user_message_chunk text with a stable messageId, also used during history replay. A delivered steering message appears as a user message chunk.
agent_thought_chunkReasoning text from the model.
tool_callTool name, kind, pending status, and redacted JSON arguments.
tool_call_updateTool progress, completion, or failure.
session_info_updateSession title after a prompt or when loading history. While fx retries a model request, _meta.fx.modelResponseRecovery carries its state, attempt, and status message; null clears it.
usage_updateProvider-confirmed context usage when the context window is known.
noticeContext notices, such as content left out to fit a context limit, for clients that set session.notices in clientCapabilities. Other clients receive them as message text.

When the agent starts subagents, the session/prompt response waits until each one reports. A report completes the subagent's tool call and then runs as another turn of the same prompt.

Cancellation also stops pending permission and MCP input requests, and stops waiting for subagent reports.

MCP servers

Clients can supply stdio and HTTP servers through mcpServers. A stdio entry needs an absolute command path, and an HTTP entry needs an HTTPS or loopback HTTP url. An invalid entry, or two entries with the same name, fails the request with -32602. fx does not connect to SSE servers or type: "acp" servers, and its initialize response does not advertise them. fx combines client entries with approved servers from the project's .mcp.json; a client entry wins a same-name project entry.

The model sees a client-supplied server's tools on every turn, without searching for them, unless the client sets _meta.fx.alwaysLoaded to false on that entry. Those schemas share the mcp_selected_schema_bytes context limit, and tools that don't fit stay available through capability_search.

ACP sessions do not open sign-in. The client can supply an Authorization header for its servers.

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; a larger message gets error -32000. fx saves an inline image that is too large for the model request, such as one over 5 MiB encoded, but doesn't send it. The model gets the image's size and the saved original's path instead, so it can make a smaller copy.

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