MCP gateway

Docker Sandboxes includes an MCP gateway for connecting agents to Model Context Protocol servers. The gateway gives the agent inside the sandbox one MCP endpoint, while sbx manages the registered servers, OAuth credentials, and sandbox lifecycle on the host.

This is different from configuring an MCP server directly in an agent such as Claude Code. Direct MCP setup configures that agent's own MCP client. With Docker Sandboxes, you register MCP servers once on the host, and the sandbox gateway exposes them to supported agents inside isolated sandboxes. That host-managed gateway provides a single path for credentials, explicit server loading, live updates, and organization governance.

Note

The Docker Sandboxes MCP gateway is separate from the Docker Desktop MCP Toolkit. You don't need the Docker Desktop MCP Toolkit to use sbx mcp, and MCP Toolkit server settings aren't shared with Docker Sandboxes.

Prerequisites

• Sign in with sbx login.
• Use an agent integration that configures MCP at startup: Claude Code, Codex, Gemini, Kiro, or OpenCode.
• For remote servers that require OAuth without Dynamic Client Registration, register an OAuth client with the server provider.
• For --local --url registrations that resolve to OCI packages, use a host with Docker installed and running. Docker is also required for explicit --command docker ... registrations.

Quick start

Start by registering one MCP server on the host:

$ sbx mcp add notion --url https://mcp.notion.com/mcp

If the server requires OAuth, sbx opens an authorization flow before it stores the registration. After registration, verify that the server is registered:

$ sbx mcp ls
NAME                 TYPE     URL/COMMAND
notion               remote   https://mcp.notion.com/mcp

Then start a sandbox and expose the registered server:

$ sbx run claude --name mcp-demo --static-mcp notion

The sandbox starts with an MCP gateway and pre-loads the notion server. The registration remains on the host and can be reused by other sandboxes.

Register an MCP server

sbx mcp add registers an MCP server by name. The registration records the server definition on the host. It doesn't attach the server to a sandbox by itself. To expose a registered server to a sandbox, pass it with --static-mcp when you create the sandbox, or use sbx mcp load for a sandbox that's already running.

Server names can contain letters, numbers, dots, hyphens, and underscores.

The --url flag can point to different kinds of input. The execution location depends on what you register:

• A remote endpoint URL identifies a running MCP server. The server runs remotely, and the sandbox gateway connects to it.
• A metadata URL with --local returns a registry entry, server.json, or server.yaml that describes an OCI-packaged stdio server. sbx resolves the image and runs it on the host with Docker.
• An explicit command runs on the host as a stdio MCP server.

Local stdio servers run on the host, not inside the sandbox. The agent inside the sandbox connects only to the MCP gateway.

Remote endpoint URL

For a remote MCP endpoint, pass the server URL:

$ sbx mcp add notion --url https://mcp.notion.com/mcp
$ sbx mcp add linear --url https://mcp.linear.app/mcp

Local stdio server

Some MCP servers communicate over stdio instead of exposing a remote HTTP endpoint. Use a local stdio server when sbx should launch the MCP server on the host. You can provide a metadata URL or an explicit command.

From registry or manifest metadata

Use --local --url when you have an MCP community registry URL or a URL that returns a server.json or server.yaml document. The registry entry or manifest must describe an OCI package that uses stdio transport. sbx doesn't launch non-OCI package types, such as npm, from metadata. To use those servers, register an explicit command.

This path resolves the image from the metadata and starts it on the host with Docker, so Docker must be installed and running on the host.

$ sbx mcp add fetch --local \
  --url https://registry.modelcontextprotocol.io/v0/servers/fetch-mcp/versions/latest

If the entry doesn't publish an OCI stdio package, sbx rejects the registration instead of starting it locally.

A server manifest describes the MCP server package and how to start it. It can be hosted on a GitHub raw URL, internal HTTP server, or CDN.

$ sbx mcp add opine --local --url https://example.com/mcp/opine/server.yaml

From an explicit command

Use --command when you already know the executable and arguments, or when you need custom Docker flags. The command can be a package runner such as npx or a Docker container command:

$ 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 for the host process, pass --dir. This flag is only valid with --command:

$ sbx mcp add local-fs --command node --args server.js --dir /srv/data

Use registry or manifest metadata when you have a published server definition and don't need to customize docker run. Use --command for local development, private servers, or custom container flags.

Warning

Local stdio servers run on the host, outside sandbox isolation. If the command starts a Docker container, that container uses host Docker isolation, not sandbox isolation. The process or container can access host files, host network resources, and credentials made available to it. Use trusted commands and images, and avoid mounting host paths or passing credentials unless the server needs them.

Authorize OAuth-backed servers

If a registered remote server requires OAuth, sbx mcp add starts the authorization flow by default:

$ sbx mcp add notion --url https://mcp.notion.com/mcp
Resolving MCP server "notion"...
Open this URL to authorize MCP server "notion":
https://api.notion.com/v1/oauth/authorize?...
MCP server "notion" authorized
MCP server "notion" registered (type: remote)

OAuth credentials stay on the host. In local gateway mode, sbx stores tokens in the host operating system's credential store.

To register an OAuth-backed server without authorizing it, pass --skip_auth:

