Claude Code MCP 配置：.mcp.json 格式、作用域与 claude mcp add

Claude Code 的 MCP 配置和它的其他设置不在同一个地方、JSON 结构不同、作用域规则也自成一套。绝大多数「MCP server 加了却不出现」的问题，都出在这三件事之一。本文讲清 Claude Code MCP 配置的格式、三种作用域、能替你写配置的 claude mcp 命令，以及怎么确认到底加载了什么。

如果你只想知道每个文件在磁盘上的位置，可以看姊妹篇 Claude Code 配置文件位置，那篇列了全部路径；本文讲的是 MCP 配置里该写什么、怎么写对。

Claude Code MCP 配置速览

放在哪： 不在 settings.json 里。项目作用域的 server 写在仓库根目录的 .mcp.json；本地（local）与用户（user）作用域的 server 存在 ~/.claude.json。
顶层键： mcpServers，一个以 server 名为键的对象。
两类 server： Claude Code 自己拉起的本地进程（stdio），以及通过 HTTP 连接的远程 server。
最省事的写法： 用 claude mcp add 或 claude mcp add-json，它会按你选的作用域写进正确的文件。
怎么核对： 终端里跑 claude mcp list，或在会话里输入 /mcp。

MCP 配置的格式

Claude Code 里所有 MCP 配置的外层结构都一样：一个 mcpServers 对象，每个 server 一个条目。条目内部写什么，取决于传输方式。

本地（stdio）server：Claude Code 以子进程方式启动一条命令，通过标准输入输出与它通信：

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"],
      "env": {
        "LOG_LEVEL": "info"
      }
    }
  }
}

command 是可执行文件，必须能在 Claude Code 的运行环境里找到——这个环境不一定等于你的交互式 shell。
args 是数组，每个参数单独一个字符串，不要把整行命令塞进一个字符串。
env 只对这个 server 进程生效。代理变量、下游服务的 token、日志级别都放这里。
stdio server 的 type 可以省略，带 command 的条目默认按 stdio 处理。

远程（HTTP）server：服务已经在别处运行，Claude Code 连接它的 URL：

{
  "mcpServers": {
    "issue-tracker": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${TRACKER_TOKEN}"
      }
    }
  }
}

可流式 HTTP 的 server，type 写 http。部分老 server 只提供 sse，这种传输仍可用，但正在被 HTTP 取代。
headers 用来放 Bearer token、API Key 这类静态鉴权。使用 OAuth 的 server 不需要写 header，在会话里通过 /mcp 完成授权，Claude Code 会替你保存 token。

三种作用域，各写进哪个文件

Claude Code 把每个 MCP server 存在三种作用域之一。作用域决定条目写进哪个文件、谁能用到这个 server。

作用域	存储位置	谁能用	典型用途
local（默认）	`~/.claude.json` 中当前项目路径下	仅你本人、仅当前项目	个人或试验性 server、带你个人 token 的 server
project	仓库根目录 `.mcp.json`	所有克隆该仓库的人	团队共享工具，提交进版本库
user	`~/.claude.json` 顶层	仅你本人、所有项目	想在哪都能用的工具，比如文档检索类 server

同名 server 出现在多个作用域时，local 优先于 project，project 优先于 user。「改了 .mcp.json 却没反应」最常见的原因就是这个优先级：一个同名的 local 条目把它盖住了。

项目作用域还有两条规则要记住：

项目 server 需要确认。 Claude Code 第一次在某个仓库的 .mcp.json 里看到一个 server 时，会询问是否信任。如果你曾经拒绝过、想重新弹出提示，用 claude mcp reset-project-choices 清除这些选择。设置项 enableAllProjectMcpServers、enabledMcpjsonServers、disabledMcpjsonServers 可以非交互地控制同样的行为。
绝不要提交真实密钥。 .mcp.json 本来就是要共享的，写进去的 token 等于公开给所有有仓库权限的人。请用下一节的环境变量展开，或者把带凭据的 server 放在 local / user 作用域。

企业还可以在 managed-settings.json 同级目录部署托管的 MCP 配置，并通过托管策略允许或禁止特定 server，这些条目在用户侧无法覆盖。

在 .mcp.json 里使用环境变量

.mcp.json 支持变量展开，这正是共享文件能安全提交的关键：

${VAR} 会被替换为启动 Claude Code 时环境中 VAR 的值；
${VAR:-default} 在 VAR 未设置时使用 default。

展开在 command、args、env、url、headers 里都有效。团队可以这样提交：

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "${INTERNAL_MCP_URL:-https://mcp.internal.example.com/mcp}",
      "headers": {
        "Authorization": "Bearer ${INTERNAL_MCP_TOKEN}"
      }
    }
  }
}

每位开发者在自己的 shell 配置里导出 INTERNAL_MCP_TOKEN 即可。如果必需的变量缺失又没有默认值，server 会启动失败，/mcp 会显示为失败，而不是悄悄在无鉴权状态下连上。

用 claude mcp add 添加 server

手写 JSON 也可以，但 CLI 会按作用域把条目写进正确的文件，能避开大部分语法错误。基本形式：stdio 用 claude mcp add [选项] <名称> -- <命令> [参数...]，远程用 claude mcp add --transport http <名称> <URL>。

# stdio server，local 作用域（默认）
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /Users/me/projects

# 带环境变量的 stdio server，写进 .mcp.json 与团队共享
claude mcp add --scope project --env LOG_LEVEL=info filesystem -- npx -y @modelcontextprotocol/server-filesystem .

