sbx mcp add, sbx mcp load, and --static-mcp

You want the agent to read documentation through an MCP server, and you do not want that server's token inside the VM. sbx mcp keeps the registration, the OAuth tokens, and any local server process on the host, and gives the sandbox one URL.

When you finish this section, you can register a server, pick static or dynamic mode, and load a server into a running sandbox.

Register on the host

sbx mcp add: registers an MCP server by name. sbx validates the server and stores its specification for --static-mcp on sbx create and sbx run.

--url takes four forms: a remote endpoint, a community-registry URL, a server.json or server.yaml manifest URL, and a dhi.io/ image reference. Other image references are rejected, and --local runs a registry OCI server on the host with docker run. The capture registered one remote server and listed it:

{
  "gateway": {
    "name": "LOCAL",
    "local": true,
    "operator": "managed by you",
    "decision": "local",
    "signed_in_as": "<docker-user>"
  },
  "servers": [
    {
      "name": "m101-deepwiki",
      "transport": "remote http",
      "status": "ready",
      "type": "remote"
    }
  ]
}

The help's own registry example did not resolve on 2026-10-08: the add of https://registry.modelcontextprotocol.io/v0/servers/fetch-mcp/versions/latest failed with registry returned status 404 (the capture). --command is the other input, and it runs on the host with all the permissions of your host user. A local server that starts a container uses host Docker, outside the engine boundary of the microVM.

OAuth metadata is discovered through RFC 9728 and RFC 8414, or supplied by hand with --oauth-authorization-server. --client-id names a pre-registered client, and dynamic registration follows RFC 7591. --scope records default scopes with a documented precedence, --resource sets the RFC 8707 indicator, and --callback-port pins the listener. Tokens stay on the host, and sbx mcp auth [server|--all], auth status, and auth rm manage them.

The deepwiki server needs none: sbx mcp inspect reports requires_oauth: false, and auth status --all --json printed [], so no OAuth flow was captured. A confidential client's secret and any --header 'Name: ${placeholder}' value come from the secret store as mcp:<server>:client_secret and mcp:<server>:<placeholder>. A header-bearing registration is rejected on the hosted gateway.

One gateway per sandbox

MCP gateway: an endpoint on the host that gives agents access to the registered MCP servers. Inside m101-mcp the environment holds MCP_GATEWAY_URL=http://mcp-gateway.docker.internal/mcp and MCP_SENTINEL_TOKEN_NAME=proxy-managed (the capture). The docs list the agents that read that URL at start: Claude Code, Codex, Devin, Gemini, Kiro, and OpenCode. Docker Agent is absent from that list. A plain shell sandbox reached the gateway with curl all the same (the capture):

HTTP/1.1 200 OK
…
Content-Type: text/event-stream
…
Mcp-Session-Id: <session>
…
event: message
id: <event-id>
data: {"jsonrpc":"2.0","id":1,"result":{"capabilities":{"logging":{},"prompts":{"listChanged":true},"resources":{"listChanged":true},"tools":{"listChanged":true}},"instructions":"### m101-deepwiki…"protocolVersion":"2025-11-25","serverInfo":{"name":"mcp-gateway-m101-mcp","version":"0.1.0"}}}

The gateway names itself mcp-gateway-m101-mcp, one per sandbox, answers protocol version 2025-11-25, and declares tools.listChanged: true. sbx mcp ls adds a GATEWAY column, LOCAL, managed by you, with signed_in_as in the JSON. mcp.forceLocalGateway, default false, and SBX_MCP_URL=none select the local data plane when an account would otherwise use the hosted gateway.

The docs separate it from the Desktop product: sbx mcp works without the Docker Desktop MCP Toolkit. Network policy does not apply to a server the host registered, as Kevin Wittek said on 2026-09-04. A server the agent starts inside the VM is subject to it. DMR, Compose models, and the MCP gateway service covers the Toolkit gateway.

Static and dynamic

Static mode: --static-mcp a,b at create or run fixes the set once at creation. The static sandbox exposed the three deepwiki tools plus code-mode and mcp-exec, and no discovery tool. The dynamic sandbox started with discovery tools only, and sbx mcp load m101-deepwiki --sandbox m101-mcp-dyn added the three:

$ sbx mcp load m101-deepwiki --sandbox m101-mcp-dyn
MCP server "m101-deepwiki" loaded into sandbox "m101-mcp-dyn" (live)

The help promises the notice: connected agents see the tools of the new server at once, through the standard MCP tools/list_changed notification. The probe opened a new session for each run, so it recorded the two lists and not the notification itself. The built-in tools belong to the gateway: mcp-exec, code-mode, mcp-find, mcp-add, mcp-config-set, and <server>-authorize for OAuth servers. In Cedar MCP policies those are MCP::Primordial resources and a server's tools are MCP::Tool resources, which org policies returns to.

sbx mcp catalog was removed in v0.45.0, and the sbx mcp enable of the product page never existed (conflict C11). Figure 3.7 draws the store, the two gateways, and the load. For the protocol itself, read the MCP lesson.