浏览 MCP与Skills教程与资源
Claude Code MCP 配置：local、project、user 作用域与首次调用
在当前项目接入公开文档服务，检查实际加载的作用域、项目审批和工具结果。local 不是项目里的一个配置文件，团队共享也不是第四种 scope。
local、project、user 差在加载与共享，不是远近
| scope | 配置实际存放位置 | 什么时候选择 |
|---|---|---|
| local（默认） | 用户目录的 ~/.claude.json，按当前项目路径保存。 | 只想自己在这个项目试用；不写入仓库，换项目不自动出现。 |
| project | 项目根目录 .mcp.json。 | 团队需要共享同一个非秘密连接定义；每个人的依赖、授权和信任仍要分别完成。 |
| user | ~/.claude.json 的用户范围。 | 本人在多个项目通用的连接；不要把只服务一个项目的权限无意扩大到所有项目。 |
这里的 local 与 .claude/settings.local.json 不同。团队分发是一种维护方式，不是 --scope team。Windows 原生的 ~ 指当前用户；在 WSL 中运行则是 Linux 用户目录。
先在准备使用的项目目录中安装 local 连接
前提是 claude --version 能正常运行，你已经进入目标项目根目录。示例连接 OpenAI 提供的公开 Docs MCP；协议由 Claude Code 处理，它与正在使用哪个模型服务商是两件事。无需把 Anthropic Key 或 OpenAI Key 交给这个端点。已有同名配置时先 get 检查，再决定是否保留。
添加、查看定义，再启动交互会话
claude --version claude mcp add --transport http --scope local openaiDeveloperDocs https://developers.openai.com/mcp claude mcp list claude mcp get openaiDeveloperDocs claude
在 Claude Code 交互界面输入 /mcp，检查连接状态和发现的工具。add 的 Added 消息只说明保存；list/get 的健康状态与当前会话发现结果要继续检查。
让 Claude 查资料，并核对它真的走了这个连接
向会话发送：‘使用 openaiDeveloperDocs 查询 Codex MCP 的配置文件位置与项目可信限制。列出每项结论对应的官方页面；如果工具不可用，停止并给出连接错误。’主线只查询公开资料，不操作项目文件。
展开调用记录，确认 Server、查询参数和返回页面相关。预期结果应包含资料支持的路径与 URL；页面链接能打开还不够，要回查该段确实支持结论。没有工具调用记录而直接回答，不算完成这次 MCP 连接练习。
再在一个不相关的项目中运行 claude mcp list：如果没有其他来源定义，本例 local 连接应不出现。若仍出现，检查是否存在 user、plugin 或账户 connector 的同一连接，不能据此直接断言 local scope 失效。这个对照验证可见性，不验证上游资源权限。
项目配置可以共享，个人授权不能随仓库共享
若团队都要使用，先核对并移除本例 local 定义，再在同一项目添加 project 范围；不要保留两层同名定义让旧配置遮住新文件。下面命令与 JSON 是同一项目配置的两种呈现，不要重复覆盖整份 .mcp.json。
明确移除旧层再添加新层
claude mcp remove openaiDeveloperDocs --scope local claude mcp add --transport http --scope project openaiDeveloperDocs https://developers.openai.com/mcp claude mcp get openaiDeveloperDocs
可共享的无密钥连接定义
{
"mcpServers": {
"openaiDeveloperDocs": {
"type": "http",
"url": "https://developers.openai.com/mcp"
}
}
}仅在你明确需要 user 范围时使用
claude mcp add --transport http --scope user openaiDeveloperDocs https://developers.openai.com/mcp
交互会话会要求审核项目 Server；Pending approval 的下一步是进入 claude 交互检查，不是绕过审批。非交互 -p/SDK/云端行为不同，不把交互确认当作所有执行环境的保护。这里未使用自动批准配置。
改了 .mcp.json 仍不生效，先查同名优先级
Claude Code 的三种常用 scope 同名时按 local → project → user 优先级取整条定义，不是把字段拼接。比如 local 的 URL 是旧地址，而你修了 project 的 URL，加载的仍可能是完整 local 条目；此时反复编辑 .mcp.json 不会解决。get、list 与 /mcp 中的来源和冲突提示比猜文件位置更可靠。
插件与 claude.ai connectors 也可能提供 Server，当前文档还有端点去重规则。所以排查‘删除后仍可见’时要列出全部来源；不能把它们一律说成残留缓存。团队拉下 .mcp.json 后只获得定义，不会自动获得另一位成员的 OAuth 会话、二进制路径或包版本。
若后来改用 stdio，命令放在 -- 后面，客户端参数放在前面；不要把 shell 整段文本写成 command。Windows 的 npx.cmd、GUI/WSL 环境与个人绝对路径要分别核对。共享配置应使用项目可解析的路径与有文档的环境变量，不能提交某位成员电脑的私有路径。
按 list/get 的状态继续，不要统一重装
Pending approval
- 原因
- 项目 .mcp.json 的 Server 尚未得到该环境认可。
- 怎么改
- 进入当前项目的交互 claude，审阅工作区与 Server。只有需要重新作审批选择时才使用 claude mcp reset-project-choices，注意它会重置该项目的既有选择。
同名冲突，实际 URL 不是刚修改的地址
- 原因
- 更高优先级的 local 或 project 定义覆盖了整项。
- 怎么改
- get 核对实际来源，然后使用 remove 名称 --scope 对应层仅移除错误定义；保留有效定义后重开会话。
Failed to connect
- 原因
- 保存成功但连接测试失败；可能是端点、网络或 Server 故障。
- 怎么改
- 先保留时间、URL 与原始错误。公开 Docs 主线不要求 OAuth；换成私有服务时再按它的认证要求处理，不能把所有失败归为 Key 错误。
项目能加载但具体查询被拒绝
- 原因
- scope 控制配置在哪加载，不替外部服务账号授予读取权限。
- 怎么改
- 核对发起上游请求的身份、目标对象与授权范围，用同一对象复测；不要通过扩大到 user scope 解决 403。
删对配置层，再核对账户授权
如果你采用的是 project 或 user 方案，把 scope 改为实际使用的那一项，再重开会话确认。不要为清理一个 Server 删除整个 ~/.claude.json。当前 Claude Code 文档说明，删除远程定义时也清理其本地 OAuth 令牌和注册信息；这仍不能证明提供方所有令牌立即失效。对于有账号授权的服务，还需在提供方撤销访问。本例无 OAuth，不需要添加这一步。
回到添加时的项目执行
claude mcp remove openaiDeveloperDocs --scope local claude mcp list
资料与核对范围
资料核对日：2026-10-10。以下来源支持协议与配置说明；文中的命令、练习和预期结果不代表本站已在所有客户端和系统完成实测。