# 带 header 的远程 HTTP server，所有项目可用
claude mcp add --transport http --scope user --header "Authorization: Bearer $TRACKER_TOKEN" issue-tracker https://mcp.example.com/mcp

# 直接粘贴一段完整 JSON 条目
claude mcp add-json weather '{"type":"stdio","command":"node","args":["/opt/weather-mcp/index.js"]}'

# 导入你在 Claude Desktop 里已配好的 server（macOS 与 WSL）
claude mcp add-from-claude-desktop

容易踩的几个点：

-- 分隔符。 -- 之后的内容都属于 server 命令。漏掉它，原本给 server 的参数（比如 -y）会被当成 claude 自己的参数解析，导致添加失败或存进错误的命令。
选项写在名称前面。 --scope、--env、--header、--transport 都是 claude mcp add 的选项，放在 server 名称之前。
header 要加引号。 header 值里有空格，必须加引号。上例中 shell 会在添加时就把 $TRACKER_TOKEN 展开、存成明文 token；如果你想保留变量引用，请用 add-json 或直接编辑 .mcp.json，写成 ${TRACKER_TOKEN}。

管理已添加的 server：

claude mcp list            # 列出全部 server 及连接状态
claude mcp get filesystem  # 查看单个 server 的详情，包括作用域
claude mcp remove filesystem --scope project

单次运行或 CI 场景下，claude --mcp-config ./ci-mcp.json 会从指定文件加载 server；再加上 --strict-mcp-config，则忽略其他所有 MCP 配置，只认这一个文件。

Windows：用 cmd /c 包住 npx

在原生 Windows（非 WSL）上，npx 是批处理脚本，Claude Code 无法直接把它作为进程拉起。直接写 npx ... 添加的 server 会报类似「connection closed」的错误。需要包一层：

claude mcp add filesystem -- cmd /c npx -y @modelcontextprotocol/server-filesystem C:\Users\me\projects

写成 JSON 就是 "command": "cmd"、"args": ["/c", "npx", "-y", "..."]。WSL 下直接用 Linux 写法即可。

怎么确认实际加载了什么

别相信你刚改过的那个文件，去问 Claude Code 它看到了什么：

终端里： claude mcp list 会显示每个 server 的状态。预期的 server 不在列表里，是作用域或文件的问题；在列表里但显示失败，是启动或鉴权的问题。
会话里： /mcp 列出已连接的 server、它们提供的工具，以及失败的 server；需要 OAuth 的远程 server 也在这里完成授权。
调试输出： 用 --debug 启动 Claude Code（老版本是 --mcp-debug）会打印 server 启动报错，通常比瞎猜快得多。

常见 MCP 配置问题与解决办法

把 server 写进了 settings.json。 settings.json 里的 MCP server 会被忽略。把条目移到 .mcp.json，或用 claude mcp add 重新添加。
改了 .mcp.json 没有变化。 有同名的 local / user 作用域 server 优先生效，或者项目 server 在信任提示时被拒绝了。用 claude mcp get <名称> 看实际生效的作用域。
server 启动超时。 首次运行较慢（npx 下载、拉取容器镜像）可能超过启动超时。在启动前设置 MCP_TIMEOUT（单位毫秒），例如 MCP_TIMEOUT=30000 claude。
工具输出被截断。 大体积的工具结果有上限；如果某个 server 确实需要返回大量内容，可以调高 MAX_MCP_OUTPUT_TOKENS。
终端里能跑，Claude Code 里失败。 server 继承的是 Claude Code 的环境，而不是你交互式 shell 的环境。command 写从根目录开始的完整路径，server 需要的变量写进它的 env。
在代理后面 server 连不上网。 stdio server 是独立进程，需要在 env 里给它 HTTP_PROXY / HTTPS_PROXY。桌面端的同类分层可参考 Claude Desktop 怎么走 HTTP 代理。
JSON 不合法。 一个多余的逗号或没加引号的键，会让整个文件读不出来。重启前先用任意 JSON 校验工具检查一遍。

MCP 配置与 API 端点互不相干

MCP 配置决定 Claude Code 能调用哪些工具；模型端点由 ANTHROPIC_BASE_URL 以及 settings.json 或环境变量里的凭据决定，控制模型请求发往哪里。两者互不影响：把 Claude Code 指向 ROIBest AI 这类网关或中转，不会改变 MCP server 的加载方式；新增一个 MCP server，也不会把模型流量导到别处。如果两边都要配，Claude Code 配置一文讲了设置分层怎么合并，Claude Code 代理配置讲的是端点这一侧。

常见问题

Claude Code 的 MCP 配置文件在哪里？

项目作用域的 server 在仓库根目录的 .mcp.json；local 与 user 作用域的 server 存在用户主目录下的 ~/.claude.json。MCP server 不从 settings.json 读取。

local、project、user 三种作用域有什么区别？

local（默认）只对你本人、当前项目生效；project 写进 .mcp.json，与所有使用该仓库的人共享；user 对你本人在所有项目中生效。同名 server 出现在多个作用域时，local 覆盖 project，project 覆盖 user。

.mcp.json 里能用环境变量吗？

可以。在 command、args、env、url、headers 中使用 ${VAR} 或 ${VAR:-default}。这是让提交进版本库的文件不含 token 的推荐做法。

为什么 /mcp 里显示我的 MCP server 失败？

最常见的原因是：命令不在 Claude Code 能看到的路径上、缺少环境变量、启动时间超过 MCP_TIMEOUT，或者在原生 Windows 上 npx 没有用 cmd /c 包住。用 --debug 启动 Claude Code 可以看到 server 自己的报错输出。