服务对象与地域限制
PuppyIP 仅面向海外合规企业及其授权人员提供服务,不面向中国大陆地区开放或提供代理服务。本服务仅限用于中国大陆境外的合法业务活动,严禁在中国大陆境内使用本服务。
代理 IP 或服务器位于境外,不改变上述限制。不得通过中转、转接、共享或转售向中国大陆境内的最终使用者提供本服务。使用前请阅读用户服务协议。
本文要点
- Claude Code v2.1.327 起,mcp add-json 可以在普通终端从标准输入读取一个服务器对象。
- 默认 local 作用域只在当前项目下对自己可见。团队共享需使用 project 作用域。
- 看到 Added 后,用 claude mcp get 检查状态,再根据提示处理项目审批、认证或连接。
先确认版本和输入的 JSON
Anthropic 在 Claude Code v2.1.327 增加了 <code>claude mcp add-json <name> -</code>,末尾的 <code>-</code> 让 CLI 从标准输入读取配置。先在准备执行命令的同一个普通终端运行 <code>claude --version</code>。如果机器装过多个版本,以这次命令实际调用的版本为准。到目标项目目录执行注册,避免命令跑在已经打开的 Claude Code 会话里。
服务器配置文件 <code>server.json</code> 应只包含一个对象。用作格式示例的远端 HTTP 配置是 <code>{"type":"http","url":"https://mcp.example.com/mcp"}</code>。实际使用时替换成服务提供方给出的 MCP 地址。如果拿到的是带 <code>mcpServers</code> 的完整文档,先取出目标名称对应的对象。命令中的 <code>example-api</code> 是本地注册时使用的服务器名称。
用管道注册,再核对保存范围
在 Bash 或 Zsh 中执行 <code>cat server.json | claude mcp add-json example-api -</code>。也可以用输入重定向 <code>claude mcp add-json example-api - < server.json</code>。这适用于示例所用的 POSIX shell 语法。出现 JSON 解析错误时,先用本地编辑器核对文件能否解析为一个对象,再核对传输类型和 URL 是否齐全。
默认 <code>local</code> 作用域只在注册时的项目下对当前用户可见。要供团队在同一项目使用,选择 <code>project</code>,Claude Code 把记录写入项目根目录的 <code>.mcp.json</code>,使用时按提示完成项目服务器审批。要让同一用户跨项目使用,选择 <code>user</code>。如果换目录后看不到服务器,先回到注册时的项目运行 <code>claude mcp get example-api</code>,核对当前条目的作用域和地址。
注册服务器并检查状态
bashcat server.json | claude mcp add-json example-api -
claude mcp get example-api
根据状态检查批准、认证或连接
出现 <code>Added</code> 表示 CLI 已保存配置。继续运行 <code>claude mcp get example-api</code> 查看这一个条目的详情,或用 <code>claude mcp list</code> 查看当前项目可见的服务器。等待项目批准时,在目标项目打开 Claude Code,核对来源后按提示处理。远端服务若显示 <code>Needs authentication</code>,可在会话中打开 <code>/mcp</code> 查看该服务支持的认证步骤。
如果显示 <code>Failed to connect</code>,对照服务提供方的文档核对传输类型和完整端点路径,再确认当前网络能访问服务。通用网页可打开只能说明该网页可访问。定位到具体失败后,再在同一目录执行 <code>claude mcp get example-api</code> 复测。若连接正常但某个工具仍不可用,还要核对该服务对当前账号开放的工具和权限。
如果使用 v2.1.329 或更新版本,并且远程 HTTP MCP 服务器拒绝连接时返回了 JSON-RPC 错误,可以在会话中打开 <code>/mcp</code>、选择该服务器,再查看 <code>Server message</code>。一般连接失败也可用 <code>claude mcp get example-api</code> 查看 <code>Issue:</code> 行是否提供详情。遇到没有服务端消息的错误,继续核对失败阶段、端点和授权。
共享配置时检查凭据保存位置
管道传递让 JSON 不必作为命令行参数传入,原始文件仍可能保留其内容,注册后的配置也会按所选作用域保存。共享 <code>.mcp.json</code> 时保留普通参数,并按服务支持的认证方式管理凭据。Claude Code 文档允许在 <code>.mcp.json</code> 的 <code>headers</code> 等字段引用环境变量。使用这种配置时,应在启动 Claude Code 的同一个环境里核对变量是否已设置,避免把实际令牌写入项目文件或提交到版本库。
资料来源
常见问题
添加成功后为什么还提示认证?
添加命令保存配置。远端服务器如果要求用户登录,连接前还需要完成服务支持的认证。在目标项目打开 Claude Code 的 `/mcp` 查看提示。
可以直接把整个 .mcp.json 传给 add-json 吗?
单次 add-json 需要一个服务器对象。对带 mcpServers 的文件,应取出目标名称对应的对象,再将它送入标准输入。
换项目后为什么找不到已注册的服务器?
默认 local 只在原项目下对当前用户可见。回到注册时的项目核对作用域。共享给同项目的团队时,使用 project 作用域和项目审批流程。