[!info] related notes

• 前置笔记: docker-mcp-gateway
• 相关 MOC: docker-mcp-toolkit-moc, mcp-moc
• 关联笔记: mcp-filesystem, github-copilot, opencode

MCP 客户端配置指南

目标

让所有 AI 客户端通过 Docker MCP Gateway 统一访问 MCP 工具，实现一次配置、多处使用。

前置条件

1. Docker Desktop 已安装并运行
2. 在 Docker Desktop 的 Beta features 中开启了 MCP Toolkit
3. 在 MCP Toolkit 界面中已添加至少一个 MCP Server

步骤

1. VS Code (GitHub Copilot)

配置文件位置：

• 全局生效：VS Code 命令面板 → MCP: Open User Configuration
• 项目级：项目根目录创建 .vscode/mcp.json

配置内容：

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

启用工具：

1. 打开 Copilot Chat 视图
2. 点击工具/附件图标 (🔧)
3. 确保 Docker Gateway 透传的工具处于勾选状态
4. 将对话模式切换为 Agent

2. OpenCode

配置文件位置：

• 全局生效：~/.config/opencode/opencode.json（Windows: C:\Users\baker\.config\opencode\opencode.jsonc）
• 项目级：项目根目录创建 opencode.json

配置内容（OpenCode 使用特殊格式）：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "docker-toolkit-gateway": {
      "type": "local",
      "command": [
        "docker",
        "mcp",
        "gateway",
        "run",
        "-q"
      ]
    }
  }
}

关键区别：

• 使用 mcp 字段（不是 mcpServers）
• 需要 type: "local" 声明
• command 是数组格式（不是字符串 + args）

3. Codex

配置文件位置：~/.codex/config.toml

配置内容：

[mcp_servers.docker-toolkit-gateway]
command = "docker"
args = ["mcp", "gateway", "run", "-q"]

4. Claude Desktop

配置文件位置：

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

配置内容：

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

验证

测试 Gateway 连通性

在终端手动运行 Gateway 命令，观察输出：

docker mcp gateway run -q

正常启动后会输出 JSON-RPC 格式的消息，如：

{"jsonrpc":"2.0","method":"notifications/tools/list_changed","params":{}}

测试 AI 客户端

在 AI 客户端中询问：

检查一下你现在连接了哪些 MCP 工具

成功后应列出 Gateway 代理的所有工具（如 Playwright 的 21 个工具、Brave 的 6 个工具等）。

使用特定 Profile

如果在 Docker 中创建了特定的 Profile（如 my-tools），在命令末尾添加：

"command": ["docker", "mcp", "gateway", "run", "-q", "--profile", "my-tools"]

常见问题

Q: 报错 Invalid input mcp.xxx

原因：配置格式不符合客户端的 Schema 校验。

解决：

• VS Code/Claude：使用 mcpServers 字段
• OpenCode：使用 mcp 字段 + type: "local" + command 数组格式

Q: Gateway 启动失败

排查：

1. 确认 Docker Desktop 正在运行
2. 终端运行 docker mcp gateway run 查看具体报错
3. 确认 MCP Toolkit 功能已开启
4. 确认 Catalog 中至少有一个 Server

Q: 工具调用无响应

排查：

1. 确认命令中包含 -q 参数
2. 检查 Docker 容器是否正常运行
3. 查看 AI 客户端的日志输出

Q: WSL 环境下找不到 Docker

解决：

1. 打开 Docker Desktop → Settings → Resources → WSL Integration
2. 确保当前 WSL 发行版被勾选

相关笔记

• docker-mcp-gateway：Gateway 的核心概念
• mcp-filesystem：MCP 文件系统服务器配置
• github-copilot：Copilot 使用指南
• opencode：OpenCode 使用指南

Related notes

• Docker MOC
• MCP MOC
• MCP