sbx: local mcp gateway and mcp governance

[dvdksn]

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
• MCP policies concept
• MCP access policies
• MCP policy reference

[netlify]

✅ Deploy Preview for docsdocker ready!

Name	Link
🔨 Latest commit	7718c60
🔍 Latest deploy log	https://app.netlify.com/projects/docsdocker/deploys/6a7205949c20f60008a62d2f
😎 Deploy Preview	https://deploy-preview-25559--docsdocker.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[docker-agent]

Assessment: 🟢 APPROVE

This PR reorganizes the Docker Sandboxes governance documentation IA and adds new MCP policy governance pages. The changes are well-executed:

• Redirects/aliases: All moved pages carry appropriate aliases: entries for their old URLs (local.md → /ai/sandboxes/governance/local/, audit.md → /ai/sandboxes/governance/audit/, monitoring.md → /ai/sandboxes/governance/monitoring/, sign-in-enforcement.md → /ai/sandboxes/governance/sign-in-enforcement/, organization.md carries both /ai/sandboxes/security/governance/ and /ai/sandboxes/governance/org/).
• Front matter: All new files have complete title, description, and keywords fields.
• Style: No hedge words, AI-isms, or style violations found in the new content.
• Cross-references: Relative links updated correctly throughout to reflect the new subdirectory structure.
• Vendored content: No vendored files were edited.

No issues found. The reorganization is clean and the new MCP governance content follows established patterns.

[docker-agent]

Assessment: 🟢 APPROVE

32 files reviewed. The PR adds substantial new documentation for the Docker Sandboxes MCP gateway and reorganizes governance pages into a cleaner IA. One minor style issue found.

Redirect coverage: All moved files correctly include aliases: entries. Verified for local.md, audit.md, monitoring.md, sign-in-enforcement.md, and the new organization.md (which aliases both the old /ai/sandboxes/security/governance/ and /ai/sandboxes/governance/org/ paths). The governance/api.md → governance/reference/api.md rename uses build: render: never so no rendered page exists at the old URL — no redirect needed.

No AI-isms found: No hedge words (simply, easily, just, seamlessly), no meta-commentary, no marketing language in the new content.

Content quality: The MCP gateway, concepts, and policy reference pages are well-structured and technically clear.

[docker-agent]

Assessment: 🟡 NEEDS ATTENTION

Two medium-severity findings in the new documentation. No vendored files were touched. All moved/renamed pages include proper aliases: entries for redirect coverage. New content follows style guide conventions well — no hedge words, no marketing language, correct use of select throughout.

[docker-agent]

Assessment: 🟢 APPROVE

This PR adds documentation for Docker Sandboxes MCP gateway and MCP access governance. The new pages are well-structured, use active voice, avoid AI-isms, and match existing documentation style. Front matter is complete on all new files. No missing redirects needed (these are new pages, not moved ones). No markdown formatting issues found.

One low-priority style observation is noted below but does not affect user understanding.

[saucow]

@dvdksn reviewed the policy related docs, overall looks really good. Agent also returned some suggesting providing the aggregated feedback here:

1.1 Actions table: "Remote server registration needs an explicit permit"

• Where: reference/mcp-policy.md, Actions table, register row.
• Issue: the "Remote" qualifier implies local registrations are treated differently. They are not: registration is uniformly default-deny for local-stdio, container-stdio, and remote servers. ValidateRegistration has no branch on server type (sandboxes sandboxlib/mcp/policy_registration.go:66-101), and TestValidateRegistration_NoRegisterRuleDenies (policy_registration_test.go:136-153) proves both a local npx spec and a remote spec are implicitly denied without a register permit. The access-controls page already states this unqualified, so the reference row is also internally inconsistent with the rest of the PR.
• Suggested: "Server registration needs an explicit permit."

1.2 resource.category never matches at the local gateway

• Where: reference/mcp-policy.md, Resource attributes table and Limitations.
• Issue: the copy-from-catalog mechanism exists only at the remote gateway (mcp-gateway-enterprise pkg/service/dataplane/auth_middleware.go:375-386). The local entity builder never populates category (sandboxes sandboxlib/mcp/entity_builder.go:50-65, called via policy_interceptor.go:85), so for locally governed tools it is always the empty string. A category-keyed permit fails closed (everything denied); a category-keyed forbid fails open (nothing blocked). In a local-scoped reference this invites rules that silently never fire.
• Suggested: remove the attribute from this page, or state plainly that it is not populated for the local gateway and rules keyed on it will not match locally.

