本页描述的是本地 MCP gateway。云端沙箱使用在 Docker Agentic Platform 中配置的 MCP 服务器：参见加载 MCP 服务器。

Docker Sandboxes 内置一个 MCP gateway，用于把智能体连接到 Model Context Protocol 服务器。该 gateway 为沙箱内的智能体提供一个 MCP 端点，而 sbx 负责在宿主机上 管理已注册的服务器、OAuth 凭据和沙箱生命周期。

这与在 Claude Code 等智能体中直接配置 MCP 服务器不同。直接配置 MCP 是为该智能体 自己的 MCP 客户端做配置。使用 Docker Sandboxes 时，你在宿主机上注册一次 MCP 服务器，沙箱 gateway 就会把它们暴露给隔离沙箱内受支持的智能体。这种由宿主机 统一管理的 gateway 为凭据、显式加载服务器、实时更新和组织治理提供了单一路径。

NOTE

Docker Sandboxes 的 MCP gateway 与 Docker Desktop MCP Toolkit 无关。你不需要 Docker Desktop MCP Toolkit 即可使用 sbx mcp，而且 MCP Toolkit 的服务器设置 也不会与 Docker Sandboxes 共享。

前置条件

• 使用 sbx login 登录。
• 使用会在启动时配置 MCP 的智能体集成：Claude Code、Codex、Devin、Kiro 或 OpenCode。
• 对于需要 OAuth 且不支持动态客户端注册（Dynamic Client Registration）的远程 服务器，请先向服务器提供商注册一个 OAuth 客户端。
• 对于解析为 OCI 包的 --local --url 注册项，请使用已安装并正在运行 Docker 的 宿主机。显式的 --command docker ... 注册项同样需要 Docker。

快速开始

先在宿主机上注册一个 MCP 服务器：

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

如果该服务器需要 OAuth，sbx 会在存储注册项之前打开授权流程。注册完成后，验证 服务器是否已注册：

$ sbx mcp ls

该列表会显示每个服务器的传输方式、状态、gateway 和详情。

然后启动一个沙箱并暴露已注册的服务器：

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

沙箱启动时会带上一个 MCP gateway，并预加载 notion 服务器。该注册项保留在 宿主机上，可以被其他沙箱复用。

注册 MCP 服务器

sbx mcp add 按名称注册一个 MCP 服务器。注册项会在宿主机上记录服务器定义。它 本身并不会把该服务器附加到某个沙箱上。要把已注册的服务器暴露给沙箱，请在创建 沙箱时通过 --static-mcp 传入它，或者对于已在运行的沙箱使用 sbx mcp load。

服务器名称可以包含字母、数字、点、连字符和下划线。名称 none 专用于 不使用 MCP 服务器启动沙箱。

--url 标志可以指向不同类型的输入。执行位置取决于你注册的内容：

• 远程端点 URL 标识一个正在运行的 MCP 服务器。服务器在远程运行，由沙箱 gateway 连接过去。
• 配合 --local 的元数据 URL 会返回一个注册表条目、server.json 或 server.yaml，用于描述一个以 OCI 包形式发布的 stdio 服务器。sbx 解析该 镜像并用 Docker 在宿主机上运行它。
• 显式命令会在宿主机上作为 stdio MCP 服务器运行。

本地 stdio 服务器运行在宿主机上，不在沙箱内部。沙箱内的智能体只连接到 MCP gateway。

如果某个 --url 主机名解析到私有地址、回环地址、链路本地地址或云元数据地址， sbx 仍会注册该服务器，但会就解析出的地址向你发出警告。只注册你信任的 URL。 从不受信任的 URL 获取清单可能暴露内部服务或云元数据，而 DNS 重绑定可以在检查 之后重新定向主机名。

OAuth 元数据发现遇到这些地址（包括重定向目标）时同样会发出警告并继续执行。 对于受信任的内部服务器，请传入 --skip-ssrf-check，以跳过 MCP URL 检查和 OAuth 元数据发现检查，并抑制它们的警告。只有在你信任该 MCP 主机、OAuth 提供商 以及所有元数据重定向目标时才使用该标志。

远程端点 URL

对于远程 MCP 端点，请传入服务器 URL：

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

如果对远程服务器的请求出现停滞，请参阅 MCP 服务器流停滞。

自定义请求头

使用 --header 'Name: value' 可以向远程 MCP 端点发送自定义 HTTP 头，例如用 API 密钥进行身份验证。每个标头重复一次该标志，每个标头名称只出现一次：

