sbx: local mcp gateway and mcp governance (#25559)

## Summary

Add Docker Sandboxes MCP docs for the local gateway path, including `sbx
mcp` usage, OAuth behavior, bundles, explicit sandbox exposure, built-in
gateway tools, and MCP access-governance documentation.

Generated by Codex

## Scope note for reviewers

This PR deliberately documents the local MCP gateway path only. That is
the path that ships by default for Docker Sandboxes: servers and bundles
are registered on the host, exposed explicitly to sandboxes, and
governed through the local gateway surface.

Remote, SaaS, and self-hosted gateway behavior is intentionally out of
scope for this PR. That includes dynamic discovery tools such as
`mcp-find` and `mcp-add`, remote dataplane behavior, and setup for
non-local gateways. These will be documented in a follow-up PR.

The MCP policy reference is likewise limited to values available in the
local gateway path. Hosted-only policy surface, including the
`container-stdio` server type, `resource.category`, and
`context.oauth_scopes`, is deferred to the same follow-up.

Preview links:

- [MCP
gateway](https://deploy-preview-25559--docsdocker.netlify.app/ai/sandboxes/mcp-gateway/)
- [MCP policies
concept](https://deploy-preview-25559--docsdocker.netlify.app/ai/sandboxes/governance/concepts/#mcp-policies)
- [MCP access
policies](https://deploy-preview-25559--docsdocker.netlify.app/ai/sandboxes/governance/access-controls/mcp/)
- [MCP policy
reference](https://deploy-preview-25559--docsdocker.netlify.app/ai/sandboxes/governance/reference/mcp-policy/)

---------

Co-authored-by: Codex <noreply@openai.com>
Co-authored-by: Claude <noreply@anthropic.com>

Author: 3 people

content/manuals/admin/organization/manage/manage-licenses.md

@@ -44,5 +44,5 @@ See these docs to explore Docker Core add-ons, or products that need licenses:
 
 - [Docker plans](/manuals/subscription/plans/_index.md) to learn about different add-ons
 - [Manage seats](/manuals/admin/organization/manage/manage-seats.md) to add more seats to your Docker Core subscription
-- [AI Governance](/manuals/ai/sandboxes/governance/org.md) to set up organization policies for your organization members
+- [AI Governance plan](/manuals/subscription/plans/ai-governance.md) to learn about AI Governance license usage and billing
 - [Docker Offload](/manuals/offload/about.md) to let your developers offload building and running containers to the cloud

content/manuals/ai/sandboxes/_index.md

@@ -18,9 +18,9 @@ system.
 > [organization governance](governance/) requires a separate paid subscription.
 
 Organization admins can
-[centrally manage sandbox network and filesystem policies](governance/org.md),
-so the same rules apply uniformly across every developer's machine. Available
-on a separate paid subscription.
+[centrally manage sandbox network, filesystem, and MCP policies](governance/access-controls/organization.md),
+so the same controls apply uniformly across every developer's machine.
+Available on a separate paid subscription.
 
 ## Get started
 
@@ -75,6 +75,8 @@ the [usage guide](usage.md) for basic commands.
 - [Agents](agents/) — supported agents and per-agent configuration
 - [Integrations](integrations/) — connect editors and apps like VS Code and
   Cursor to a sandbox over SSH
+- [MCP gateway](mcp-gateway.md) — register MCP servers and connect them to
+  sandboxed agents
 - [Customize](customize/) — reusable templates and declarative kits for
   extending or tailoring sandboxes
 - [Architecture](architecture.md) — microVM isolation, workspace mounting,

content/manuals/ai/sandboxes/agents/_index.md

@@ -1,7 +1,7 @@
 ---
 title: Supported agents
 linkTitle: Agents
-weight: 30
+weight: 40
 description: AI coding agents supported by Docker Sandboxes.
 keywords: docker sandboxes, ai agents, claude code, codex, cursor, gemini
 ---

content/manuals/ai/sandboxes/architecture.md

@@ -1,6 +1,6 @@
 ---
 title: Architecture
-weight: 40
+weight: 70
 description: Technical architecture of Docker Sandboxes; workspace mounting, storage, networking, and sandbox lifecycle.
 keywords: docker sandboxes, architecture, microVM, workspace mounting, sandbox lifecycle
 ---
@@ -54,7 +54,7 @@ $ DOCKER_SANDBOXES_ENABLE_VIRTIOFS_CACHE=0 sbx run <template>
 
 All outbound traffic from the sandbox routes through an HTTP/HTTPS proxy on
 your host. Agents are configured to use the proxy automatically. The proxy
-enforces [network access policies](governance/) and handles
+enforces [network access policies](governance/access-controls/network.md) and handles
 [credential injection](security/credentials.md). See
 [Network isolation](security/isolation.md#network-isolation) for how this
 works and [Default security posture](security/defaults.md) for what is
@@ -102,6 +102,22 @@ One limitation applies:
   `HTTP_PROXY`, `HTTPS_PROXY`, or `DOCKER_SANDBOXES_PROXY` environment variables
   explicitly.
 
+## MCP gateway
+
+Supported agents connect to a single MCP gateway endpoint for the sandbox. The
+gateway runs on the host side of the sandbox boundary and brokers access to
+registered MCP servers.
+
+Registered MCP servers can be remote endpoints, or they can be local stdio
+servers launched on the host. Local stdio servers don't run inside the sandbox
+VM. If a local stdio server is packaged as an OCI image, or if you register an
+explicit `docker` command, it uses Docker on the host.
+
+When MCP policies apply, enforcement happens on the MCP gateway path, separate
+from the HTTP/HTTPS network proxy. Server registration is checked before the
+server is stored, and governed MCP requests are checked by the gateway before
+tool calls, resource reads, prompt retrieval, or gateway meta-tool execution.
+
 ## Lifecycle
 
 `sbx run` initializes a VM with a workspace for a specified agent and starts

content/manuals/ai/sandboxes/customize/_index.md

@@ -3,7 +3,7 @@ title: Customizing sandboxes
 linkTitle: Customize
 description: Build reusable sandbox images, extend agents with tools and credentials, and define custom agents using templates and kits.
 keywords: sandboxes, sbx, customize, templates, kits, mixins, custom agents
-weight: 35
+weight: 60
 aliases:
   - /ai/sandboxes/agents/custom-environments/
 params:

content/manuals/ai/sandboxes/customize/kit-examples.md

@@ -85,7 +85,7 @@ Install steps run under `sh`, not bash, so bash-only builtins such as
 (`curl … | bash`) or wrap the step in `bash -c '…'` when you need them.
 
 Downloads are subject to the sandbox's
-[deny-by-default network policy](../governance/local.md). A domain that
+[network access rules](../governance/access-controls/network.md). A domain that
 resolves from your host can still be blocked inside the sandbox — for
 example, `get.sdkman.io` returns a 403 until you allow it with
 `sbx policy allow network get.sdkman.io`. A tool may also need base

content/manuals/ai/sandboxes/faq.md

@@ -1,6 +1,6 @@
 ---
 title: FAQ
-weight: 70
+weight: 110
 description: Frequently asked questions about Docker Sandboxes.
 keywords: docker sandboxes, sbx, faq, sign in, telemetry, clipboard, image paste, pricing, commercial use, allowlist, firewall, domains, proxy
 ---
@@ -11,8 +11,9 @@ Yes to both. The `sbx` CLI is free to use, including for commercial and
 professional work, with no per-seat fee. Install it, sign in with a free
 Docker account, and run sandboxes at no cost.
 
-The only paid component is organization governance: centrally managed network
-and filesystem policies, [sign-in enforcement](governance/sign-in-enforcement.md),
+The only paid component is organization governance: centrally managed network,
+filesystem, and MCP policies,
+[sign-in enforcement](governance/monitor-and-enforce/sign-in-enforcement.md),
 and [audit logs](governance/audit/). These
 [organization governance features](governance/) require a separate paid
 subscription —
@@ -29,9 +30,8 @@ Signing in gives each sandbox a verified identity, which lets Docker:
   containers, install packages, and push code. Your Docker identity is the
   anchor.
 - **Enable team features.** Team-scale features like
-  [organization governance](governance/org.md), shared environments, and
-  audit logs need a concept of "who," and adding that later would be worse for
-  everyone.
+  [organization governance](governance/), shared environments, and audit logs
+  need a concept of "who," and adding that later would be worse for everyone.
 - **Authenticate against Docker infrastructure.** Sandboxes pull images, run
   daemons, and talk to Docker services. A Docker account authenticates those
   requests.
@@ -40,13 +40,13 @@ Your Docker account email is only used for authentication, not marketing.
 
 ## Can I enforce sandbox policies across my organization?
 
-Yes. Admins can centrally manage network and filesystem policies. These
-rules apply to every sandbox in the
-organization. When organization governance is active, it replaces local rules
-set with `sbx policy` — local rules are no longer evaluated.
+Yes. Admins can centrally manage network, filesystem, and MCP policies. These
+controls apply to every sandbox in the organization. When organization
+governance is active, it replaces local rules set with `sbx policy` — local
+rules are no longer evaluated.
 
-See [Organization governance](governance/org.md). This feature requires
-a separate paid subscription —
+See [Organization policies](governance/access-controls/organization.md). This
+feature requires a separate paid subscription —
 [contact Docker Sales](https://www.docker.com/products/ai-governance/#contact-sales)
 to get started.
 
@@ -132,7 +132,7 @@ $ echo $BRAVE_API_KEY
 ## Why do agents run without approval prompts?
 
 The sandbox itself is the safety boundary. Because agents run inside an
-isolated microVM with [network policies](governance/),
+isolated microVM with [network policies](governance/access-controls/network.md),
 [credential isolation](security/credentials.md), and no access to your host
 system outside explicitly shared paths, the usual reasons for approval prompts
 (preventing destructive commands, network access, file modifications) are

content/manuals/ai/sandboxes/get-started.md

@@ -160,8 +160,8 @@ Initialize the global network policy for your sandboxes:
 
 **Balanced** is a good starting point — it permits traffic to common
 development services while blocking everything else. You can adjust individual
-rules later. See [Policies](governance/local.md) for a full description of each
-option.
+rules later. See [Local policy](governance/access-controls/local.md) for a full
+description of each option.
 
 Replace `claude` with the agent you want to use — see [Agents](agents/) for the
 full list.
@@ -224,11 +224,11 @@ To allow a specific host:
 $ sbx policy allow network registry.npmjs.org
 ```
 
-With **Balanced**, common development services are allowed by default. With
-**Locked Down**, everything is blocked until you allow it — including your
-model provider's API. If the agent can't reach a service it needs, the network
-policy is the first place to look. See [Policies](governance/local.md) for the
-full rule set and how to customize it.
+With **Locked Down**, even your model provider API is blocked unless you
+explicitly allow it. With **Balanced**, common development services are
+permitted by default. See
+[local policy](governance/access-controls/local.md) for the full rule set
+and how to customize it.
 
 ## Clean up
 
@@ -272,5 +272,5 @@ Then explore:
   network rules into a reusable definition you launch with a single flag.
 - [Agents](agents/) — the full list of supported agents and how to configure
   each one.
-- [Governance](governance/) — centrally manage network and filesystem policies
-  across a team.
+- [Governance](governance/) — centrally manage network, filesystem, and MCP
+  policies across a team.

content/manuals/ai/sandboxes/governance/_index.md

@@ -1,30 +1,33 @@
 ---
 title: Governance
-weight: 55
+weight: 90
 description: Control what sandboxes can access, from local developer rules to org-wide enforcement.
-keywords: docker sandboxes, governance, policy, network access, filesystem access, organization policy
+keywords: docker sandboxes, governance, policy, network access, filesystem access, mcp policy, organization policy
 ---
 
 Sandbox governance covers the policy system that controls what sandboxes can
-access over the network and on the filesystem. It operates at two layers, and
-only one applies at a time:
+access over the network, on the filesystem, and through MCP. For MCP setup and
+server registration, see [MCP gateway](../mcp-gateway.md). Governance operates
+at two layers, and only one applies at a time:
 
-**Local policy** is configured per machine using the `sbx policy` CLI. It lets
-individual developers customize which domains their sandboxes can reach. See
-[Local policy](local.md).
+**Local policy** is configured per machine using the `sbx policy` CLI. It
+lets individual developers customize which domains their sandboxes can reach.
+See [Local policy](access-controls/local.md).
 
-**Organization policy** is configured centrally in the Docker Admin Console or
-via the [Governance API](/reference/api/ai-governance/). Rules defined at the
-org level apply uniformly across every sandbox in the organization. When
+**Organization policy** is configured centrally in Docker Home. Network and
+filesystem policies can also be managed via the
+[Governance API](/reference/api/ai-governance/). Controls defined at the org
+level apply uniformly across every sandbox in the organization. Organization
+governance can also include MCP policies for sandbox MCP activity. When
 organization governance is active, it replaces local policy entirely: local
 `sbx policy` rules are no longer evaluated. See
-[Organization policy](org.md).
+[Organization policies](access-controls/organization.md).
 
 Alongside this access-control policy, admins can require developers to sign in
 as members of their organization before using sandboxes at all.
-[Sign-in enforcement](sign-in-enforcement.md) is deployed through endpoint
-management and ensures developers can't bypass organization policy by using a
-personal account.
+[Sign-in enforcement](monitor-and-enforce/sign-in-enforcement.md) is deployed
+through endpoint management and ensures developers can't bypass organization
+policy by using a personal account.
 
 > [!NOTE]
 > Organization governance is available on a separate paid subscription.
@@ -33,17 +36,36 @@ personal account.
 
 ## Learn more
 
-- [Policy concepts](concepts.md): resource model, rule syntax, evaluation, and
-  precedence
-- [Local policy](local.md): configure network and filesystem rules on your
-  machine with the `sbx policy` CLI
-- [Organization policy](org.md): centrally manage sandbox policies across your
-  organization from the Admin Console
-- [Sign-in enforcement](sign-in-enforcement.md): require developers to sign in
-  as organization members, enforced through endpoint management
-- [Monitoring](monitoring.md): inspect active rules and monitor sandbox network
-  traffic with `sbx policy ls` and `sbx policy log`
+Start with [Policy concepts](concepts.md) for the resource model, rule syntax,
+MCP policy basics, evaluation, and precedence.
+
+### Access controls
+
+- [Local policy](access-controls/local.md): configure network rules on your
+  machine with the `sbx policy` CLI.
+- [Organization policies](access-controls/organization.md): centrally manage
+  sandbox policies across your organization.
+- [Network access policies](access-controls/network.md): control outbound network
+  access from sandboxes.
+- [Filesystem access policies](access-controls/filesystem.md): control which
+  host paths sandboxes can mount as workspaces.
+- [MCP access policies](access-controls/mcp.md): control MCP server registration,
+  tool calls, resources, prompts, and approval gates.
+
+### Monitor and enforce
+
+- [Monitoring policies](monitor-and-enforce/monitoring.md): inspect active
+  rules and monitor sandbox network traffic with `sbx policy ls` and
+  `sbx policy log`.
 - [Audit logs](audit/): view, configure, export, and collect governance audit
-  records
-- [API reference](/reference/api/ai-governance/): manage org policies
-  programmatically via the Governance API
+  records.
+- [Sign-in enforcement](monitor-and-enforce/sign-in-enforcement.md): require
+  developers to sign in as organization members, enforced through endpoint
+  management.
+
+### Reference
+
+- [AI Governance API](/reference/api/ai-governance/): manage network and
+  filesystem org policies programmatically.
+- [MCP policy reference](reference/mcp-policy.md): look up Docker MCP policy
+  actions, resources, attributes, context fields, and approval behavior.

content/manuals/ai/sandboxes/governance/access-controls/_index.md

@@ -0,0 +1,27 @@
+---
+title: Access controls
+weight: 20
+description: Configure local and organization controls for sandbox network, filesystem, and MCP access.
+keywords: docker sandboxes, access controls, governance, network access, filesystem access, MCP access
+---
+
+Access controls are expressed as policies. Local and organization pages
+describe where policies apply. Network and filesystem pages describe the rules
+inside those policies. MCP policies use Cedar statements instead of the network
+and filesystem rule format.
+
+## Policy scope
+
+- [Local policy](local.md): configure network rules on a developer machine with
+  the `sbx policy` CLI.
+- [Organization policies](organization.md): manage centralized policies for an
+  organization or team.
+
+## Access surfaces
+
+- [Network access policies](network.md): control outbound network access from
+  sandboxes.
+- [Filesystem access policies](filesystem.md): control which host paths
+  sandboxes can mount as workspaces.
+- [MCP access policies](mcp.md): control MCP server registration, tool calls,
+  resources, prompts, and approval gates with Cedar policy.