MCP 认证

版本要求与措辞以官方为准。

OAuth 认证

许多云端 MCP 服务器需要认证，Claude Code 支持 OAuth 2.0。服务器以 401 Unauthorized 或 403 Forbidden 响应时，Claude Code 把远程服务器标为需要认证，具体表现取决于服务器：对你还没登录的服务器，两个状态码都会在 /mcp 里标出让你走 OAuth 流程；对 claude.ai 连接器，由 claude.ai 拒绝你会话令牌引起的 401 不会标记连接器（重新授权连接器修不了你的登录），而是显示会话令牌被拒绝的状态；对你自己配置了 Authorization 头（在 headers 里或经 headersHelper）的服务器，连接时的 401/403 不标记服务器而是报告连接失败（因为要修的是你配置的凭证）；对投递到云会话的连接器，Claude Code 不运行登录流程（会话代理用你在 claude.ai 里授予的授权认证），需要重新授权时到 claude.ai/customize/connectors 重新连接。对你已登录的 OAuth 服务器，请求返回 401 时 Claude Code 刷新存储的令牌、重连并重试请求一次，只有重试也失败才在 /mcp 里标记；服务器拒绝存储的刷新令牌时，Claude Code 立即显示指向 /mcp 的提示，在下次工具调用失败之前选 Re-authenticate 重新登录。返回指向授权服务器的 WWW-Authenticate 头的自定义服务器同样得到自动发现。有服务器需要认证时启动会有一条通知（v2.1.193+，只计入你能从 Claude Code 登录的服务器；每个服务器只通知一次）。非交互模式没有 /mcp 面板，无法替你跑 OAuth 流程；自 v2.1.196 起，启用工具搜索（默认）的 claude -p 或 SDK 运行里，配置的服务器需要认证时 Claude Code 会告诉 Claude 该服务器的工具不可用。你配置的 headers.Authorization 被服务器拒绝时，Claude Code 报告连接失败而不是回退到 OAuth——检查令牌对该 MCP 端点是否有效，或去掉该头改用 OAuth。

用法：先 claude mcp add --transport http sentry https://mcp.sentry.dev/mcp（已用同名同范围添加过会报 MCP server sentry already exists in local config），然后在 Claude Code 里用 /mcp 并按浏览器步骤登录。提示：令牌被安全存储并自动刷新；用 /mcp 菜单里的 Clear authentication 撤销访问；浏览器没自动打开就复制提供的 URL 手动打开；认证后浏览器重定向因连接错误失败时，把浏览器地址栏里的完整回调 URL 粘贴到 Claude Code 弹出的 URL 提示里；OAuth 适用于 HTTP 服务器。

命令行认证：claude mcp login <名称> 直接在 shell 里运行服务器的 OAuth 流程，无需在会话里打开 /mcp；claude mcp logout <名称> 清除存储的凭证。检测到没有本地浏览器（SSH 会话、没有显示服务器的 Linux）时，它打印授权 URL 而不是尝试打开浏览器，你在本机打开 URL 后把完整的重定向 URL 粘贴回来。

固定 OAuth 回调端口：有些服务器要求预先注册特定的重定向 URI。默认 Claude Code 随机选一个可用端口作回调；用 --callback-port 固定端口以匹配预先注册的 http://localhost:PORT/callback 形式的重定向 URI（可单独使用配合动态客户端注册，也可与 --client-id 一起配合预配置凭证）。预配置 OAuth 凭证：有些服务器不支持动态客户端注册，出现「Incompatible auth server: does not support dynamic client registration」之类错误时，服务器需要预配置凭证（Claude Code 也支持使用 Client ID Metadata Document 的服务器）。步骤：在服务器的开发者门户创建应用，记下客户端 ID 与密钥；注册表单要求重定向 URI 时选一个可用端口并填 http://localhost:PORT/callback（v2.1.229 曾误发 127.0.0.1 形式，导致精确匹配注册 URI 的服务器以重定向 URI 不匹配拒绝登录，v2.1.231 恢复为 localhost）；然后添加服务器——claude mcp add 用标志（--client-id 传客户端 ID，--client-secret 以掩码输入提示密钥，--callback-port），claude mcp add-json 则在 JSON 里放 oauth 对象并把 --client-secret 作为单独标志（只想固定端口让 Claude Code 自动注册客户端，就单独设 callbackPort；也可用环境变量 MCP_CLIENT_SECRET 跳过交互提示）；最后在 Claude Code 里 /mcp 并按浏览器登录。提示：客户端密钥安全存储在系统钥匙串（macOS）或凭证文件里，不在配置里；密钥只能在添加服务器时设置，之后 claude mcp login 或 /mcp 认证时使用已存的密钥，不再提示也不读 MCP_CLIENT_SECRET；之后要加或改密钥，先 claude mcp remove <名称> 再用 --client-secret 和同样的 --scope 重新添加；公共 OAuth 客户端没有密钥就只用 --client-id；这些标志只适用于 HTTP 和 SSE 传输；用 claude mcp get <名称> 验证 OAuth 凭证已配置。

