Claude Code 接入 MCP：一条命令的事，坑在作用域
一句话结论：Claude Code 里接入 MCP 服务器只需 claude mcp add 一条命令，真正需要想清楚的是三个作用域（local/project/user）选哪个、以及 .mcp.json 里那些容易写错的字段。按 code.claude.com 官方文档的说法，该接服务器的信号是：你正在从别的工具里复制粘贴数据到对话。
基础流程四步走
- 在项目目录的终端（不是 claude 会话内）执行
claude mcp add --transport http 服务器名 https://服务器地址/mcp；本地进程型服务器用claude mcp add 名称 -- 启动命令 参数。 - 运行
claude mcp list查看连接状态，✔ 表示连通；新会话里也可用 /mcp 命令管理。 - 在会话中直接提需求，Claude 会自动选择服务器的工具；首次调用会请求授权，批准即可。
- 不用时执行
claude mcp remove 服务器名移除——每个服务器的工具描述都会占上下文，别留僵尸配置。
三种作用域怎么选
| 作用域 | 存储位置 | 适用场景 |
|---|---|---|
| local（默认） | 项目私有，仅当前用户当前项目 | 个人试验、涉密配置 |
| project | 项目根目录 .mcp.json | 提交到版本库给团队共用 |
| user | 用户主目录 .claude.json | 个人跨所有项目复用 |
同名服务器按 local > project > user 优先级覆盖。改作用域没有原地迁移命令，只能 remove 后重新 add 。
两个高频坑
一是 .mcp.json 里写了 url 却没写 type：Claude Code 会把无 type 的条目当 stdio 服务器解析然后报错跳过，远程服务器必须写 "type": "http"（旧配置的 streamable-http 是合法别名）。二是 环境变量展开：.mcp.json 支持 ${VAR} 语法引用本机环境变量，token 别明文写进要提交的文件。
接入前先确认信任来源：能抓取外部内容的服务器存在提示词注入风险，来路不明的服务器不要加。
更多客户端（Cursor 、 VS Code）的接入对照可看站内MCP 客户端配置；服务器端原理与选型见MCP 入门教程与MCP 服务器推荐清单。
claude mcp add 报错 command: expected string
这是旧版本对”有 url 无 type”条目的报错写法，给条目加上 “type”: “http” 并升级 Claude Code 到较新版本即可。
服务器显示 inactive 怎么排查
先 claude mcp get 服务器名 看定义与作用域；本地服务器检查命令能否独立运行、环境变量是否齐全；远程服务器检查网络与鉴权头。
项目级 .mcp.json 要提交到 git 吗
工具型配置可以提交，团队共享是它的设计目的；但含密钥的 env 字段要用 ${VAR} 引用，密钥本身走本地环境变量或 secrets 管理。
评论 (0)