$ sbx mcp add acme --url https://mcp.acme.com/mcp \
  --header 'Authorization: Bearer ${api-key}' \
  --header 'Accept: application/json, text/event-stream'
$ sbx secret set mcp:acme:api-key

请把示例 URL 换成你的 MCP 端点。sbx secret set 命令会提示你输入 API 密钥， 并把它存储在宿主机凭据存储中。 ${api-key} 占位符会保留在注册项中。当沙箱连接时，gateway 会读取该密钥，并把 它的值替换进标头。请在标头值外加单引号，以便 shell 保留占位符。占位符指的是 已存储的密钥，而不是环境变量：无论你的 shell 环境如何，${api-key} 读取的都是 mcp:acme:api-key。

用 sbx secret set mcp:<server>:<placeholder> 存储每个占位符。像 Authorization 这样的凭据标头必须使用密钥占位符。显式的 Authorization 头优先于 OAuth 访问 令牌。

存储密钥之后，把该服务器暴露给沙箱：

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

自定义标头要求使用远程 HTTP 端点，不能与 --command 或 --local 一起使用。 它们还要求宿主机能够连接到该服务器。托管 gateway 会拒绝这类注册项，除非你 提供 --oauth-authorization-server，以把连接经由宿主机路由。

管理标头密钥

标头密钥在宿主机上使用全局作用域。用 sbx secret set mcp:<server>:<placeholder> 设置它们，不要加 --sandbox。标头密钥必须已存储值，且不支持 --ref 或 --command 动态来源。 要查看标头模板以及它们的密钥是否已设置，请运行 sbx mcp inspect acme。该命令 不会显示解析后的密钥值。

密钥存储中还会包含一条自动管理的 :endpoint 记录，例如 mcp:acme:api-key:endpoint。这条元数据把密钥与已注册服务器的 URL 绑定起来， 使 gateway 能在发送密钥之前检测到端点变更。你不需要自行设置这条记录。如果你 更改了服务器的端点，请遵循 CLI 的指引为该端点重新设置密钥。

要轮换标头密钥，请用相同的名称运行 sbx secret set。设置、修改或删除标头密钥 之后，请停止并重新启动沙箱，或重启 sandboxd，以把变更应用到已有的 gateway。 已有连接会保留原来的值；因缺少密钥而被跳过的服务器不会自动重试。

用 sbx mcp rm 删除注册项时会保留其标头密钥，并打印用于删除它们的命令。要 删除示例中的密钥：

$ sbx secret rm mcp:acme:api-key

本地 stdio 服务器

有些 MCP 服务器通过 stdio 通信，而不是暴露远程 HTTP 端点。当你希望 sbx 在 宿主机上启动 MCP 服务器时，请使用本地 stdio 服务器。你可以提供元数据 URL 或 显式命令。

从注册表或清单元数据

当你拥有 MCP 社区注册表的 URL，或者一个返回 server.json 或 server.yaml 文档的 URL 时，请使用 --local --url。该注册表条目或清单必须描述一个使用 stdio 传输方式的 OCI 包。sbx 不会从元数据启动非 OCI 的包类型（例如 npm）。要使用 这类服务器，请注册显式命令。

这条路径会从元数据解析镜像，并用 Docker 在宿主机上启动它，因此宿主机必须已 安装并正在运行 Docker。

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

如果该条目没有发布 OCI stdio 包，sbx 会拒绝该注册项，而不会在本地启动它。

服务器清单描述 MCP 服务器包及其启动方式。它可以托管在 GitHub raw URL、内部 HTTP 服务器或 CDN 上。

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

从显式命令

当你已经知道可执行文件和参数，或者需要自定义 Docker 标志时，请使用 --command。该命令可以是 npx 这样的包运行器，也可以是 Docker 容器命令：

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

要设置宿主进程的工作目录，请传入 --dir。该标志只能与 --command 一起使用：

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

当你已发布服务器定义且不需要定制 docker run 时，请使用注册表或清单元数据。 对于本地开发、私有服务器或自定义容器标志，请使用 --command。

WARNING

本地 stdio 服务器运行在宿主机上，位于沙箱隔离之外。如果该命令启动了 Docker 容器，该容器使用的是宿主机 Docker 隔离，而不是沙箱隔离。该进程或容器可以 访问宿主机文件、宿主机网络资源以及提供给它的凭据。请使用可信的命令和镜像， 并避免挂载宿主机路径或传入凭据，除非该服务器确实需要它们。

Docker Hardened Image

