它到底是什么

--mcp-config 是 Claude Code 的 CLI 启动 flag。官方 CLI reference 的描述是："Load MCP servers from JSON files or strings (space-separated)"。也就是说，它接受 JSON 文件路径或 JSON 字符串，可以一次传多个，用空格分隔。

官方文档给出的语法：

--mcp-config <path-or-json> [<path-or-json> ...]

• 文档没有为它写默认值。
• 官方示例是 claude --mcp-config ./mcp.json。

用法

# 从文件加载
claude --mcp-config ./mcp.json

# 直接传 JSON 字符串(GitHub issue #14490 中的复现命令采用了这种形式)
claude --mcp-config '{"mcpServers":{"axiom":{"type":"stdio","command":"npx","args":["-y","mcp-remote","https://mcp.axiom.co/mcp"]}}}'

官方 MCP 文档说明，项目根目录 .mcp.json 的顶层结构是 mcpServers 对象，以服务器名为键。type 可取 http、stdio、sse、ws，其中 sse 已标注为 deprecated。服务器名只能包含字母、数字、连字符和下划线。

{
  "mcpServers": {
    "server-name": {
      "type": "stdio",
      "command": "...",
      "args": [],
      "env": {}
    }
  }
}

与其他 flag 的组合 / 互斥

运行约束 / 限制

经典使用场景

• 非交互运行：MCP 文档提到该 flag 用于 claude -p 和 Agent SDK 会话。传入 -p 时，CLI 会等待服务器连接后再开始第一轮。
• 只加载指定的服务器：配合 --strict-mcp-config，会话只用你传入的服务器，忽略其他 MCP 配置。

常见坑

• --strict-mcp-config 可能不覆盖 disabledMcpServers:GitHub issue #14490 报告，在 Claude Code 2.0.72（macOS）上，如果某服务器在项目的 disabledMcpServers（存放于 ~/.claude.json）里，即使用 --mcp-config 加 --strict-mcp-config 加载它，它仍保持 disabled。这个 issue 已被以 "closed as not planned" 关闭，并带 autoclose 标签，所以问题不一定已被修复。issue 里的 workaround 是手动编辑 ~/.claude.json，把它从 disabledMcpServers 中移除。
• .mcp.json 里的环境变量展开规则不一定适用于 --mcp-config:MCP 文档只在 .mcp.json 一节描述了 ${VAR} 和 ${VAR:-default}。文档没有说明 --mcp-config 传入的文件或字符串是否同样展开，请自行验证。

来源

• CLI reference - Claude Code Docs（用户给的 docs.claude.com/en/docs/claude-code/cli-reference 会 301 跳转到这里）
• Connect Claude Code to tools via MCP - Claude Code Docs
• --strict-mcp-config does not override disabledMcpServers · Issue #14490 · anthropics/claude-code