覆盖 OAuth 元数据发现：在服务器标准端点出错、或想让发现经过内部代理时，在 .mcp.json 服务器配置的 oauth 对象里设置 authServerMetadataUrl 指向特定授权服务器元数据 URL，绕过默认发现链（默认先检查 RFC 9728 受保护资源元数据等）；URL 必须用 https://，其 scopes_supported 覆盖上游服务器通告的 scope。限制 OAuth scope：用 oauth.scopes（单个空格分隔的字符串）固定登录流程请求的 scope——当上游授权服务器通告的 scope 超过你愿意授予的，这是把 MCP 服务器限制在安全团队批准子集的受支持办法；它优先于 authServerMetadataUrl 和服务器在 /.well-known 发现的 scope；不设则由 MCP 服务器决定请求的 scope（自 v2.1.196 起，未设置 oauth.scopes 时 Claude Code 请求服务器 WWW-Authenticate 头或受保护资源元数据提供的 scope，两者都没有就不发送 scope 参数，不再请求自动发现的完整 scopes_supported 目录）；授权服务器在 scopes_supported 里通告 offline_access 时，Claude Code 把它附加到固定的 scope 上让访问令牌无需新的浏览器登录即可刷新；服务器之后对某次工具调用返回 403 insufficient_scope 时，调用以点名所需 scope 的 needs additional permissions 消息失败，服务器在 /mcp 里显示为需要认证——该 scope 不在你固定的 oauth.scopes 里就加上，再 /mcp 重新认证（Claude Code 请求的是固定的 scope 而不是服务器点名的那个，不加就重新认证拿到的令牌仍缺它）。

用 headersHelper 做自定义认证

服务器使用 OAuth 之外的认证方案（Kerberos、短期令牌、内部 SSO）时，用 headersHelper 在连接时生成请求头：Claude Code 运行该命令并把输出合并进连接头；命令可以是脚本路径或内联。要求：命令必须向 stdout 写一个字符串键值的 JSON 对象；Claude Code 在 shell 里运行它并在 10 秒后放弃；工作目录取决于你在哪里配置了服务器，所以脚本要给绝对路径或放在 PATH 上；动态头覆盖同名的静态 headers。每次连接（会话开始和重连）都重新运行 helper（受项目与本地范围服务器的信任规则约束），不缓存结果，令牌复用由你的脚本负责。工具调用返回 401/403 时 Claude Code 在同一规则下重新运行 helper、用新头重连并重试一次，重试也失败才在 /mcp 标为需要认证；helper 输出含 Authorization 头时，Claude Code 用它作为服务器的认证而不回退到 OAuth；服务器在连接时拒绝 helper 的凭证则报告连接失败而不是需要认证，修好 helper 返回的凭证后从 /mcp 重连会再次运行 helper。运行 helper 时 Claude Code 设置环境变量 CLAUDE_CODE_MCP_SERVER_NAME、CLAUDE_CODE_MCP_SERVER_URL，以及仅由插件提供服务器时的 CLAUDE_PLUGIN_ROOT，方便写一个服务多个 MCP 服务器的 helper；插件提供的 headersHelper 不能引用插件的 ${user_config.*} 值（命令经 shell 运行，Claude Code 会报告服务器配置错误而不替换），把 ${user_config.KEY} 放在服务器的 headers 字段里。