对于以 Docker Hardened Image 形式打包的 MCP 服务器，请传入它的 dhi.io 引用， 而不是注册表或清单 URL：

$ sbx mcp add fetch --url dhi.io/fetch-mcp:latest

请使用标签或摘要：dhi.io/<IMAGE>:<TAG> 或 dhi.io/<IMAGE>@sha256:<DIGEST>。 对于来自其他镜像仓库的镜像，请使用服务器清单 URL 或 显式命令。

为基于 OAuth 的服务器授权

如果已注册的远程服务器需要 OAuth，sbx mcp add 默认会启动授权流程：

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

OAuth 凭据保留在宿主机上。在本地 gateway 模式下，sbx 会把令牌存储在宿主操作 系统的凭据存储中。

如需注册一个基于 OAuth 的服务器但暂不授权，请传入 --skip-auth：

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

使用预注册的 OAuth 客户端

在本地 gateway 模式下，你可以注册不支持动态客户端注册的远程 OAuth 服务器。如果 该服务器发布了 OAuth 元数据，请传入你向服务器提供商注册的客户端 ID：

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

如果该服务器没有发布 OAuth 元数据，请传入 --oauth-authorization-server 以及 客户端 ID。该标志接受一个本地文件路径，或指向 RFC 8414 授权服务器元数据文档 的 HTTP 或 HTTPS URL。该文档必须定义 authorization_endpoint 和 token_endpoint：

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

这些标志只能与 --url 一起使用。

对于机密型（confidential）OAuth 客户端，请在注册服务器之前存储客户端密钥。系统 没有 --client-secret 标志：

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

客户端密钥保留在宿主机凭据存储中，不会写入 MCP 注册项。如果服务器要求使用 机密型客户端而没有存储任何密钥，注册会成功，但授权会被跳过。请存储该密钥， 然后运行 sbx mcp auth <server>。

更换 OAuth 客户端

如果你用不同的客户端 ID、颁发者或令牌端点重新注册同一个服务器名称，sbx 会 拒绝使用绑定到旧客户端的密钥。在确认注册项指向预期客户端和提供商之后，存储 该客户端的密钥，清除旧绑定，然后进行授权：

$ sbx secret set mcp:slack:client_secret
$ sbx secret rm mcp:slack:client_secret:identity
$ sbx mcp auth slack

仅设置密钥并不会清除旧绑定。:identity 记录是把已存储密钥与其 OAuth 客户端 绑定起来的元数据。授权则会记录与新客户端的绑定关系。

对于以旧名称 mcp:<server>.client_secret 存储的密钥，请改用 mcp:<server>:client_secret 重新设置。

设置 OAuth 作用域

使用可重复的 --scope 标志记录授权期间请求的默认作用域：

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

sbx mcp auth 命令接受 --scope，以在单次授权中覆盖已记录的默认值：

$ sbx mcp auth serverx --scope read

除非你传入 --no-scope，否则 sbx 会按以下顺序请求第一组可用的作用域：

1. 传给 sbx mcp auth --scope 的作用域
2. 由 sbx mcp add --scope 记录的默认作用域
3. 受保护资源声明它需要的作用域
4. 授权服务器通告的 openid、email、profile 和 offline_access 中的任意组合

如果这些来源都没有提供作用域集合，sbx 会省略 OAuth 的 scope 参数，让授权 服务器应用其默认授权。其他通告的作用域不会包含在回退方案中。

当 sbx 使用已记录的默认值或资源所需的作用域时，如果授权服务器通告了 offline_access，它也会一并请求。这样服务器就能签发刷新令牌，访问令牌过期 时你无需重新授权。传给 sbx mcp auth --scope 的作用域会严格按给定内容请求， 不包含 offline_access。此前在没有刷新令牌的情况下签发的凭据不会被升级； 请再次运行 sbx mcp auth 以请求新的授权。

传入 --no-scope 可以在单次授权中抑制已记录的默认值、资源所需的作用域以及 通告作用域的回退方案，同时不改变已存储的默认值：

$ sbx mcp auth serverx --no-scope

--no-scope 不能与 --scope 组合使用。你选择的作用域会与授权服务器通告的 作用域以及资源所需的作用域进行核对。如果两个来源都没有发布某个作用域，该 作用域仍会被请求，但会给出警告。授权服务器仍可能针对特定客户端拒绝某个通告 的作用域。对于请求了作用域的本地授权流程，sbx 会列出已请求、已通告和被 拒绝的作用域，并给出一条重试命令。如果服务器指明了被拒绝的作用域，该命令会 移除它们；否则会使用 --no-scope。 sbx 从不自动重试。