$ sbx mcp add notion --url https://mcp.notion.com/mcp --skip_auth

Use a pre-registered OAuth client

In local gateway mode, you can register a remote OAuth server that doesn't support Dynamic Client Registration. If the server publishes OAuth metadata, pass the client ID that you registered with the server provider:

$ sbx mcp add slack --url https://slack.example.com/mcp \
  --client-id <CLIENT_ID>

If the server doesn't publish OAuth metadata, pass --oauth-authorization-server with the client ID. The flag accepts a local file path or an HTTP or HTTPS URL to an RFC 8414 authorization server metadata document. The document must define authorization_endpoint and token_endpoint:

$ sbx mcp add serverx --url https://mcp.serverx.example/mcp \
  --oauth-authorization-server ./serverx-authorization-server.json \
  --client-id <CLIENT_ID>

These flags are only valid with --url.

For a confidential OAuth client, store the client secret before registering the server. There is no --client-secret flag:

$ 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 encrypted host credential store and isn't written to the MCP registration. If the server requires a confidential client and no secret is stored, registration succeeds but authorization is skipped. Store the secret, then run sbx mcp auth <server>.

Set OAuth scopes

Use the repeatable --scope flag to record the default scopes requested during authorization:

$ sbx mcp add serverx --url https://mcp.serverx.example/mcp \
  --scope read --scope write

The sbx mcp auth command also accepts --scope to override the recorded defaults for one authorization. If the authorization server advertises supported scopes, every requested scope must be in that set.

For each OAuth-backed remote server exposed to a sandbox, the gateway exposes a helper tool named <server>-authorize, such as notion-authorize. The agent can call the tool to authorize or reauthorize the server. If the server isn't authorized, the helper is the only tool exposed for that server.

You can manage OAuth credentials from the host:

$ sbx mcp auth status notion
$ sbx mcp auth notion
$ sbx mcp auth rm notion

Use --all to apply auth, auth status, or auth rm to all registered OAuth-backed servers. Use --format=json for machine-readable output.

Choose an MCP mode

Every sandbox starts an MCP gateway. When the sandbox starts, supported agent 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.
• Dynamic mode pre-loads no servers and lets the agent find and attach registered servers.

This choice persists across sandbox restarts.

Use static mode

Pass --static-mcp to pre-load registered MCP servers:

$ sbx mcp add notion --url https://mcp.notion.com/mcp
$ sbx mcp add linear --url https://mcp.linear.app/mcp
$ sbx run claude --name my-session --static-mcp notion,linear

You can pass --static-mcp as a comma-separated list or repeat the flag:

$ sbx run claude --name my-session \
  --static-mcp notion --static-mcp linear

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.

Use dynamic mode

Omit --static-mcp to use dynamic mode. The gateway pre-loads no servers and exposes mcp-find, mcp-add, and mcp-config-set to the agent. The agent can search the registered server catalog and attach servers during the session.

If you run sbx mcp add after a dynamic sandbox starts, its gateway refreshes the searchable catalog. The agent can then find and attach the new registration without restarting. The sbx mcp add command doesn't attach the server by itself.

Add a server to a running sandbox

To attach an already-registered server to a running sandbox, use sbx mcp load. This works in both static and dynamic modes:

$ sbx mcp add linear --url https://mcp.linear.app/mcp
$ sbx mcp load linear --sandbox my-session
MCP server "linear" loaded into sandbox "my-session" (live)

Connected agent sessions receive a tool-list update, so the added tools become visible without reconnecting. The loaded server remains attached across sandbox restarts.

Built-in gateway tools

The local MCP gateway exposes a small set of built-in tools. These tools belong to the gateway itself, not to a registered MCP server. Agents can see and call them on the same MCP connection as server tools, so they can appear in agent tool lists, logs, policy decisions, audit logs, or approval prompts.

You don't need to call these tools directly for normal setup. Use sbx mcp commands to register servers and manage credentials from the host. The tools matter because agents can call them during a session, and admins can govern them separately from tools provided by registered MCP servers.

Servers attached with mcp-add remain attached across sandbox restarts. The gateway exposes <server>-authorize for OAuth-backed remote servers, even when they already have a valid token. Local stdio servers don't expose this helper. If code-mode creates a generated tool, the tool is shared by clients connected to the sandbox's gateway and disappears when the gateway is replaced or stops.

In MCP access policies, built-in gateway tools are MCP::Primordial resources and use the invokePrimordial action. Tools from registered MCP servers are MCP::Tool resources and use the invokeTool action. For details, see the MCP policy reference.

Manage registrations

List registered servers:

$ sbx mcp ls

Inspect a registered server:

$ sbx mcp inspect notion

Remove a registered server:

$ sbx mcp rm notion

For OAuth-backed servers, sbx mcp rm removes the OAuth access token before it removes the server registration. A client secret for a pre-registered OAuth client and its identity binding remain in the host credential store so you can reuse them when you re-add the same client. The command prints the sbx secret rm commands for removing them. To remove only the OAuth access token, use sbx mcp auth rm.

Governance

Organizations with AI Governance can use MCP access policies to control MCP server registration, tool calls, gateway meta-tools, resources, prompts, and approval requirements. MCP access policies are organization policies written in Cedar.