AgentSky
Log inSign up

Add MCP servers to an existing session via the API

PATCH a session with mcp_servers_mode "append" to add MCP servers, such as a Mac reach, without replacing the ones it already has.

Updated November 3, 2026

Send PATCH /v1/sessions/{id} with mcp_servers_mode: "append" to add MCP servers to a session and keep the ones it already has.

  1. Call PATCH /v1/sessions/{id} with mcp_servers and "mcp_servers_mode": "append".
  2. Leave out the mode, or send "replace", to keep the default behaviour: the list you send replaces the session's MCP servers.
  3. A running turn is not interrupted. The session picks up the new servers the next time it is idle.

Example body: {"mcp_servers_mode": "append", "mcp_servers": [{"name": "mac-browser", "url": "https://…/mcp"}]}

Good to know: append keeps existing servers and their stored credentials. It is refused if a name is already in use, or if the session would have more than twenty MCP servers in total.

A Mac reach URL must be a live one from your own Mac, in the session's workspace, and nobody else can be a member of that workspace or invited to it. It is tied to the session's task and can't be lent to an unrelated task. Archiving or deleting the task, or one day without activity, revokes it. Each tool call relayed to your Mac is recorded in the transcript with the resource it used and its result status.

Where: API, or call_api from the Use AgentSky as an MCP server and sky api from the Use the sky CLI. Related: Use the AgentSky API, Give an agent access to a folder on your Mac.

View as Markdown