对于暴露给沙箱的每一个基于 OAuth 的远程服务器，gateway 会暴露一个名为 <server>-authorize 的辅助工具，例如 notion-authorize。智能体可以调用该工具 来授权或重新授权该服务器。如果该服务器尚未授权，这个辅助工具就是该服务器唯一 暴露的工具。

你可以在宿主机上管理 OAuth 凭据：

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

使用 --all 可以把 auth、auth status 或 auth rm 应用于所有已注册的 基于 OAuth 的服务器。auth status 的输出会报告授权服务器授予的作用域、由 sbx mcp add --scope 记录的默认值，以及服务器支持的作用域。它会合并重复的 作用域名称，并高亮那些未被请求或已不在支持集合中的已授予作用域。使用 --json 可获得机器可读的输出：

$ sbx mcp auth status notion --json

覆盖 OAuth 资源标识符

当你的 OAuth 提供商要求的令牌受众与 sbx 发现到的资源标识符不同时，请使用 --resource。默认情况下，sbx 使用服务器的受保护资源元数据；如果没有元数据， 则使用端点 URL。设置覆盖值之前，请先用 sbx mcp inspect <SERVER> 检查当前值：

$ sbx mcp add serverx --url https://mcp.serverx.example/mcp \
  --resource https://api.serverx.example/mcp

请使用提供商提供的资源 URI。它必须带有 scheme 和主机，且不能包含 fragment。 要修改已有注册项的值，请删除该注册项后重新添加。

该覆盖值要求在宿主机上进行 OAuth 授权。除非你同时提供 --oauth-authorization-server 或 --client-id 以把授权路由到宿主机，托管 gateway 不会使用它。不带这些标志时，sbx mcp add 会警告说托管 gateway 将不会 使用该覆盖值。

选择 MCP 模式

每个沙箱启动时都会启动一个 MCP gateway。沙箱启动时，受支持的智能体集成会读取 该 gateway URL 并把它注册给智能体。

你在创建沙箱时是否传入 --static-mcp，决定了它的 MCP 模式：

• 静态模式只加载你指定的服务器，如果你指定 none，则在没有服务器的情况下启动。 它不向智能体暴露动态发现工具。
• 动态模式不预加载任何服务器，让智能体自行查找并附加已注册的服务器。

除非你卸载某个具名静态集合中的所有服务器， 这个选择会在沙箱重启后继续保留。使用 --static-mcp none 创建的沙箱始终保持 静态模式。

使用静态模式

传入 --static-mcp 以预加载已注册的 MCP 服务器：

$ 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

你可以把 --static-mcp 作为逗号分隔的列表传入，也可以重复该标志：

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

静态集合中的每个名称都必须已经用 sbx mcp add 注册过。gateway 不会向智能体 暴露 mcp-find、mcp-add 或 mcp-config-set。

在重新接入已有沙箱时，你无法通过传入 --static-mcp 来替换初始集合。要从宿主机 附加另一个服务器，请使用 sbx mcp load。

不使用 MCP 服务器启动

向 sbx create 或 sbx run 传入 --static-mcp none，即可启动一个既没有 MCP 服务器也没有动态发现工具的本地沙箱：

$ sbx run claude --name mcp-empty --static-mcp none

none 不区分大小写，且不能与服务器名称组合使用。云端沙箱不支持该值。之后你 仍然可以用 sbx mcp load 加载已注册的服务器。 无论加载还是卸载服务器，沙箱都会保持静态模式，重启后也是如此。

使用动态模式

省略 --static-mcp 即使用动态模式。gateway 不预加载任何服务器，并向智能体暴露 mcp-find、mcp-add 和 mcp-config-set。智能体可以搜索已注册服务器目录，并在 会话期间附加服务器。

如果你在动态沙箱启动之后运行 sbx mcp add，它的 gateway 会刷新可搜索的目录。 此后智能体无需重启就能找到并附加新的注册项。sbx mcp add 命令本身不会附加 该服务器。

向运行中的沙箱添加服务器

要把一个已注册的服务器附加到运行中的沙箱，请使用 sbx mcp load。这在静态 和动态模式下都可用：

$ sbx mcp add linear --url https://mcp.linear.app/mcp
$ sbx mcp load linear --sandbox my-session

已连接的智能体会话会收到工具列表更新，因此新增的工具无需重新连接即可见。已 加载的服务器在沙箱重启后仍保持附加状态。

