MCP 服务器配置本身不复杂,但多数问题出在作用域选择和环境不一致上。下面这套流程适合刚接触 Claude Code 的用户,也适合排查工具突然不可用的情况。先说明一点:下面的命令和文件路径基于 Claude Code 的常见版本,具体参数需要结合你的安装版本确认。开始前,先跑一下 claude mcp --help 看看当前支持哪些参数。
先分清项目级和用户级配置
Claude Code 的 MCP 服务器配置入口并非集中在一个全局设置文件里,而是按项目作用域分开管理。项目级配置存放在当前目录下的 .mcp.json 文件中,用户级配置则位于 ~/.claude.json 的 mcpServers 字段下。当你执行 claude mcp add 命令时,默认写入项目配置;若需要全局生效,需显式加上 --scope user 参数。这个区分是避免配置混乱的关键,因为项目配置会优先于用户配置被加载,且不会自动同步到其他项目。
所以你先要确认自己处于哪个项目目录。进入项目后,用 ls -a 查看是否有 .mcp.json。如果你想做一个全局工具,就不要在某个项目目录下执行 add 命令,否则后续换到别的项目就看不到。反过来,如果某个项目里的工具不见了,检查该项目的 .mcp.json 是否覆盖了全局配置。
添加服务器用命令比手改 JSON 更稳
添加 MCP 服务器时,建议使用 claude mcp add 命令而不是手动编辑 JSON。例如添加一个本地 stdio 类型的服务器,可以执行 claude mcp add my-server -- cmd arg1 --port 8080,其中 -- 后面是实际启动命令及参数。若服务器使用 HTTP 传输,则需要指定 --transport http 并提供 URL,如 claude mcp add remote-server --transport http https://example.com/mcp。添加完成后,运行 claude mcp list 可以查看当前作用域下所有服务器及状态,确认配置是否被正确识别。
命令方式的好处是它同时更新了配置文件和索引,不容易出现格式错误。注意 stdio 适合本地进程,比如 Node.js 脚本或 Python 命令;HTTP 类型适合远程服务,比如部署在另一台机器上的 MCP 服务。如果服务器本身支持两种传输方式,优先选 stdio,因为它不依赖网络端口,受防火墙影响小。
验证阶段看这几个信号
配置完成后不要直接开始对话,先用 claude mcp list 检查服务器是否处于 connected 状态。如果显示 error 或 disconnected,可以运行 claude mcp get server-name 查看详细的错误日志。对于 stdio 类型服务器,常见问题是指令路径不对;对于 http 类型,常见问题是缺少 Authorization 头或 CORS 限制。还可以在 Claude Code 对话中输入 /mcp 命令,交互式地查看和切换已配置的服务器,验证工具是否真正可用。这一步能省去后续反复调试的时间。
connected 只是第一步,还要看工具是否能被模型真正调用。你可以直接在对话中要求“用 server-name 里的某个工具做一件具体的事”,然后观察返回结果。如果模型无法调用,返回信息里通常会包含工具名和错误代码。这个信号比状态列表更可靠。
环境变量和绝对路径是高频坑
作用域之外,环境变量是另一个高频故障点。MCP 服务器进程会继承启动 Claude Code 的那个 shell 的环境变量,所以如果你把 API Key 写在 ~/.bashrc 里,但 Claude Code 是从图形菜单启动的,那些变量可能根本没加载。建议在启动前先运行 echo $API_KEY 确认变量存在,或者把变量写在 .mcp.json 所在目录的启动脚本里。
路径问题同样常见。很多服务器配置里用的是相对路径,比如 ./server.js,一旦工作目录变化就会找不到文件。建议在配置文件中使用绝对路径,或至少在项目目录下先测试好相对路径再固定下来。如果日志显示 ENOENT 或 command not found,多半是路径问题。
权限边界提前收紧
不要下意识地把所有权限开放给 MCP 服务器。Claude Code 会以你的系统用户身份运行这些工具,所以任何 MCP 工具都可能触发文件读写、命令执行等敏感操作。如果服务器来自第三方,先看源码或发布者,最好把它跑在一个低权限用户或容器里。对于需要访问外部 API 的服务器,在环境变量里只给最小权限的 token,而不是把 root 凭据透传进去。
需要说明的是,这不是劝退你使用 MCP,而是提醒你在配置阶段就明确这台服务器需要哪些权限。比如一个只读文件的服务器,不需要给它监听端口或写文件的权限。权限收得越紧,后续出问题时的排查范围越小。
settings.json 与 .mcp.json 的优先级
如果你更习惯静态配置文件,也可以在 settings.json 的 mcpServers 字段里声明服务器,格式与 .mcp.json 相同。但两种方式不能混用:同一作用域下,如果同时存在 .mcp.json 和 settings.json 中的 mcpServers 声明,系统会优先读取 .mcp.json,而忽略 settings.json 里的声明。所以当你改了 settings.json 但工具没变化,先去当前目录找有没有残留的 .mcp.json。
我的建议是统一用 claude mcp add 命令,它默认写 .mcp.json,你不需要关心优先级。如果必须用 settings.json,则确保该作用域下没有 .mcp.json 文件。每换一次项目,先检查一遍这两个位置。
配置完成后,完整的验证链路是:确认作用域、添加服务器、查看状态、实际调用工具。任何一步出现异常,都先看错误日志,再检查环境变量和权限。MCP 服务器本身并不神秘,出问题往往不是配置语法的问题,而是作用域和环境变量脱离了预期。