AI Tools
教程8 分钟2026年11月13日作者:AIGCDev

Claude Code MCP 连不上或工具不可用:按状态排查

Claude Code 里的 MCP 出问题时,先确认卡在哪一层:列表里没有服务,先查配置来源和作用域;显示连接失败,查启动、网络或认证;显示 Connected 但没有工具,查工具发现和权限。 添加命令成功只说明配置已写入,Connected 也不代表后续业务操作成功。

本文面向已经有 MCP 服务、主要使用终端 CLI 的开发者,按 2026-11-13 核验的 Claude Code MCP 官方文档 整理。服务端、客户端版本及组织策略可能改变状态和入口;下文的旧版隔离实验只验证配置与失败状态,未验证模型调用、OAuth 或真实服务。

先记录状态,再选排查分支

在启动 Claude Code 的同一项目目录运行,把 server-name 换成服务名:

pwd
claude --version
claude mcp list
claude mcp get server-name

list / get 可能实际启动 stdio 服务或尝试连接远端;先确认配置和服务可信。交互会话内用 /mcp 查看服务详情、状态和工具数量。不要把命令输出、配置文件或日志原样公开:URL、参数、环境变量和报错可能包含凭据或内部地址。当前文档列出 Connected、Needs authentication、Failed to connect 等状态,也区分待审批、禁用和策略阻止;版本不同可能显示不同。官方状态说明

观察 下一步 能说明什么
服务缺席,或 get 找不到 核对当前目录、配置来源、作用域、审批与策略 还不能推断服务端故障
Needs authentication / Failed to connect 根据传输方式查认证、进程或网络 配置已发现,但尚未建立可用连接
Connected,但 /mcp 无预期工具 查工具数量、发现机制、权限及服务端暴露情况 连接状态不等于工具已可供模型使用
工具可见但调用失败 记录具体工具错误、授权范围和服务端响应 连接与发现通过,业务请求仍可能失败

服务不在列表:先找配置从哪里来

  1. 确认目录和作用域。 官方文档中 local 是默认作用域,只在添加时的项目可用;project 存放在项目根目录的 .mcp.json;user 跨项目可用。同名配置按 local、project、user 的顺序优先,整个条目取高优先级版本,不合并字段。查看当前项目中预期的条目和作用域,不要为了排查整体删除配置。作用域和优先级
  2. 检查配置解析和启动环境。 对照官方格式核对 mcpServers JSON 结构及传输类型;含 URL 的远程条目需要正确的 type。查看 list 的配置警告,并确认启动 Claude Code 的环境提供所需变量,不要打印真实值。官方说明 .mcp.json 中未设置且无默认值的 ${VAR} 通常会警告并保留未展开文本;远程 URL 和 headers 中部分凭据变量读取为空是例外。配置警告、变量展开
  3. 检查项目审批和禁用状态。 可信项目的 .mcp.json 服务器可能需要在交互式 claude 会话中检查并批准。确认命令和来源可信后再接受;/mcp 也可查看是否被禁用。组织托管策略可能阻止或隐藏服务,应向管理员核对,不要自行绕过。项目审批、托管配置
  4. 确认实际入口。 手动配置、插件和 claude.ai 连接器不是同一来源。插件服务检查 /plugin 和 /mcp;通过 claude.ai 添加的连接器检查账号连接状态与 /mcp。如果当前认证方式是 API key 或第三方提供方,官方说明不会加载 claude.ai 连接器;可用 /status 检查当前认证方式。终端、VS Code 和 JetBrains 会话的连接器由 Claude Code 获取,桌面应用的本地和 SSH 会话由应用提供,排查入口不同。连接器条件

**一次本地隔离实验:**2026-11-13,我们在 macOS 的 Claude Code 2.1.87 中,用空 HOME、隔离配置目录和两个临时工作目录,添加一个 local scope 服务,命令指向不存在的程序。add 显示 Added,同目录 get 和 list 显示 Failed to connect;另一个目录的 list 显示没有配置服务。每步运行一次,没有登录、调用模型或连接外部服务。这个观察只支持该版本、该合成输入下的配置与连接状态,不能证明新版 UI 或真实服务行为。

