Allow enabling the streamable-HTTP standalone SSE stream from YAML for remote MCP toolsets

Read pkg/config/latest/types.go and the remote toolset construction path in pkg/tools/mcp/mcp.go; then find the matching Remote definition in agent-schema.json and the docs for remote: options. Trace how Toolset.SetStandaloneSSE() is used before Start. Done means YAML can opt in with standalone_sse, the default remains false, and the schema and documentation describe the option.

Overview

Add an optional boolean on remote: MCP toolsets, for example:

toolsets:
  - type: mcp
    remote:
      url: http://<gateway-host>/mcp
      transport_type: streamable-http
      standalone_sse: true   # new, default false

When true, the streamable-HTTP transport opens the standalone SSE GET stream: the optional GET on the same MCP endpoint that the streamable-HTTP spec defines for server-to-client messages (DisableStandaloneSSE: false in the go-sdk transport). This is unrelated to the legacy transport_type: sse transport, which uses a separate endpoint and protocol.

The plumbing already exists: Toolset.SetStandaloneSSE() (added in #3770) and remoteMCPClient.standaloneSSE in pkg/tools/mcp. As of v1.152.0 and current main, nothing in the YAML loading path calls it, and config/latest.Remote has no corresponding field, so a YAML-defined agent cannot enable it.

Motivation

This is needed for docker-agent to work reliably with Docker's sbx MCP gateway (the MCP gateway exposed inside an sbx sandbox, e.g. via sbx mcp). Both are Docker products and should work together out of the box; today they only partly do.

The comment on standaloneSSE in pkg/tools/mcp/remote.go already describes the situation: some MCP gateways send keepalive pings and "close the session when the ping cannot be delivered". With the standalone stream disabled (the default), that is what we observe with the sbx gateway:

1. docker-agent connects and lists tools. Without the standalone GET stream there is no channel for server-initiated messages.

2. The session is invalidated well under a minute after connect. docker-agent doesn't notice, because nothing is listening on a stream.

3. The next call fails and the supervisor reconnects:

   level=WARN msg="Authenticated MCP request was rejected by the server" url=http://<gateway-host>/mcp status=404 body="session not found\n"
   level=WARN msg="MCP call failed, forcing reconnect and retrying" ... error="... session not found"
   level=WARN msg="supervisor: session lost" ... forced=true
   

4. notifications/tools/list_changed is never received, so the toolset cache is never refreshed: across four rotated debug logs (about three days of use) there are zero MCP server notified tool list changed lines, even though the gateway changed its tool set several times.

The most visible consequence is OAuth-backed servers behind the gateway. When a server needs (re)authorization, the gateway exposes only an authorize tool in its place. The user completes the browser flow and the gateway connects the real backend and changes its tool set. docker-agent, however:

• re-listed tools before the user finished authorizing (during the reconnect described above), so it cached the pre-auth list;
• never receives tools/list_changed afterwards;
• has nothing that fails, so nothing triggers another reconnect or re-list.

The agents keep seeing only the stale list (in our case an agent resolved 1 tool, 27 s after authorization completed) until docker-agent is restarted. A fresh start lists the real tools immediately. The user did everything right and the tools still don't appear.

Use cases

1. Agents running inside an sbx sandbox that reach MCP servers through the sbx MCP gateway over streamable-http, where servers can be authorized, re-authorized, or loaded and unloaded while a session is running.
2. Any remote streamable-HTTP MCP gateway that uses keepalive pings or sends tools/list_changed on the standalone stream.
3. Multi-agent configs where each agent declares its own remote toolset. Each toolset holds its own session and its own tool cache, so every one of them goes stale independently.

Proposed solution

• Add StandaloneSSE bool (json:"standalone_sse,omitempty") to Remote in pkg/config/latest/types.go, and the matching property in agent-schema.json.
• In the remote-toolset construction path (pkg/tools/mcp/mcp.go, where toolset.Remote.URL is handled), call SetStandaloneSSE(toolset.Remote.StandaloneSSE) before Start.
• Keep the default false, as in #3770, because of the hang reported for some servers (commit 332f5928, go-sdk #633). It is opt-in, so there is no behaviour change for existing configs.
• Document it next to the other remote: options.

Alternatives

• /toolset-restart. It does re-list tools, but LocalRuntime.RestartToolset (pkg/runtime/runtime.go) only looks at the active agent's toolsets. When the stale toolset belongs to a sub-agent, there is nothing to restart from the TUI. The same toolset also can't be told apart from its siblings in a multi-agent config, because unnamed remote toolsets all share the description mcp(remote host=<host> transport=streamable-http).
• transport_type: sse. This is the legacy transport on a separate endpoint, not the standalone stream of streamable HTTP, and it requires server support that a streamable-HTTP-only gateway doesn't have.
• lifecycle: tuning (restart: always, max_restarts, backoff). It only governs reconnecting after a lost session is detected, and without a stream the loss is only detected when a call fails, so it doesn't help.
• Restart docker-agent after every in-session re-authorization. This works but defeats the point of in-session authorization.
• Enable it by default for streamable-http. This risks the hang cases in #3770, so an opt-in is safer.
• A gateway-side change (not to ping sessions that have no open stream) could also help, but it is complementary and out of scope here. Exposing the existing opt-in in YAML is the minimal, self-contained fix on the docker-agent side.

Related issues

• #3770 introduced SetStandaloneSSE as a library-only option with default false.

Additional context

Observed with docker-agent v1.152.0 and sbx 0.49.2. The evidence is from docker-agent's debug log only; sanitised excerpts are available on request.

We have not yet verified end to end that enabling the standalone stream keeps the gateway session alive and delivers tools/list_changed; that is the expected outcome based on the code and the comment in remote.go.