1.3 resource.type vocabulary is incomplete and partly wrong

• Where: reference/mcp-policy.md attribute table; access-controls/mcp.md "Restrict host-run servers".
• Issues:
  1. local-stdio is not only "explicit host commands". Metadata-resolved --local OCI servers also classify as local-stdio (mcpruntime resolve.go:604-613 assigns Type local; sandboxes entity_builder.go:77-95 maps local to local-stdio). container-stdio is the manifest-OCI shape provisioned via the enterprise gateway, not the general OCI-stdio case.
  2. Remote servers bind remote-dcr / remote-no-dcr (sandboxes entity_builder.go:84-93). The doc omits these, so a reader who writes resource.type == "remote" gets a rule that never matches anything.
• Suggested: describe local-stdio as host-run stdio servers (explicit commands and --local metadata-resolved OCI images run on the host), and publish the remote values so admins do not guess. The "Restrict host-run servers" example itself still works as written.

1.4 context.oauth_scopes is not bound at the local gateway

• Where: reference/mcp-policy.md, Context fields table.
• Issue: it is bound only at the remote gateway (mcp-gateway-enterprise pkg/plugins/providers/governor/entities.go:336). The local request builder sets only args and request_time, and its own comment lists oauth_scopes as a remote-only input (sandboxes entity_builder.go:305-327). Locally, a rule referencing it never matches: a permit fails closed, a forbid fails open.
• Suggested: scope the row to remotely enforced requests, or drop it from this local-scoped page.

1.5 context.request_time is not bound at registration

• Where: reference/mcp-policy.md, Context fields ("Bound at each enforcement point").
• Issue: the registration check made for sbx mcp add sends no context at all (sandboxes policy_registration.go:83), so a time-window condition on a register permit never matches and the registration falls to default deny. request_time is bound for invokeTool, invokePrimordial, readResource, and getPrompt.
• Suggested: qualify: bound for invocation, read, and prompt decisions; registration decisions carry no request_time, so time-window register rules fail closed.

1.6 code-mode generated tools are not session-scoped

• Where: mcp-gateway.md, Built-in gateway tools.
• Issue: a generated tool registers on the sandbox gateway's shared MCP server and lives until the gateway is replaced or stops; it is visible to any client connected to that sandbox's gateway, not only the session that created it (mcpruntime codemode.go:188-208; removal only on backend replace/close, gateway.go:788-812).
• Suggested: "scoped to the sandbox's gateway: generated tools are ephemeral, shared by connections to that gateway, and disappear when the gateway stops."

1.7 <server>-authorize exposure is broader than described

• Where: mcp-gateway.md, OAuth section and Built-in gateway tools.
• Issue: "only when an OAuth-backed server is exposed to the sandbox and needs authorization" is too narrow. The helper is registered for every qualifying OAuth-backed remote backend, including ones that connected with a valid token, and it supports re-authorization (mcpruntime gateway.go:1193-1197). Only remote URL backends qualify; local stdio OAuth servers never get one (local_authorize.go:33-42).
• Suggested: the gateway exposes <server>-authorize for OAuth-backed remote servers exposed to the sandbox (it can also be used to re-authorize); when the server is not yet authorized, the helper is the only tool that server exposes.

1.8 Smaller precision fixes

• The context.args "too deeply nested arguments are omitted" clause is remote-only. The remote gateway enforces a 64-level depth cap; the local builder has no depth cutoff (sandboxes entity_builder.go:371-420). Either drop the clause or scope it.
• resource.identityURL for explicit local commands is the resolved host command path, and for --local metadata registrations it is a local://stdio/<name> placeholder, not the registry URL (sandboxes entity_builder.go:103-112). Worth a sentence, since the withdraw pattern pivots on identityURL.
• "If you omit --static-mcp, the sandbox starts with an MCP gateway but no registered MCP servers" is accurate for the local mode this page documents, but in hosted/dynamic mode the registered catalog remains discoverable and loadable via gateway discovery tools. Consider scoping the sentence to the local gateway mode explicitly.

[dvdksn]

Addressed the aggregated policy review in 03153a3 and 51ac95f after verifying the findings against the sandboxes and mcpruntime source.

• Registration is documented as uniformly requiring a permit.
• Local-unavailable category and OAuth-scope fields were removed.
• Server type and identity URL values now distinguish explicit commands, --local metadata, and remote endpoints; hosted-only values are deferred.
• Request time and tool arguments now state exactly where the local gateway binds them.
• The host-run restriction uses local-stdio, which covers commands and --local OCI registrations.
• code-mode generated tools are documented at gateway scope.
• OAuth authorization helpers now cover authorization and reauthorization for remote OAuth servers.
• The local-mode behavior without --static-mcp is explicitly scoped.

Generated by Codex

[saucow]

@dvdksn thanks for the thorough fixes. We re-verified the updated text against the sandboxes, mcpruntime, and gateway sources: all eight items from the previous review are correctly addressed, and we also confirmed the narrowed host-run forbid is safe (every host-run registration path resolves to local-stdio; a container-stdio registration can never be attached or launched by the local gateway).

Two new findings introduced by the updated text, both one-sentence fixes:

2.1 context.args: "Remote server requests don't include it" is no longer true

• Where: reference/mcp-policy.md, Context fields table, context.args row.
• Issue: the gateway that governs remote-server requests binds context.args for invokeTool, and has since before this text was written: mcp-gateway-enterprise commit 2250c5959 ("Forward tool args to governor invoke policy (split out redirect note to system requirements for both mac and windows #1970)", 2026-07-01) routes req.Context.Arguments into the Cedar request context (pkg/plugins/providers/governor/entities.go:109, args bound at entities.go:329-342, fed end-to-end from pkg/service/dataplane/tool_invoke_policy.go:160). Since the same organization policy is evaluated there, args-conditioned rules do take effect on remote-server tool calls. The sentence is also drifting at the local seam: as of sandboxes 9b672e9d6 (2026-07-25), local data-plane mode Cedar-evaluates all tracked backends locally, remote servers included, with args bound; and args are also bound for invokePrimordial (built-in gateway tools), which the row omits (sandboxlib/mcp/policy_interceptor.go:124).
• Suggested: scope the row to where evaluation happens rather than a server type, e.g.: "Tool-call arguments for invokeTool and built-in gateway tool calls evaluated by the gateway. Present when arguments are available as a JSON object." and drop the remote-server sentence.

2.2 "Server type values" list is missing a reachable value

• Where: reference/mcp-policy.md, "Server type values" section.
• Issue: the three values are described as the set local gateway registrations use, but a fourth is reachable: sbx mcp add <name> --url <registry or manifest URL> without --local resolves to a spec that the register gate evaluates as resource.type == "container-stdio" (mcpruntime resolve.go:626; sandboxes sandboxlib/mcp/entity_builder.go:81-82, evaluated via policy_registration.go:79). Under the page's blocklist example such a registration is permitted and persisted. It is inert on the local gateway (it can never be attached or run locally), so the host-run forbid example is unaffected, but policy authors keying rules on resource.type should know the value can appear in register decisions.
• Suggested: add one sentence or bullet: registering an OCI/registry server without --local is evaluated as type container-stdio; it cannot be attached or run by the local gateway.

---

Reviewed with Claude Code

[dvdksn]

@saucow Addressed both follow-up findings in 1846a26 after verifying the cited Sandboxes and mcpruntime revisions.

• context.args now covers invokeTool and invokePrimordial requests evaluated by the gateway and no longer makes an incorrect distinction based on server type.
• I added container-stdio only as a registration-decision value in the local gateway reference. A manifest URL without --local resolves to internal type server, which the local registration entity maps to container-stdio. A permit can therefore allow and persist that registration. The local classifier still defers this type to the control plane, so it cannot attach or run when the local gateway is the data plane. This documents the local policy seam without expanding the page into remote gateway behavior.

The host-run forbid remains unchanged because host execution still maps to local-stdio.

I also rebased the branch onto main and resolved the governance IA conflicts while retaining the expanded audit-log section added upstream.

Generated by Codex

[cmrigney]

Looks good!