已发现但连接失败:按传输方式缩小范围

  • stdio 本地进程:在 get 中核对可执行文件和参数是否与服务自己的启动说明一致;另行核对实际启动目录和所需环境变量;确认程序存在且当前用户有执行权限。检查服务日志时避免输出密钥。项目配置中的相对路径尤其需要与启动目录对齐;也检查服务是否在启动后立即退出。
  • HTTP / SSE 远程服务:核对服务商提供的 MCP 端点、网络或代理可达性,以及返回的状态码。需要认证时,在 /mcp 中选择该服务并按提示完成授权;授权失败要检查账号和服务商的权限范围。不要把 bearer token 放到文章、工单或仓库中。远程认证
  • 审批、禁用或策略状态:它们并非网络故障。先处理对应状态,企业策略由管理员确认。当前文档也说明 HTTP/SSE 首次临时连接失败会重试,stdio 首次失败不使用同一重试机制;详情和重连方式以所用版本的 /mcp 和官方重连说明为准。

历史报告可帮助确定对照项,不能证明当前版本有同一缺陷:2026-01-02 的 issue #16107 中,报告者称 Linux 上项目级服务器在 2.0.71 起连接失败,而手动协议初始化有响应。报告者随后发现是 Laravel Boost 的协议版本不匹配,并称升级服务端后解决。这提示同时核对客户端与服务端版本,不能仅凭握手现象认定客户端缺陷或套用旧降级建议。

已连接但工具不可用:检查发现、权限和调用

先在当前会话打开 /mcp,选择服务查看工具数量和名称。当前官方文档会标出声明支持工具但未暴露工具的服务器;远程服务也可能显示 cached 和上次发现的工具数,表示工具列表来自缓存,首次使用时才连接。缓存功能需 2.1.221 或更高版本且受配置或 rollout 影响,不能把缓存数字当作本次实时调用成功。工具可用性、状态详情

如果数量为零或缺少目标工具,按顺序核对:

  1. 服务端是否确实向该账号和连接暴露预期工具;对照服务端文档或由维护者检查工具列表。服务能够完成握手,不保证它返回了预期工具。
  2. /mcp 的服务来源、禁用状态和当前会话权限规则;团队环境还要核对组织的连接器工具控制。云会话中的部分可用数量还可能受 deny 规则、工具名长度或服务端工具可见性影响。官方工具可用性说明
  3. 工具搜索可能延迟加载工具定义,未在最初上下文中看到完整定义不等于工具不存在;服务尚在连接时,也可能出现 No such tool available。等待连接结束,再按工具名称检查。工具搜索
  4. 若服务和工具可见,选择一个你有权使用、明确只读的具体工具和无敏感测试对象,请 Claude 调用并查看实际工具结果。例如让它读取你有权访问的测试记录,确认返回对象与预期一致;没有合适的只读工具时,到工具发现为止,不为验证而执行写操作。仅凭模型声称已调用不算成功,要看工具调用和响应。

2026-08-20 的 issue #88392 报告过非交互会话偶发连接成功却无工具,而另一 MCP 客户端当时能列出工具;报告者后来称升级到 2.1.239 后解决。2026-04-16 的 issue #49019 则是报告者的插件服务显示 Connected,但工具未进入会话。它们是不同环境下的用户报告,不证明你的故障有相同原因;对照客户端时也要使用相同身份、服务端和权限。

账号连接器缺席时

如果手动 MCP 服务正常,claude.ai 连接器却不出现在 /mcp,先检查 /status 的实际认证方式、claude.ai 的连接器授权,以及组织是否允许该连接器。必要时检查 /mcp 中未使用连接器的折叠列表和重复端点提示。官方说明部分 Anthropic 托管连接器不支持从 Claude Code 本地 OAuth,应在 claude.ai 的连接器页面完成连接。官方连接器说明

例如 issue #77588 于 2026-07-14 报告其 macOS CLI 中账号连接器未初始化,而手动配置服务正常;报告者还观察到显示版本与实际运行版本不一致。这是该用户的历史现象,遇到类似症状应记录实际入口、版本和认证方式,再查当前文档或向管理员及维护者提供脱敏信息。

如果问题是项目指令没有被加载,而非 MCP 服务或工具不可用,可另看 Claude Code 的 CLAUDE.md 加载排查。

排查仍无结果时,提供最小复现:客户端版本和运行入口、操作系统、服务来源及传输方式、当前目录与作用域、状态和脱敏错误、预期工具及是否在其他客户端可见。去掉 token、cookie、内部 URL 和业务数据;保留足以区分连接失败与工具发现失败的信息。

claude-codemcptroubleshooting