helper 在哪里运行（工作目录）：插件里配置的——插件根目录；项目 .mcp.json 或 local 范围服务器——声明它的项目目录；项目里的智能体文件、SDK 的 mcpServers 选项或 setMcpServers()、--mcp-config——会话的主工作目录；用户范围、托管 MCP、claude.ai 连接器、项目之外的智能体文件（含 --add-dir 目录里的）——你的配置目录（~/.claude，除非设了 CLAUDE_CONFIG_DIR）。helper 能读哪些环境变量：由仓库或插件提供的 headersHelper 是你没写过的命令，所以 Claude Code 运行它时去掉你环境里的凭证变量（如 ANTHROPIC_API_KEY）——适用于项目 .mcp.json 或插件里的服务器，以及来自你项目或 --add-dir 目录的智能体文件里的内联服务器；不适用于用户或 local 范围、托管 MCP、claude.ai 连接器、SDK 或 --mcp-config 提供的，以及来自 ~/.claude/agents/、托管设置或 --agents 的智能体文件里的内联服务器。除 Git 的 GIT_CONFIG_KEY_ 变量外，名字看起来像凭证的变量（含 TOKEN、SECRET、PASSWORD、KEY、AUTH，不分大小写）都会被去掉；此时让脚本从文件或凭证存储读取凭证，若服务器 url 带着这类变量的真实值，helper 收到的 CLAUDE_CODE_MCP_SERVER_URL 里那部分会被替换成 REDACTED 之类的占位。运行 helper 之前先信任文件夹：helper 是任意 shell 命令，对项目 .mcp.json 或 local 范围的服务器，只有你接受了声明该服务器的项目目录的信任对话框之后才运行；不算数的信任：父文件夹的信任，以及 claude -p 或 SDK 会话对设置文件里 Hook 获得的自动信任；信任之前 Claude Code 只用静态 headers 连接服务器，在 claude -p/SDK 会话里还会为每个服务器向 stderr 打印一行 headersHelper not run，告诉你怎样授予信任；不用对话框授予信任的办法：在 ~/.claude.json 里把 projects["<文件夹>"].hasTrustDialogAccepted 设为 true。项目内联在智能体文件里的服务器按该智能体文件来源（你的项目、.claude/agents/、--add-dir 目录）适用同一规则，信任之前根本不加载。

使用 claude.ai 的连接器

用 claude.ai 账号登录 Claude Code 时，你在 claude.ai 里添加的 MCP 服务器（称为连接器）会自动出现在 Claude Code 里：在 claude.ai/customize/connectors 添加服务器（Team 和 Enterprise 方案里只有管理员能添加），在 claude.ai 完成所需认证，然后在 Claude Code 里用 /mcp 查看，来自 claude.ai 的服务器带来源标记。Anthropic 也自己提供一些连接器（如可用 Claude Docs 的账号上 /mcp 会列出 claude.ai Claude Docs，你要求写给别人看的文档时 Claude 会用它；想关闭就在 deniedMcpServers 里加对应的 serverName）；组织在 claude.ai 里管理其认证的连接器在 /mcp 和 /plugin 里标为 managed（不改变 Claude Code 连接它的方式或你组织的工具控制）；从未登录过的连接器折叠在 claude.ai 部分末尾的 Show unused connectors 行后面。只有当前认证方式是 claude.ai 订阅登录时才拉取连接器；即使之前运行过 /login，下列情况也不加载：ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN 或 apiKeyHelper 在生效；Bedrock、Agent Platform 等第三方服务商在生效；ANTHROPIC_PROFILE、联合变量或活跃的 Anthropic profile 提供凭证；CLAUDE_CODE_OAUTH_TOKEN 持有来自 claude setup-token 的令牌（它只能发模型请求）。/mcp 没列出你添加的连接器时，运行 /status 确认当前认证方式，取消设置那个环境变量、移除 apiKeyHelper 或关掉 profile，再 /login 选 claude.ai 账号。会话启动时临时网络问题使连接器列表没加载出来，Claude Code 在后台重试最多三次；仍没出现就重启。/mcp 把连接器显示为 session token rejected 说明 claude.ai 拒绝了你 Claude Code 登录的令牌：运行 /login 重新登录，再从 /mcp 重连连接器。你在 Claude Code 里添加的服务器优先于指向同一 URL 的 claude.ai 连接器（/mcp 会把连接器标为隐藏并说明如何移除重复项）；Microsoft 365、Gmail、Google Calendar 等 Anthropic 托管的连接器不支持来自 Claude Code 的本地 OAuth（上游身份提供方只接受 claude.ai 注册的重定向 URL），所以用 claude mcp add 或 .mcp.json 指向它们的条目要移除（claude mcp remove <名称>），然后在 claude.ai 里连接服务，连接器就会自动出现在 Claude Code 里。

