From 6760e6fb18404aa7da21a774c792869c6656e358 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Fri, 23 Oct 2026 13:24:27 +0000 Subject: [PATCH 1/3] docs: explain empty static MCP mode The MCP gateway guide omitted the empty static set and its unload behavior. Add a local-only example, value constraints, and persistence guidance without asserting a shipping version. --- content/manuals/ai/sandboxes/mcp-gateway.md | 26 +++++++++++++++++---- 1 file changed, 22 insertions(+), 4 deletions(-) diff --git a/content/manuals/ai/sandboxes/mcp-gateway.md b/content/manuals/ai/sandboxes/mcp-gateway.md index 12cee969dc3..adc1e99f2ce 100644 --- a/content/manuals/ai/sandboxes/mcp-gateway.md +++ b/content/manuals/ai/sandboxes/mcp-gateway.md @@ -73,6 +73,8 @@ sandbox, or use [`sbx mcp load`](#add-a-server-to-a-running-sandbox) for a sandbox that's already running. Server names can contain letters, numbers, dots, hyphens, and underscores. +The name `none` is reserved, regardless of capitalization, for the empty static +set described in [Use static mode](#use-static-mode). The `--url` flag can point to different kinds of input. The execution location depends on what you register: @@ -448,7 +450,8 @@ mode: registered servers. This choice persists across sandbox restarts unless you -[unload every server in the static set](#remove-a-server-from-a-running-sandbox). +[unload every server in a named static set](#remove-a-server-from-a-running-sandbox). +Sandboxes created with `--static-mcp none` remain static. ### Use static mode @@ -470,6 +473,19 @@ $ sbx run claude --name my-session \ Every name in the static set must already be registered with `sbx mcp add`. The gateway doesn't expose `mcp-find`, `mcp-add`, or `mcp-config-set` to the agent. +For versions of `sbx` that support `--static-mcp none`, pass `none` to +`sbx create` or `sbx run` to start a local sandbox with no MCP servers and no +dynamic discovery tools: + +```console +$ sbx run claude --name mcp-empty --static-mcp none +``` + +`none` is case-insensitive and can't be combined with server names. Cloud +sandboxes don't support this value. You can load registered servers later with +[`sbx mcp load`](#add-a-server-to-a-running-sandbox). The sandbox remains in +static mode after loading or unloading servers and across restarts. + You can't replace the initial set by passing `--static-mcp` when reconnecting to an existing sandbox. To attach another server from the host, use [`sbx mcp load`](#add-a-server-to-a-running-sandbox). @@ -525,9 +541,11 @@ $ sbx mcp load linear --sandbox my-session In dynamic mode, the agent can also find and attach the registered server again. Unloading a server doesn't prevent the agent from reloading it. -If you unload all servers from a static sandbox, it stays in static mode for -the current session. After restarting the Docker Sandboxes daemon and -reconnecting, the agent can find and attach registered servers. +If you unload all servers from a sandbox created with a named static set, it +stays in static mode for the current session. After restarting the Docker +Sandboxes daemon and reconnecting, the agent can find and attach registered servers. A sandbox +created with `--static-mcp none` keeps dynamic discovery disabled after unloading +its last server and restarting. ## Built-in gateway tools From 8663a30546f7d04f28517e9e8865d18eaaa97a77 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Fri, 23 Oct 2026 15:10:28 +0000 Subject: [PATCH 2/3] docs: separate starting sandboxes without MCP servers Starting without MCP servers is a distinct use case from preloading named servers. Give it a dedicated subsection and keep option constraints there. --- content/manuals/ai/sandboxes/mcp-gateway.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/content/manuals/ai/sandboxes/mcp-gateway.md b/content/manuals/ai/sandboxes/mcp-gateway.md index adc1e99f2ce..f04a378b4b3 100644 --- a/content/manuals/ai/sandboxes/mcp-gateway.md +++ b/content/manuals/ai/sandboxes/mcp-gateway.md @@ -73,8 +73,8 @@ sandbox, or use [`sbx mcp load`](#add-a-server-to-a-running-sandbox) for a sandbox that's already running. Server names can contain letters, numbers, dots, hyphens, and underscores. -The name `none` is reserved, regardless of capitalization, for the empty static -set described in [Use static mode](#use-static-mode). +The name `none` is reserved for +[starting a sandbox without MCP servers](#start-without-mcp-servers). The `--url` flag can point to different kinds of input. The execution location depends on what you register: @@ -444,8 +444,8 @@ integrations read the gateway URL and register it with the agent. Whether you pass `--static-mcp` when you create the sandbox determines its MCP mode: -- Static mode pre-loads the specified servers and doesn't expose dynamic - discovery tools to the agent. +- Static mode loads only the servers you specify, or starts without servers + if you specify `none`. It doesn't expose dynamic discovery tools to the agent. - Dynamic mode pre-loads no servers and lets the agent find and attach registered servers. @@ -473,6 +473,12 @@ $ sbx run claude --name my-session \ Every name in the static set must already be registered with `sbx mcp add`. The gateway doesn't expose `mcp-find`, `mcp-add`, or `mcp-config-set` to the agent. +You can't replace the initial set by passing `--static-mcp` when reconnecting to +an existing sandbox. To attach another server from the host, use +[`sbx mcp load`](#add-a-server-to-a-running-sandbox). + +### Start without MCP servers + For versions of `sbx` that support `--static-mcp none`, pass `none` to `sbx create` or `sbx run` to start a local sandbox with no MCP servers and no dynamic discovery tools: @@ -486,10 +492,6 @@ sandboxes don't support this value. You can load registered servers later with [`sbx mcp load`](#add-a-server-to-a-running-sandbox). The sandbox remains in static mode after loading or unloading servers and across restarts. -You can't replace the initial set by passing `--static-mcp` when reconnecting to -an existing sandbox. To attach another server from the host, use -[`sbx mcp load`](#add-a-server-to-a-running-sandbox). - ### Use dynamic mode Omit `--static-mcp` to use dynamic mode. The gateway pre-loads no servers and From 00ae46217475fe1c6158d04f21211ca881ea42bb Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Fri, 23 Oct 2026 15:19:13 +0000 Subject: [PATCH 3/3] docs: remove version qualification from empty MCP setup The empty static MCP setup instructions unnecessarily qualify support by version. Describe the command directly, consistent with the requested documentation style. --- content/manuals/ai/sandboxes/mcp-gateway.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/content/manuals/ai/sandboxes/mcp-gateway.md b/content/manuals/ai/sandboxes/mcp-gateway.md index f04a378b4b3..7c74ce76c60 100644 --- a/content/manuals/ai/sandboxes/mcp-gateway.md +++ b/content/manuals/ai/sandboxes/mcp-gateway.md @@ -479,9 +479,8 @@ an existing sandbox. To attach another server from the host, use ### Start without MCP servers -For versions of `sbx` that support `--static-mcp none`, pass `none` to -`sbx create` or `sbx run` to start a local sandbox with no MCP servers and no -dynamic discovery tools: +Pass `--static-mcp none` to `sbx create` or `sbx run` to start a local sandbox +with no MCP servers and no dynamic discovery tools: ```console $ sbx run claude --name mcp-empty --static-mcp none