从运行中的沙箱移除服务器

在 Docker Sandboxes v0.48.0 及更高版本中，使用 sbx mcp unload 可以把服务器 从运行中沙箱的本地 MCP gateway 上分离。这在静态和动态模式下都可用。云端沙箱 和托管 MCP gateway 不支持卸载服务器。

$ sbx mcp unload linear --sandbox my-session

已连接的智能体会话会收到工具列表更新，因此该服务器的工具无需重启智能体即被 移除。该命令还会移除保存的附加关系，因此沙箱或守护进程重启时不会恢复该服务器。 该服务器在宿主机上的注册项和凭据仍然保留，其他已加载该服务器的沙箱也不受影响。

要重新附加该服务器：

$ sbx mcp load linear --sandbox my-session

在动态模式下，智能体也可以再次找到并附加该已注册的服务器。卸载服务器并不能 阻止智能体重新加载它。

如果你从用具名静态集合创建的沙箱中卸载了所有服务器，它在当前会话中仍保持静态 模式。重启 Docker Sandboxes 守护进程并重新连接之后，智能体可以找到并附加已注册的 服务器。使用 --static-mcp none 创建的沙箱在卸载最后一个服务器并重启之后，仍会 保持动态发现处于禁用状态。

内置 gateway 工具

本地 MCP gateway 暴露了一小组内置工具。这些工具属于 gateway 本身，而不是某个 已注册的 MCP 服务器。智能体可以在与服务器工具相同的 MCP 连接上看到并调用它们， 因此它们可能出现在智能体的工具列表、日志、策略决策、审计日志或审批提示中。

正常配置时你不需要直接调用这些工具。请用 sbx mcp 命令在宿主机上注册服务器 和管理凭据。这些工具之所以重要，是因为智能体可以在会话期间调用它们，而且 管理员可以把它们与已注册 MCP 服务器提供的工具分开治理。

工具	说明
mcp-exec	通过 gateway 按名称执行工具。
code-mode	创建一个临时 JavaScript 工具，它可以通过 MCP gateway 调用选定的工具。
mcp-find	搜索已注册服务器目录，不改变沙箱状态。仅动态模式。
mcp-add	把已注册的服务器附加到沙箱。仅动态模式。
mcp-config-set	为已附加的服务器设置按会话生效的配置覆盖值。仅动态模式。
<server>-authorize	为暴露的基于 OAuth 的远程服务器启动或重新启动 OAuth 授权。

用 mcp-add 附加的服务器在沙箱重启后仍保持附加状态。对于基于 OAuth 的远程 服务器，即使它们已有有效令牌，gateway 也会暴露 <server>-authorize。本地 stdio 服务器不会暴露这个辅助工具。如果 code-mode 创建了生成式工具，该工具由连接到 沙箱 gateway 的客户端共享，并在 gateway 被替换或停止时消失。

在 MCP 访问策略中，内置 gateway 工具是 MCP::Primordial 资源，使用 invokePrimordial 操作。已注册 MCP 服务器的工具是 MCP::Tool 资源，使用 invokeTool 操作。详情请参阅 MCP 策略参考。

管理注册项

列出已注册的服务器：

$ sbx mcp ls

检查某个已注册的服务器：

$ sbx mcp inspect notion

当多个注册项同名时，检查操作需要用 --sandbox 指定所属沙箱：

$ sbx mcp inspect filesystem --sandbox my-sandbox

对于归属于环境的注册项，检查输出会以文本、JSON 和 YAML 格式显示所属沙箱和环境。 如果只有一个注册项使用该名称，你可以不加 --sandbox 直接检查。

删除某个已注册的服务器：

$ sbx mcp rm notion

删除注册项不会把该服务器从已加载它的沙箱上分离。删除注册项之前，请对每个 沙箱使用 sbx mcp unload。

对于基于 OAuth 的服务器，sbx mcp rm 会先删除 OAuth 访问令牌，再删除服务器 注册项。预注册 OAuth 客户端的客户端密钥及其身份绑定会保留在宿主机凭据存储中， 这样你重新添加同一个客户端时就能复用它们。该命令会打印用于删除它们的 sbx secret rm 命令。如需只删除 OAuth 访问令牌，请使用 sbx mcp auth rm。

治理

启用了 AI Governance 的组织可以使用组织 MCP 访问策略 控制 MCP 服务器注册、工具调用、gateway 元工具、资源、提示词和审批要求。 MCP 访问策略是用 Cedar 编写的组织策略。