Claude Code 如何配置 MCP？

说明 Claude Code 配置 MCP 时如何区分本地 stdio 与远程 HTTP，怎样处理认证凭据、选择个人或项目作用范围，以及如何验证连接状态。

先看要点

Claude Code 配置 MCP，先看服务是本机启动的 stdio 进程，还是通过 URL 连接的远程服务：前者要配置启动命令和参数，后者要配置传输类型与 URL，必要时再处理认证。本文按这两种情况说明配置方式、凭据保护和连接验证，避免把远程地址误配成本地命令。

配置 MCP 前，先判断服务是本地运行还是远程连接

查看 MCP 服务提供方的接入说明，重点找它给出的是启动命令，还是 HTTP 地址。像 npx -y 包名、Python 脚本或本机二进制程序这样的命令，通常对应 stdio：Claude Code 在本机启动进程，通过标准输入输出与它通信。若说明提供 https:// URL，则通常是远程 HTTP 服务。不要只凭服务名称猜传输类型；如果对方明确要求 SSE 或 WebSocket，也要按其说明核对支持方式。

远程 HTTP 是官方文档推荐的云服务连接方式。SSE 已被标记为弃用；有些仅提供 SSE 的服务，当前文档说明 Claude Code 可在特定版本上先尝试 HTTP 再回退到 SSE。因此，碰到 SSE 地址时，应先核对服务商说明和本机 Claude Code 版本，不要假定所有旧版本都能自动回退。官方文档也说明，url 不能单独代替传输类型：JSON 配置中的远程条目要写明 "type": "http"（或与实际传输对应的类型），否则可能被当作 stdio 配置处理。

本地 stdio MCP 服务怎么配置？

stdio 配置至少要明确服务名称、启动命令以及服务所需的参数或环境变量。使用 CLI 添加时，-- 用来分开 Claude Code 自己的选项和 MCP 启动命令；省略它，启动命令中的参数可能被误读为 Claude Code 的选项。

claude mcp add --transport stdio --scope user myserver --env API_KEY=你的密钥 -- npx -y @example/mcp-server

上面的包名和变量名只是格式示意，应替换成服务提供方给出的实际值。--transport stdio 指定本地传输，--scope user 让服务器配置用于你的各个项目；若只想当前项目可用，可选择默认的 local 范围，或按团队协作需求使用 project 范围。注意 --env 后要提供环境变量键值，并按文档示例把它放在服务器名称之后、-- 之前。

运行前先确认启动命令对应的运行时和服务器程序在本机可用，并检查服务说明中要求的参数、工作目录和环境变量名称。若命令在终端里无法启动，先修正本机环境；若终端能启动、Claude Code 却无法连接，再核对添加命令中的参数是否完整，以及是否把服务端参数放在 -- 之后。不同 MCP 服务的依赖和启动方式不同，不能用一个示例命令代替服务方文档。

远程 HTTP MCP 的 URL 和认证凭据怎么处理？

远程服务先确认准确的 MCP URL，以及服务要求的是 OAuth 登录、固定 API Key，还是 Bearer Token 等请求头认证。HTTP 服务的基本添加形式如下：

claude mcp add --transport http --scope user my-api https://example.com/mcp

如果服务使用 OAuth，连接后可在 Claude Code 的 /mcp 界面完成身份验证。若服务要求固定请求头，CLI 支持通过 --header 提供，例如文档中的 Bearer Token 形式。不要把真实密钥放进准备提交给团队的项目配置或代码仓库。项目配置适合共享服务器地址和不敏感设置；个人凭据应通过服务支持的认证流程或本机环境变量提供。

也可以在项目根目录的 .mcp.json 中用环境变量占位，而不是把令牌原文写进文件：

{
  "mcpServers": {
    "my-api": {
      "type": "http",
      "url": "https://example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${MCP_TOKEN}"
      }
    }
  }
}

这段配置需要你在启动 Claude Code 的环境中提供 MCP_TOKEN，并核对服务实际要求的请求头名称和令牌格式。官方文档支持在 MCP 配置的 URL、请求头等位置使用环境变量扩展；如果变量没有设置，配置可能无法按预期工作。避免把令牌粘贴到共享文件、提交记录或可被他人查看的日志中。若不确定某个认证方式或字段是否受当前版本支持，应以服务提供方说明和 Claude Code 官方 MCP 文档为准。

个人配置还是项目配置，应该怎么选？

Claude Code 的 MCP 配置范围决定服务器在哪些项目加载，以及是否与团队共享。默认 local 范围只对当前项目生效、配置不与团队共享；user 范围对你的各个项目生效；project 范围通过项目根目录的 .mcp.json 与团队共享。文档说明 local 和 user 配置存放在用户主目录的 ~/.claude.json 中，project 配置则位于项目根目录。

只在个人电脑使用，或含个人凭据：优先选 local 或 user，注意不要把私密配置复制到仓库。
团队都需要同一个服务入口：可以用 project 配置共享服务器定义，但不要因此把个人访问令牌一并提交。
还不确定配置是否正确：先用个人范围验证，确认服务名、地址和认证方式，再决定是否整理为团队配置。

添加 project 范围的 MCP 后，Claude Code 可能要求审查并批准项目服务器；这是与连接状态不同的一步。不要为了绕过提示而直接信任来源不明的项目配置。改配置前先检查已有文件和条目，只编辑目标服务器，避免覆盖其他 MCP 服务设置。

配置后怎样确认连接成功？

终端中可先运行 claude mcp list 查看服务器及状态，再运行 claude mcp get <名称> 查看指定服务器详情；进入 Claude Code 后，也可以使用 /mcp 检查状态。添加命令显示成功，只能说明配置已写入，不等于服务器已经成功连接。列表中的 Connected 表示已连接；Needs authentication 提示需要认证；Failed to connect 则表示连接失败。项目服务器若显示 Pending approval，先处理工作区信任与批准，再判断是否还有连接问题。

排查时按故障类型缩小范围：stdio 服务先检查命令、参数、所需运行时和环境变量；远程服务先核对 URL、网络可达性、认证方式及令牌是否有效。若错误提示涉及请求头或认证，不要把包含密钥的完整配置直接发到公开渠道；提供给他人协助时先遮住令牌、私有主机信息等敏感内容。连接失败不一定代表配置格式错误，也可能是服务端或网络问题，应结合状态和错误详情判断。

本文配置说明依据 Claude Code 官方 MCP 文档，核查日期：2026 年 10 月 9 日。文档和版本功能可能调整；SSE 自动回退等行为尤其应对照本机版本确认。