连接器如何到达 Claude Code：终端、VS Code、JetBrains 和 Agent SDK 会话——Claude Code 自己从 claude.ai 拉取，受本节设置和托管 MCP 配置管控；云会话——由云主机传入，受你的 claude.ai 组织设置，加上到达会话的允许/拒绝列表设置和运行它的主机上的 managed-mcp.json 管控（会话代理会改写每个连接器的 URL，所以按连接器自身 URL 写的 serverUrl 模式匹配不上）；桌面应用的本地和 SSH 会话——桌面应用以进程内 type: "sdk" 服务器的方式投递，任何 MCP 设置或 managed-mcp.json 都影响不到它们（用户通过在 claude.ai 断开连接器把它挡在自己的会话之外，组织则通过连接器工具控制里的 blocked 条目）。disableClaudeAiConnectors、ENABLE_CLAUDEAI_MCP_SERVERS、allowAllClaudeAiMcps 只作用于 Claude Code 自己拉取的连接器。组织对连接器工具的控制：Claude Code 在启动时读取并在本地强制执行（桌面应用本地和 SSH 会话除外）：设为 ask 的工具每次调用都会提示，原因为 Your organization requires approval for this tool，即使在 acceptEdits、auto、bypassPermissions 模式下也出现，且从不提供「记住选择」，匹配它的 allow 规则也不跳过；设为 blocked 的工具在 Claude 看到之前就被过滤，不出现在 Claude 的工具列表里（Claude Code 自己拉取连接器的会话里 /mcp 工具列表仍显示它并标为 disabled by your organization）；桌面应用和 claude.ai 聊天应用同样应用 blocked，桌面应用跳过所有工具都被屏蔽的连接器。关闭连接器：在任何设置范围里把 disableClaudeAiConnectors 设为 true（任一来源为真即生效：检入仓库的项目 .claude/settings.json 可以让某仓库退出 Claude Code 自己拉取的连接器，但项目级的 false 无法重新启用用户级或策略级 true 关掉的连接器）；或把 ENABLE_CLAUDEAI_MCP_SERVERS 设为 false（对当前 shell 会话同效）；只想屏蔽个别连接器，就按名称或 URL 模式加进 deniedMcpServers（如 serverName 为 "claude.ai Slack" 屏蔽 Slack 连接器），或用 /mcp 为当前会话开关任一连接器。

把 Claude Code 当作 MCP 服务器

可以让 Claude Code 自己作为 MCP 服务器供其他应用连接：运行 claude mcp serve。命令启动时不打印任何东西（stdio MCP 服务器通过 stdin 和 stdout 通信，所以终端静默阻塞说明服务器在运行、等待客户端连接）。在 Claude Desktop 里使用时，把它加到 claude_desktop_config.json：command 字段必须指向 Claude Code 可执行文件，claude 不在系统 PATH 里时要写完整路径（which claude 查找），否则会出现 spawn claude ENOENT 之类的错误。提示：在 Claude Desktop 里可以让 Claude 读目录里的文件、做编辑等；这个 MCP 服务器只把 Claude Code 的工具暴露给你的 MCP 客户端，对各个工具调用的用户确认要由你自己的客户端实现。