sbx: local mcp gateway and mcp governance#25559
Open
dvdksn wants to merge 33 commits into
Open
Conversation
✅ Deploy Preview for docsdocker ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
github-actions
Bot
added
area/subscription
docker-agent
left a comment
docker-agent
left a comment
Contributor
There was a problem hiding this comment.
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.mdcarries both/ai/sandboxes/security/governance/and/ai/sandboxes/governance/org/). - Front matter: All new files have complete
title,description, andkeywordsfields. - 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.
dvdksn
changed the title
dvdksn
force-pushed
the
codex/mcp-governance-policies-stub
branch
from
00c9d5f to
5146542
Compare
dvdksn
changed the title
docker-agent
left a comment
docker-agent
left a comment
Contributor
There was a problem hiding this comment.
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
left a comment
docker-agent
left a comment
Contributor
There was a problem hiding this comment.
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.
MCP policy support needed public-facing governance documentation before broader rollout. Add a focused governance stub covering Cedar-based MCP policy concepts, approval gates, organization policy context, and audit-log coverage.
The governance section mixed policy scope, access surfaces, monitoring, enforcement, and reference pages at one level. Group governance docs into access controls, monitor and enforce, and reference; add network, filesystem, and MCP access pages; preserve old URLs with aliases and update inbound links.
The organization policy page repeated policy evaluation and access-rule details covered by the concepts and access-control pages. Trim it to admin-console management, policy type selection, team scoping, and propagation troubleshooting, and move filesystem mount troubleshooting to the filesystem access page.
MCP governance policy docs needed a Docker-specific reference for the Cedar namespace surface without teaching the full Cedar language. Add an MCP policy reference page and link it from the governance reference, concepts, and MCP access-control pages.
The MCP policy reference included stale behavior from the original runbook for context args, resource reads, prompt access, and tool category/default semantics. Update the reference against docker/mcp-gateway-enterprise source to document current Cedar actions, attributes, context fields, and gateway limitations.
The sandbox governance docs needed a final prose and sidebar-ordering pass after adding MCP policy coverage. Normalize governance subtree weights to 10-point increments, add missing reference links and API keywords, and smooth wording in the new governance pages.
Document the local MCP gateway workflow for Docker Sandboxes, including server registration, OAuth handling, static and dynamic sandbox modes, live loading, bundles, and governance cross-links. Reorder the top-level Sandboxes section weights so the new MCP gateway page has a stable place in the sidebar.
Improve the MCP gateway usage page with progressive disclosure: explain the gateway model first, add a quick start, move registration details after the first run, and remove gateway-mode diagnostics from the public local-mode flow. Add an upfront note that the Docker Sandboxes MCP gateway is separate from the Docker Desktop MCP Toolkit.
Segment the sbx mcp registration paths into remote endpoint, MCP registry, server manifest, Docker Hardened Image, local container, and local stdio options. Clarify that registration before sandbox start seeds the initial MCP catalog, while already-running sandboxes need sbx mcp load.
The previous wording exposed hosted gateway internals while explaining --local. This clarifies that --local runs registry or manifest entries as host-side stdio servers and rejects non-stdio packages.
The MCP gateway page described flags without separating endpoint URLs from metadata URLs. This adds the registration input model and clarifies that local stdio servers run on the host, not inside the sandbox.
The MCP gateway page did not state that metadata-based local registration only supports OCI stdio packages. This clarifies the OCI and host Docker requirements for --local --url registrations.
The Sandboxes security and architecture pages did not explain where MCP gateway traffic and local MCP servers sit relative to the VM boundary. This adds the gateway placement, host-side local server caveat, and MCP policy enforcement point.
MCP policy docs described default deny once Cedar evaluates a request, but did not distinguish that from the ungoverned gateway posture. This adds the pass-through versus fail-closed distinction to the access guide and reference page.
The MCP gateway page described dynamic discovery for local gateway usage, which made the local model sound broader than the supported behavior. Update the page to center explicit server exposure and add a local built-in gateway tools section, then align the MCP policy reference examples.
The built-in gateway tools section listed tool names without explaining why users or admins might see them. Add context that agents can see these gateway-owned tools and that admins govern them separately from registered server tools.
PR docker#25563 removed stale Admin Console navigation language from the sandbox docs, but this branch reintroduced it through the governance IA move. Update the reorganized sandbox governance pages to use Docker Home and AI Platform wording, and split the policy creation navigation steps so they describe distinct actions.
Admins need a concrete pattern for blocking remote MCP server registration by identity URL, plus the caveat that registration policy does not revoke existing registrations. Add the deny-list example to the MCP access policy page and record the existing-registration limitation in the MCP policy reference.
The organization policy troubleshooting section only compared network and filesystem timing even though the PR adds MCP governance. Broaden the section to cover MCP registration-time and use-time enforcement, while preserving the old heading anchor.
The previous network-versus-filesystem anchor no longer matches the broadened organization policy timing section. Remove the explicit heading ID so the page uses the new enforcement-timing heading anchor.
The MCP access guide was organized around Cedar primitives, which obscured the separate registration-time and use-time controls administrators need to combine.\n\nReframe the guide around the server lifecycle and representative admin outcomes, trim duplicate concepts content, and align related timing and reference guidance. Co-Authored-By: Codex <noreply@openai.com>
The MCP policy guide described approval as user confirmation without explaining who receives the request or how the gateway resolves it.\n\nDocument the in-protocol elicitation flow, trust boundary, client requirements, and digest-bound re-evaluation with a Mermaid diagram and aligned reference guidance. Co-Authored-By: Codex <noreply@openai.com>
The approval section opened with narration about a possible misconception instead of stating the behavior directly.\n\nLead with the per-request MCP confirmation behavior and connect the example directly to that explanation. Co-Authored-By: Codex <noreply@openai.com>
dvdksn
force-pushed
the
codex/mcp-governance-policies-stub
branch
from
e9c5077 to
61bb4f9
Compare
The upstream workflow reorganization introduced a source link to the removed governance/org.md page, causing Hugo reference validation to fail.\n\nPoint the workflow at the organization policy page, align its terminology, and resolve the outstanding MCP registration-list style finding. Co-Authored-By: Codex <noreply@openai.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Add Docker Sandboxes MCP docs for the local gateway path, including
sbx mcpusage, 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-findandmcp-add, remote dataplane behavior, and setup for non-local gateways. Reserving this for a follow-up PR.Preview links: