配置 Claude Code MCP，可以把 Agent harness 连接到 Model Context Protocol Server 暴露的工具与上下文。Server 可以增加文档搜索、Issue 管理、设计数据、浏览器操作、数据库访问或内部私有工具，也会扩大 Agent 能够接触的数据和外部动作。因此，MCP 配置既是能力选择，也是权限选择。
本文只讲当前 Claude Code 专属路径：选择 HTTP 或 STDIO、运行 claude mcp add、选择 local、project 或 user scope、完成认证、验证连接，以及移除或替换 Server。命令和行为已在 2026 年 9 月 11 日按 Anthropic 官方文档核验；本文没有替你实测任何第三方 Server 或凭据。
MCP 配置属于 Agent harness，不属于模型本身。如果这两个层级仍容易混淆，可以先阅读 Agent harness 与模型的区别。
Claude Code MCP 配置做了什么
MCP 为 Claude Code 提供了一套发现和调用 Server 工具的标准方式。Server 描述工具，并负责与外部系统的实际连接；Claude Code 则在自己的 Session 与权限控制中决定何时建议或调用这些工具。
整个配置包含五个相互独立的部分：
- Transport： Server 是远程 HTTP endpoint，还是本地 STDIO 进程。
- Configuration： Server 名称、URL 或命令、参数与环境。
- Scope： Server 只为一个项目加载、与该项目团队共享，还是跨你的所有项目可用。
- Authentication： OAuth、Token header，或本地进程使用的凭据。
- Verification： 证明配置已写入、Server 已连接，并且目标工具能安全完成任务。
不要把 MCP 连接成功当作 Server 值得信任的证明。Claude Code 完全可能正确连接到一个暴露了过宽或危险工具的 Server。
运行 claude mcp add 前先准备什么
从 MCP Server 所有者的最新文档中收集：
- 准确 HTTPS URL 或本地启动命令；
- 支持的 transport；
- 必要的包、二进制文件和运行时版本；
- 认证方式与最小上游权限；
- Server 提供的工具及其副作用；
- 预期使用者与项目；
- 移除或撤销访问的路径。
执行本地命令前先审查它。STDIO Server 是在你机器上运行的进程，不是被动配置文件。检查包来源与要求的环境变量，不要给予超过工作流实际需求的文件系统或凭据访问。
对远程 Server，要核验来源。相似域名与转贴的安装片段都不可靠；优先采用提供方自己的文档，以及由它控制的 HTTPS endpoint。
第 1 步：选择 HTTP 或 STDIO
Anthropic 当前的 Claude Code MCP 文档推荐用 HTTP 连接远程 MCP Server。在 JSON 配置中，streamable-http 可以作为 http 的别名。
Claude Code 当前文档已把 SSE 标为 deprecated（弃用）。Server 提供 HTTP 时，应使用 HTTP。从 Claude Code v2.1.265 开始，以 --transport http 添加远程 Server 时，客户端会先尝试 HTTP；旧 endpoint 拒绝 HTTP 时，再自动回退到 SSE。使用更早版本，或提供方明确要求直接连接 SSE 时，才使用 --transport sse，并在提供方新增 HTTP 后迁移。
Claude Code 也记录了 WebSocket 配置，但那是一条更专门、只能通过 JSON 配置的路径，认证限制也不同。不要因为 endpoint 在远端就随意选择 WebSocket；应遵循 Server 文档指定的 transport。WebSocket Server 不会出现在 claude mcp list 中，应改用 claude mcp get <name> 或 /mcp 验证。
第 2 步：添加 Server
远程 HTTP Server 的基础命令是：
使用占位值的示例：
本地 STDIO Server 使用：
双横线很重要。它后面的内容会原样传给本地 Server 命令，而不会被 Claude Code 当作自己的参数解析：
这里的包名和 URL 只用于展示命令格式。只能用 Server 当前官方说明中的真实值替换。
命令打印 Added ... 时，表示 Claude Code 已写入配置；它不能证明凭据有效、Server 可访问或每个工具都能工作。
第 3 步：选择 local、project 或 user scope
Claude Code 有三种配置作用域，分享行为不同：
Local 是默认值。想明确表达意图时添加 --scope local；团队项目配置用 --scope project；个人跨项目配置用 --scope user：
Project scope 会创建或更新 .mcp.json，可以提交到版本控制，让协作者获得同一 Server 定义。不要在其中放凭据。交互式 Session 会在使用项目级 .mcp.json Server 前要求批准；非交互 claude -p、Agent SDK 与 cloud session 无法显示这项批准提示，会不经询问加载 project-scoped Server。如果这不是预期行为，可以用 disabledMcpjsonServers 阻止指定条目、让执行环境不加载 project settings，或用 --strict-mcp-config 只加载明确指定的配置。
如果同名 Server 同时出现在多个 scope，Claude Code v2.1.259 及以上版本会优先使用组织提供的 managedMcpServers 定义。之后才依次是 local、project、user、plugin 与 claude.ai connector。条目不会逐字段合并。因此，managed 或本地旧定义可能遮住更新后的项目定义，直到管理员修改上层定义或你删除重复项。
OpenCode 使用另一套配置合同。不要把它的路径或命令复制到 Claude Code；需要时参考单独的 OpenCode MCP 指南。
第 4 步：认证且不暴露凭据
远程 HTTP Server 支持 OAuth 时，先添加 Server，再在 Claude Code 中运行：
按浏览器登录流程完成认证。当前 Claude Code 也支持直接从交互式 shell 发起认证：
OAuth 适用于 HTTP Server。只申请工作流需要的最小 scope；不再需要访问时，在 /mcp 使用 “Clear authentication”，或运行 claude mcp logout <name>。
有些提供方不使用 OAuth，而要求 Token header。不要把长期 Token 粘进被提交的 .mcp.json。项目配置支持环境变量展开：
Claude Code 支持在 command、args、env、URL 和 headers 中使用 ${VAR} 与 ${VAR:-default}。当前版本遇到没有默认值的缺失变量时会警告，并可能在加载配置中保留字面量 ${VAR}。不要假设展开已经发生；连接前检查 claude mcp list 或 /mcp 的警告，并确认变量存在。
对 STDIO，只转发 Server 真正需要的环境变量。本地数据库、云账号或源代码托管凭据都应使用窄权限上游身份。首次测试时，只读权限比 Owner 级 Token 更合适。
第 5 步：验证配置与连接
按顺序使用管理命令：
claude mcp list 显示已配置 Server 与状态；claude mcp get <name> 显示单个 Server 详情。当前状态可能包括 connected、needs authentication、failed to connect、pending approval、rejected 或 disabled。
然后打开交互式 Claude Code Session 并运行：
对 project scope Server，只有在你信任工作区并理解其中命令或 URL 后，才审阅并批准 .mcp.json 条目。克隆下来的仓库不能只靠提交一项批准设置，就让自己自动变成可信工作区。
Server 报错时，用状态详情排查，但不要公开凭据。常见原因包括 URL 错误、运行时缺失、包不可用、Token 无效、环境变量缺失或项目条目未批准。
状态是有用证据，却不是最终测试。“Added”表示写入配置，“connected”表示 transport 和握手成功；两者都不能证明工具结果正确或写入安全。
第 6 步：安全测试一个工具
先从无害、边界很窄的读取动作开始：
- 读取一页已知公开文档；
- 用只读账号列出少量测试记录；
- 查看一次性项目的 metadata；
- 要求 Server 列出可用来源，但不创建或修改任何内容。
批准调用前，检查选中的 Server、工具名、参数、路径、资源和账号。完成后把结果与来源对照。即使回答看起来合理，只要查错了仓库、数据库或工作区，就不能算验证通过。
之后才测试写工具，而且只针对一次性目标。确认 Claude Code 出现了预期权限请求，并确保上游账号不能影响不相关数据。
MCP 工具处在更大的信任边界里。使用 Coding Agent 工作区安全清单，一起审查仓库范围、本地进程、网络目的地、secret 和外部副作用。
管理、替换或移除 Server
Claude Code 当前的管理命令是：
在 Session 中用 /mcp 检查状态与认证。同名 Server 存在于多个 scope 时，明确移除目标定义：
Server 所有者变化、endpoint 停用、包不再可信，或工作流不再需要它时，应移除配置。对远程 Server，claude mcp remove 还会删除 Claude Code 为该 Server 保存的 OAuth Token 与客户端注册。不过，本地清理不一定会撤销提供方一侧的授权，也不会自动使单独签发的 Token 失效；提供方支持时，仍应撤销或轮换上游访问。
替换 Server 时，避免在多个 scope 创建同名条目。先决定哪个定义拥有名称，删除旧副本，再添加新配置并重复完整验证流程。
常见配置失败
出现 Added，但 Server 失败。 add 命令只保存配置，没有验证所有凭据或工具。用 list、get 和 /mcp 查看真实状态。
远程 URL 被当成 STDIO。 在 JSON 中，URL 条目需要明确写 "type": "http" 或文档指定的其他类型；缺少 type 的 URL 是配置错误。
本地命令参数被 Claude Code 解析。 把 Server 命令和全部参数放在 -- 后面。
项目 Server 一直等待批准。 在项目中交互式启动 Claude Code，审阅 workspace trust，再审阅 Server 条目。检查配置前不要绕过提示。
加载了错误定义。 搜索 local、project 和 user scope 是否有同名 Server。更高优先级的 local 配置可能遮住团队版本。
认证成功，但工具权限太大。 缩小上游 OAuth scope 或 Token 权限，在暂时不用时禁用 Server，并用有限账号测试。连接成功不能成为 Owner 级权限的理由。
一套安全默认配置
- 官方提供远程 endpoint 时使用 HTTP，官方提供本地命令时使用 STDIO。
- 把 SSE 当成旧 transport；Claude Code v2.1.265 及以上版本先用 HTTP，只在旧 endpoint 要求时让客户端自动回退。
- 评估新 Server 时先用 local scope。
- 团队审阅不含 secret 的
.mcp.json后，再转为 project scope。 - 只有确实应进入每个项目的个人工具才用 user scope。
- 优先 OAuth 或受保护的环境变量引用，不提交静态 Token。
- 使用只读上游权限和一次无害工具调用做首轮测试。
- 把
Added、配置状态、真实连接和工具行为当成四个独立阶段验证。 - 记录移除配置与撤销凭据的方法。
下一步怎么做
Server 正常工作后，为团队记录所有者、用途、scope、transport、凭据来源、允许工具和审阅预期。包、endpoint、认证流程或工具列表变化时，重新验证。
MCP 能增强 Claude Code，但并不表示每个项目和工作流都适合同一个 Agent harness。准备把这套配置用于托管 Workspace 时，可以打开 Agent.Space，先从一个工具和权限都容易检查的边界任务开始。