Skip to content

docs: feat(mcp): add --static-mcp none #26428

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dvdksn wants to merge 3 commits into
base: main
Choose a base branch
from
Open

docs: feat(mcp): add --static-mcp none #26428

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
6760e6f
docs: explain empty static MCP mode
dvdksn Oct 23, 2026
8663a30
docs: separate starting sandboxes without MCP servers
dvdksn Oct 23, 2026
00ae462
docs: remove version qualification from empty MCP setup
dvdksn Oct 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 25 additions & 6 deletions content/manuals/ai/sandboxes/mcp-gateway.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 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:
Expand Down Expand Up @@ -442,13 +444,14 @@ 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.

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

Expand All @@ -474,6 +477,20 @@ 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

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

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

### Use dynamic mode

Omit `--static-mcp` to use dynamic mode. The gateway pre-loads no servers and
Expand Down Expand Up @@ -525,9 +542,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

Expand Down