| 说明 | 注册一个 MCP 服务器 |
| 用法 | sbx mcp add NAME (--url URL | --command COMMAND) [flags] |
描述
注册一个 MCP 服务器，供 sbx create/run --static-mcp 使用。 要把已注册的服务挂载到正在运行的沙箱，请使用 sbx mcp load。
--url 用于远程 MCP 端点、MCP 社区注册表或服务器清单 URL， 也可以是 Docker Hardened Image 引用。其他镜像引用不受支持。 --command 用于本地 stdio 服务器。本地服务器以你的完整权限在宿主机上运行； 请只使用可信的可执行文件。
远程端点的 OAuth 元数据会被自动发现。对于预注册的客户端，请使用 --client-id； 当服务器不发布任何发现元数据时，请使用 --oauth-authorization-server。 机密客户端需要一个存储为 mcp:NAME:client_secret 的密钥； 不带 -t 运行 sbx secret set 可从 stdin 读取它。
--header 用于给远程端点添加自定义标头。标头值可以引用已存储的密钥； 详见下面的示例。标头密钥来自本机的密钥存储，需要本地已连接的服务器。
有关注册和授权流程，请参阅： https://docs.docker.com/ai/sandboxes/mcp-gateway/
选项
| 选项 | 默认值 | 说明 |
|---|---|---|
--args | 该命令的命令行参数 | |
--callback-port | 0 | 注册时授权期间，OAuth 回调监听器要绑定的本地端口（默认：由操作系统分配的临时端口）。当该端口必须预先注册到某个 OAuth 应用的允许重定向 URI 中时很有用。适用于 --url 指定的远程 OAuth 服务器；如果最终该服务器并不需要 OAuth，则会给出警告并忽略该选项。 |
--client-id | 预注册客户端的 OAuth 客户端 ID（配合 --url 使用；可与 --oauth-authorization-server 一起使用，也可不用）。机密客户端的密钥来自 sbx secret set mcp:<server>:client_secret | |
--command | 本地 stdio 服务器要运行的可执行文件 | |
--dir | --command 宿主机服务器的工作目录（cwd） | |
--disable-http2 | 不为该远程服务器协商 HTTP/2，保持使用 HTTP/1.1。适用于 --url 指定的服务器。 | |
--header | 要发送到远程 --url 端点的自定义 HTTP 标头，采用 curl 形式 Name: value（可重复）。值中的 ${placeholder} 会在连接时由 sbx secret set mcp:<server>:<placeholder> 存储的密钥替换 | |
--local | 通过 docker run 在本地运行注册表中的 OCI 服务器 | |
--no-scope | 在注册时授权中不请求任何 scope，由授权服务器应用它自己的默认授权。抑制必需的 scope 和 OIDC 回退 scope；不能与 --scope 一起使用。适用于 --url 指定的远程 OAuth 服务器。 | |
--oauth-authorization-server | 指向 RFC 8414 oauth-authorization-server 元数据 JSON 文档的路径或 http(s) URL | |
--resource | OAuth 期间要发送的 RFC 8707 resource 指示符：一个绝对 URI（包含 scheme 和 host，不含 fragment），指明该令牌对应的服务器。它会覆盖服务器在其 RFC 9728 元数据中发布的值，以及从 --url 推导出的值；仅当推导出的值有误时才设置它。托管 gateway 目前尚不对普通远程服务器遵循该值。适用于 --url 指定的远程 OAuth 服务器。 | |
--scope | 征得同意时请求的默认 OAuth scope（可重复；如果服务器公布的元数据不识别某个 scope，会打印警告但仍然请求，因为公布某个 scope 也从未承诺服务器会授予它）。不指定 --scope 时，请求资源自身要求的 scope 集合；两者都没有时，请求 openid、email、profile 和 offline_access 中被公布的那些；其他公布的 scope 不包含在这个回退中。适用于 --url 指定的远程 OAuth 服务器。 | |
--skip-auth | 注册 OAuth 服务器，但不启动托管的 OAuth 流程 | |
--skip-ssrf-check | 在本次注册中跳过 SSRF 检查，包括 OAuth 授权服务器元数据和重定向（由操作者断言该提供商可信） | |
--url | MCP 服务器清单 URL、远程端点 URL 或 dhi.io 镜像引用 |
全局选项
| 选项 | 默认值 | 说明 |
|---|---|---|
--cloud | 改为调用 Docker Cloud Sandboxes API，而不是本地 sandboxd（支持的动词正在逐步增加，运行 sbx --cloud --help 查看当前列表） | |
-D, --debug | 启用调试日志 | |
--no-input | 从不提示；需要应答的命令会直接失败，并给出应当运行的命令 |
示例
console
# 远程 MCP 端点（自动检测 OAuth）
sbx mcp add notion --url https://mcp.notion.com/mcp
sbx mcp add linear --url https://mcp.linear.app/mcp
# MCP 社区注册表 URL
sbx mcp add fetch --url https://registry.modelcontextprotocol.io/v0/servers/fetch-mcp/versions/latest
# 普通服务器清单 URL（server.json / server.yaml）
sbx mcp add opine --url https://example.com/mcp/opine/server.yaml
# Docker Hardened Image（清单从镜像证明中提取）
sbx mcp add fetch --url dhi.io/fetch-mcp:latest
# 注册表 URL，本地模式（通过 docker run 在宿主机上运行；仅支持 stdio 包）
sbx mcp add fetch --local --url https://registry.modelcontextprotocol.io/v0/servers/fetch-mcp/versions/latest
# 私有网络端点（主机名解析到私有地址）— 跳过 SSRF 防护
sbx mcp add internal --url https://private.example.com/mcp --skip-ssrf-check
# 手动提供 OAuth 覆盖值的远程端点（服务器不发布
# well-known OAuth 元数据）：--oauth-authorization-server 是指向
# RFC 8414 元数据文档的路径或 http(s) URL，--client-id 是 OAuth 客户端 ID
sbx mcp add acme --url https://mcp.acme.com/mcp --oauth-authorization-server ./acme-as.json --client-id my-client
# 在可发现但没有注册端点的服务器上使用预注册客户端 —
# 不需要 --oauth-authorization-server（元数据会被发现）
sbx mcp add slack --url https://slack.example.com/mcp --client-id my-preregistered-client
# 机密客户端 — 先存储密钥（由提示输入，绝不进入 argv 或
# shell 历史），然后再注册；密钥从密钥存储中读取
sbx secret set mcp:slack:client_secret
sbx mcp add slack --url https://slack.example.com/mcp --client-id my-preregistered-client
# 记录征得同意时请求的默认 OAuth scope（服务器授权元数据
# 未公布的 scope 会给出警告，但仍会被请求；每个 scope 重复
# 一次 --scope）
sbx mcp add acme --url https://mcp.acme.com/mcp --scope read --scope write
# URN 形式和 URL 形式的 scope 值都是普通 scope，无需加引号
sbx mcp add fastmail --url https://api.fastmail.com/mcp --scope https://www.fastmail.com/dev/mcp --scope offline_access
# 当推导出的 RFC 8707 'resource' 指示符有误时进行更正
# （服务器公布的标识符不是它的端点 URL）
sbx mcp add acme --url https://mcp.acme.com/mcp --resource https://api.acme.com/mcp
# 带自定义标头的远程端点（curl 写法；可重复）。沙箱连接时
# 会从密钥存储中读取 ${api-key} 的值
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
# 本地 stdio 命令（在宿主机上运行 — 仅供开发使用）
sbx mcp add github --command npx --args @modelcontextprotocol/server-github
sbx mcp add postgres --command docker --args "run,-i,--rm,mcp/postgres"
# 本地 stdio 命令，为宿主进程指定工作目录（cwd）
sbx mcp add local-fs --command node --args server.js --dir /srv/data参见
sbx mcp— 管理 MCP 服务器