The MCP Gateway for Agents

Table of Contents

1. The problem the gateway solves
2. Registering a remote MCP server
3. Registering a local (stdio) server
4. Static mode vs. dynamic mode
5. Managing servers on a running sandbox
6. Security notes
7. Beginner Pitfalls

1. The problem the gateway solves

An agent that can call MCP (Model Context Protocol) tools — search Notion, open a Linear ticket, hit an internal API — usually needs credentials for each of those services configured directly in the agent. Inside a sandbox, that's exactly backwards: you're isolating the agent from your host specifically so a bug or a bad instruction can't leak something, and then handing it a pile of long-lived API keys anyway.

Docker Sandboxes' answer is the MCP gateway: you register an MCP server once, on the host, and the gateway — running inside each sandbox — exposes it to the agent as a single local MCP endpoint. The real credentials stay in the host's credential store. The agent gets tool access; it never gets the keys.

2. Registering a remote MCP server

For a hosted MCP server reachable over HTTP:

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

If the server needs OAuth, sbx opens a browser-based authorization flow right then, on the host. For a server that authenticates with an API key in a header instead:

sbx mcp add acme --url https://mcp.acme.com/mcp \
  --header 'Authorization: Bearer ${api-key}'
sbx secret set mcp:acme:api-key

${api-key} is a placeholder — the gateway substitutes the real value from the secret you just set, only when it actually makes the request.

For an OAuth server that isn't set up for Dynamic Client Registration, pass a pre-registered client ID and store the client secret separately:

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

You can also scope down what an agent is allowed to do with a server:

sbx mcp add serverx --url https://mcp.serverx.example/mcp \
  --scope read --scope write
sbx mcp auth serverx --scope read   # re-authorize with a narrower scope

3. Registering a local (stdio) server

Some MCP servers run as a local process rather than a hosted endpoint — from the registry, or from an arbitrary command:

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

sbx mcp add playwright --command npx --args @playwright/mcp@latest
sbx mcp add local-image --command docker --args "run,-i,--rm,your/image"

These run on your host, outside sandbox isolation entirely — worth remembering, since it's easy to assume everything registered with sbx mcp inherits sandbox-style isolation. It doesn't; only the agent side of the connection is sandboxed.

4. Static mode vs. dynamic mode

When you start a sandbox, you choose how much of the MCP catalog the agent can see:

# Static: only these two servers, nothing else discoverable
sbx run claude --name my-session --static-mcp notion,linear

# Dynamic (the default — just omit --static-mcp): the agent can search
# the catalog and attach servers itself at runtime
sbx run claude --name my-session

Static mode is the tighter, more predictable option — good for CI or a shared team sandbox where you want an exact, reviewable list of what an agent can reach. Dynamic mode gives the agent extra gateway tools — mcp-find, mcp-add, mcp-config-set — so it can discover and attach servers mid-session on its own, which is more convenient for solo, exploratory use.

5. Managing servers on a running sandbox

Attach a server to a sandbox that's already running, without restarting it:

sbx mcp load linear --sandbox my-session

The connected agent gets a tool-list update automatically — no reconnect needed. Day-to-day inspection and cleanup:

sbx mcp ls                    # what's registered
sbx mcp inspect notion        # details on one registration
sbx mcp auth status notion    # OAuth token status
sbx mcp rm notion             # remove a server and its credentials

6. Security notes

• Local stdio servers run on the host, not inside the sandbox — treat registering one the same way you'd treat installing any other tool directly on your machine.
• --skip-ssrf-check exists for registering internal-network servers the gateway would otherwise refuse to reach; only use it for servers you actually trust and control.
• If your organization has governance enabled, MCP access itself can be policy-controlled — which servers can be registered, which tools can be invoked, and whether some calls need explicit approval. Built-in gateway tools and registered-server tools are governed separately under that model, so a policy can, say, allow mcp-find while still gating any actual tool call behind approval.

7. Beginner Pitfalls

• Registering a server with sbx mcp add doesn't automatically expose it to every sandbox — a sandbox started with --static-mcp only sees the servers named in that flag, even if others exist in the catalog.
• A local (--command/--local) server runs on your host the moment the gateway invokes it, not inside the isolation boundary this whole course has been about — don't assume it inherits sandbox protection just because you registered it through sbx mcp.
• Removing a server with sbx mcp rm also removes its stored credentials. If you just want to stop an agent from seeing it for one session, adjust --static-mcp on that run instead of removing the registration outright.