Docker MCP Gateway

Docker MCP Gateway 是统一管理多个 MCP Server 的网关，实现一次配置、多客户端复用。

#type / concept #status / evergreen #tech / ai #resource / docker #resource / mcp

[!info] related notes

所属 MOC: docker-mcp-toolkit-moc, mcp-moc

前置概念: mcp, docker

并列概念: mcp-filesystem, mcp-tools-cheatsheet

关系笔记: mcp-gateway-architecture-evolution

Docker MCP Gateway

一句话定义

Docker MCP Gateway 是 Docker MCP Toolkit 的核心组件，作为一个常驻的网关进程，统一代理多个容器化的 MCP Server，让所有 AI 客户端只需连接一个入口即可访问所有工具。

核心机制

网关模式（Gateway Pattern）

传统网状直连：
Copilot ──→ MCP Server A
OpenCode ──→ MCP Server A
Codex ──────→ MCP Server B

Docker Gateway 星型结构：
Copilot ──→ Gateway ──→ MCP Server A
OpenCode ──→ Gateway ──→ MCP Server B
Codex ──────→ Gateway ──→ MCP Server C

核心价值：

配置解耦：更新 API Key 只需在 Docker 改一次，所有 AI 自动生效
容器隔离：每个 MCP Server 运行在独立容器中，环境不冲突
统一入口：所有 AI 客户端只需配置一条 Gateway 命令
自动热更新：新增工具后所有客户端立即可用

启动命令

docker mcp gateway run -q

关键参数：

-q（quiet 静默模式）：必须添加，否则 Docker 启动日志会污染 MCP 的 stdio JSON 通信信道
--profile <name>：指定使用哪个配置文件（Profile）

通信协议

Gateway 使用 MCP 标准协议（JSON-RPC over stdio）与 AI 客户端通信：

AI 客户端通过 stdin 发送 JSON-RPC 请求
Gateway 路由请求到对应的容器化 Server
Server 执行后通过 Gateway 返回结果到 stdout

最小例子

在 opencode.json 中配置

{
  "mcp": {
    "docker-toolkit-gateway": {
      "type": "local",
      "command": [
        "docker",
        "mcp",
        "gateway",
        "run",
        "-q"
      ]
    }
  }
}

在 VS Code 的 mcp.json 中配置

{
  "mcpServers": {
    "docker-toolkit-gateway": {
      "command": "docker",
      "args": [
        "mcp",
        "gateway",
        "run",
        "-q"
      ]
    }
  }
}

边界与易混淆点

不是

不是 Agent 框架：Gateway 只负责路由和代理，不做任务编排
不是 MCP Server：Gateway 本身不提供工具，而是代理后端 Server 的工具
不是包管理器：虽然有 Catalog，但核心价值是统一网关而非简化安装

必须满足的前提

Docker Desktop 必须在后台运行
需要较新版本的 Docker Desktop 且开启 Beta 功能中的 MCP Toolkit
Gateway 启动的 Catalog 中至少有一个 Server，否则可能闪退

常见问题

Q: 为什么必须加 -q 参数？

MCP 协议的 stdio 模式要求 stdout 只能包含合法 JSON。Docker 默认会输出启动日志（如 Reading configuration...），这些非 JSON 内容会污染通信信道，导致 AI 客户端解析失败。

Q: Windows 下 OAuth 报错 dial unix \\.\pipe\dockerBackendApiServer 怎么办？

这是 Docker Desktop 在 Windows 下的已知 Beta 版小 Bug，不影响核心功能运行，可忽略。

Q: Brave 搜索的密钥没配好？

在 Docker Desktop 的 MCP 界面中，给 Brave 填上 API Key 即可消除 Warning: Secret 'brave.api_key' not found 警告。

Docker MCP Gateway

一句话定义

核心机制

网关模式（Gateway Pattern）

启动命令

通信协议

最小例子

在 opencode.json 中配置

在 VS Code 的 mcp.json 中配置

边界与易混淆点

不是

必须满足的前提

常见问题

相关工具

Related notes