AI coding agents become far more useful when they can reach real tools: your issue tracker, your docs workspace, a browser automation server, or an internal API. The Model Context Protocol (MCP) is how most agents do that today. The problem is that wiring MCP servers straight into an agent usually means pasting tokens into config files, and those files end up inside the same environment the agent controls.
Docker Sandboxes solves this with a built-in MCP gateway. The official MCP gateway guide on docs.docker.com was updated this week, including a new --static-mcp none option. This post walks through how the gateway works, how to register remote and local servers, how OAuth and header secrets stay on the host, and how to choose between static and dynamic MCP modes for each sandbox.
How the sandbox MCP gateway works
Every sandbox starts its own MCP gateway. The agent inside the sandbox sees exactly one MCP endpoint. Behind that endpoint, the sbx CLI on your host keeps the list of registered servers, the OAuth tokens, and any secrets used in request headers. When the sandbox boots, supported agent integrations read the gateway URL and register it with the agent automatically.
This is a different model from configuring MCP inside the agent itself. With direct setup, Claude Code (or any other agent) holds its own MCP client config and its own credentials. With the sandbox gateway, you register a server once on the host, and you decide per sandbox which servers the agent can use. Credentials never need to be copied into the microVM.
Two points are easy to miss:
- The Docker Sandboxes MCP gateway is not the Docker Desktop MCP Toolkit. You don’t need the Toolkit to use
sbx mcp, and settings are not shared between the two. - Local stdio MCP servers run on the host, not inside the sandbox. The agent only talks to the gateway. That matters for security, which we cover below.
Prerequisites
- Docker Sandboxes installed with the
sbxCLI. See the install guide. - Signed in with
sbx login. - An agent integration that configures MCP at startup. The docs list Claude Code, Codex, Devin, Gemini, Kiro and OpenCode.
- Docker installed and running on the host if you register local servers from OCI metadata (
--local --url) or with--command docker. - For remote OAuth servers that don’t support Dynamic Client Registration, an OAuth client that you registered with the provider.
Step 1: Register a remote MCP server and start a sandbox
Registration happens on the host with sbx mcp add. It records the server definition but does not attach it to any sandbox. Start with a remote endpoint:
sbx mcp add notion --url https://mcp.notion.com/mcp
If the server uses OAuth, sbx opens the authorization flow before it saves the registration. Tokens are stored in the host operating system’s credential store. Check what is registered:
sbx mcp ls
The listing shows each server’s transport, status, gateway and details. Now launch Claude Code in a sandbox and expose only that server:
sbx run claude --name mcp-demo --static-mcp notion
The sandbox starts with a gateway that already has the notion server loaded. The registration stays on the host, so any other sandbox can reuse it. Server names can use letters, numbers, dots, hyphens and underscores. The name none is reserved, for reasons covered in Step 4.
Remote servers that need an API key header
Some remote servers authenticate with a static API key instead of OAuth. Use --header with a secret placeholder, then store the value in the host secret store:
sbx mcp add acme --url https://mcp.acme.com/mcp \
--header 'Authorization: Bearer ${api-key}'
sbx secret set mcp:acme:api-key
The ${api-key} placeholder stays in the registration as text. When a sandbox connects, the gateway looks up the secret named mcp:acme:api-key and fills it into the header. The placeholder refers to a stored secret, not a shell environment variable, so always wrap the header in single quotes to stop your shell from expanding it. Credential headers such as Authorization must use a placeholder, and these header secrets live in the global scope on the host.
After you change or rotate a header secret, stop and restart the sandbox (or restart sandboxd). An open connection keeps the old value, and a server that was skipped because its secret was missing is not retried on its own.
Step 2: Run local stdio MCP servers
Many MCP servers speak stdio instead of HTTP. For these, sbx launches the process on the host and bridges it into the gateway. You have three options.
From registry or manifest metadata. Point --local --url at an MCP community registry entry, or at a URL that returns a server.json or server.yaml. The entry must describe an OCI package with stdio transport. sbx resolves the image and runs it with Docker on the host:
sbx mcp add fetch --local \
--url https://registry.modelcontextprotocol.io/v0/servers/fetch-mcp/versions/latest
If the metadata only publishes non OCI packages (npm, for example), the registration is rejected. Use an explicit command for those.
From an explicit command. Use --command and --args when you know exactly what to run, or when you need custom docker run flags:
sbx mcp add playwright --command npx --args @playwright/mcp@latest
sbx mcp add local-image-server --command docker \
--args "run,-i,--rm,your/image"
To set the working directory of the host process, add --dir, which is only valid together with --command:
sbx mcp add local-fs --command node --args server.js --dir /srv/data
From a Docker Hardened Image. If the server ships as a Docker Hardened Image, pass the dhi.io reference with a tag or digest:
sbx mcp add fetch --url dhi.io/fetch-mcp:latest
A word of caution from the docs: local stdio servers sit outside sandbox isolation. If the command starts a container, that container gets normal host Docker isolation, not microVM isolation. The process can see host files, host network resources and any credentials you hand it. Only register commands and images you trust, and avoid mounting host paths unless the server needs them.
Step 3: OAuth servers without Dynamic Client Registration
In local gateway mode, you can register remote OAuth servers that need a pre-registered client. If the server does not publish OAuth metadata, provide an RFC 8414 authorization server metadata document (a local file or an HTTP or HTTPS URL that defines authorization_endpoint and token_endpoint) together with your client ID:
sbx mcp add serverx --url https://mcp.serverx.example/mcp \
--oauth-authorization-server ./serverx-authorization-server.json \
--client-id CLIENT_ID
For a confidential client there is no --client-secret flag. Store the secret first, then register:
sbx secret set mcp:slack:client_secret
sbx mcp add slack --url https://slack.example.com/mcp \
--client-id CLIENT_ID
The client secret stays in the host credential store and is never written to the MCP registration. If a confidential client has no stored secret, registration still succeeds but authorization is skipped. Inside the sandbox, each OAuth backed remote server also gets a helper tool named <server>-authorize (for example notion-authorize), which the agent can call to authorize or reauthorize. Until the server is authorized, that helper is the only tool exposed for it.
Step 4: Pick an MCP mode per sandbox
The --static-mcp flag you pass when you create a sandbox decides its MCP mode, and that choice survives restarts.
Static mode loads only the servers you name. The gateway does not expose the discovery tools mcp-find, mcp-add or mcp-config-set, so the agent cannot pull in extra servers by itself. Pass a comma separated list, or repeat the flag:
sbx run claude --name my-session --static-mcp notion,linear
Every name must already be registered. You can’t swap the initial set by passing --static-mcp again when reconnecting to an existing sandbox.
No MCP at all. The newest addition to the guide is --static-mcp none. It starts a local sandbox with no servers and no discovery tools, which is a good default for agents that should only touch code:
sbx run claude --name mcp-empty --static-mcp none
The value is case insensitive and cannot be mixed with server names. The sandbox stays static even after you load or unload servers and across restarts.
Dynamic mode is what you get when you leave out --static-mcp. No servers are preloaded, but the gateway exposes mcp-find, mcp-add and mcp-config-set, so the agent can search the registered catalog and attach servers during the session. If you register a new server on the host while a dynamic sandbox is running, its searchable catalog refreshes without a restart.
Attach and detach servers on a running sandbox
In either mode, you can attach a registered server from the host:
sbx mcp load linear --sandbox my-session
Connected agent sessions get a tool list update, so the new tools appear without reconnecting, and the attachment survives restarts. From Docker Sandboxes v0.48.0, you can also detach a server from a running local gateway:
sbx mcp unload linear --sandbox my-session
Unloading removes the saved attachment but keeps the host registration and credentials, and other sandboxes using that server are not affected. In dynamic mode, keep in mind that the agent can find and attach the server again.
Local Sandboxes vs Cloud Sandboxes
The guide describes the local MCP gateway. Cloud Sandboxes take a different path: they use MCP servers configured in Docker Agentic Platform rather than servers registered with sbx mcp add. The docs call out a few specific differences:
--static-mcp noneis not supported for cloud sandboxes.- Cloud sandboxes and hosted MCP gateways do not support
sbx mcp unload. - Custom request headers need the host to connect to the server. The hosted gateway rejects header based registrations unless you also supply
--oauth-authorization-server, which routes the connection through the host.
For cloud runs, plan your MCP configuration in Docker Agentic Platform.
Troubleshooting tips
- Remote streams stall. If a remote server’s HTTP/2 handling stalls long lived streams, register it with
--disable-http2to fall back to HTTP/1.1. The flag needs--urland can’t be combined with--commandor--local. - Header secret changes are ignored. Restart the sandbox or
sandboxdafter setting, rotating or removing a header secret. - A local registration is rejected. The registry entry or manifest probably doesn’t publish an OCI stdio package. Switch to
--command. - Warnings about private addresses. If a
--urlhostname resolves to a private, loopback, link local or cloud metadata address,sbxregisters the server but warns you. - Agent cannot see a server you just registered. Registration alone doesn’t attach anything. Use
--static-mcpat creation time orsbx mcp loadon a running sandbox.
sbx mcp add acme --url https://mcp.acme.com/mcp --disable-http2
Key takeaways
- The sandbox MCP gateway gives the agent one endpoint while credentials and server definitions stay on the host.
sbx mcp addregisters a server;--static-mcporsbx mcp loadattaches it to a sandbox.- Header API keys use
${placeholder}values backed bysbx secret set mcp:<server>:<name>. - Local stdio servers run on the host, outside microVM isolation, so only register trusted commands and images.
- Use static mode for tight control,
--static-mcp nonefor MCP free agents, and dynamic mode when the agent should discover tools itself. - Cloud Sandboxes use MCP servers configured in Docker Agentic Platform and do not support every local gateway option.
References
This post is based on the official Docker Sandboxes MCP gateway guide. For related details, see the sbx mcp add reference, the sbx mcp load and sbx mcp unload references, the Docker Sandboxes troubleshooting page, the install guide, and the local vs cloud sandboxes comparison.