基础篇
进阶篇
高频篇
精选篇
手写篇
面经篇
AI 篇
原理篇
每日一题
小程序题库
  • 知识卡片碎片时间过考点
  • 场景篇按分类整理的大前端场景考点
  • 历年面经按年份追踪真实考点
  • 算法题库NEW在线编码即时判题
  • 专项自测100 题快速查漏
  • 前端基础
    • HTTP从报文一路讲到 HTTPS
    • 浏览器渲染、事件循环、进程
    • 计算机基础Linux、网络、操作系统
  • 进阶专项
    • 设计模式23 种模式怎么用
    • 前端系统进阶学习大型项目工程化
    • 前端综合文章长期沉淀的实践文
  • 工程与工具
    • Node学习指南从环境搭建到服务端
    • NPM工作流script、依赖与发布
    • Docker容器化部署上手
    • Canvas图形与动画实战
  • 路线与导图
    • 思维导图知识点全景图
    • 学习路线按图索骥不跑偏
  • 动态
    • 公众号动态公众号历史文章
    • 博客动态站长的技术博客
    • 开发者导航常用工具与文档站
    • AI 热点每日 AI 资讯与动向
AI 工作台
旧版
AIHT
内容
精选全部 AI 动态热点榜AI 日报收藏
分类
模型行业编程产品技术观点开源
更多
Agent 接入
返回首页开发者导航
AIHT
精选 / 资讯详情
8.0
热点
AI SCORE
技术实践2026-11-20 21:57

两万多次调用归纳出 12 类 MCP 故障

dev.to · AI#MCP#故障排查#配置校验
Editor brief · 编辑速览

作者根据 21,555 次未携带凭据的初始化和工具列表探测归纳远程 MCP 故障,并按观察频率排列检查和修复办法。文章也涵盖本地配置问题,例如 JSON 语法错误或 Windows 路径转义错误导致客户端忽略配置。

文章思维导图
Knowledge map
拖拽缩放
AI deep read

AI 深度解读

MCP 服务在 Cursor 或 Claude Code 里亮红点、没有工具,或者列出了工具却调用失败,排查入口各不相同。Serverdex 作者把常见故障整理成 12 类,并用 21,555 次托管服务探测,为其中几类远程故障补上了数字。

这份清单适合按症状读。客户端完全看不到服务,先查配置有没有被读取。远程服务能连上却没有工具,先看状态码和响应内容。工具能列出却用不了,再查调用凭据、服务日志和上下文开销。

服务没出现,先确认客户端读到了配置

第一步是校验 JSON。末尾多一个逗号、两个服务条目之间少一个逗号、从聊天窗口复制了弯引号,都可能让客户端跳过配置。Windows 路径在 JSON 里也要转义,例如 C:\Users 应写成 C:\\Users。MCP 快速入门给 Claude Desktop 用户的第一步,就是检查 claude_desktop_config.json 的语法。

语法通过后,再核对文件路径、配置结构和作用域。Claude Code 和 Cursor 各有自己的读取规则,原文没有逐一列出路径。改完也要确认客户端重新加载了配置。Claude Desktop 在启动时读取配置,需要完全退出再打开。其他客户端有的保存后重载,有的提供刷新按钮。

本地服务启动失败,直接看命令、路径和日志

日志出现 spawn、ENOENT 或 command not found 时,先在终端执行配置里的原命令。桌面应用由操作系统启动,拿到的 PATH 可能和终端不同。通过 nvm 或 pyenv 装好的运行时,在终端里能用,客户端里可能找不到 npx、uvx 或 docker。可以把 which npx 的输出填进 command,也可以全局安装所需运行时。Windows 快速入门还提到,缺少 %APPDATA%\npm 时可尝试 npm install -g npm。

文件系统类服务能启动却找不到目录,就检查 args。客户端的工作目录可能和项目目录不同,传入绝对路径更稳。工具已经列出、每次调用却都报鉴权或配置错误,则检查 env,把 <your API_KEY> 之类的占位符换成实际值。Claude Code 的 --env 和服务名之间要隔一个选项,比如 --transport stdio,否则服务名会被解析成第二组 KEY=value。Windows 上若路径里的 ${APPDATA} 触发 ENOENT,可把 APPDATA 加进 env。

如果服务短暂出现后变红,直接看 stderr。Claude Desktop 的 mcp.log 和 mcp-server-NAME.log 分别可在 macOS 的 ~/Library/Logs/Claude、Windows 的 %APPDATA%\Claude\logs、Linux 的 ~/.config/Claude/logs 下找。手动运行服务还能看到它究竟卡在运行时版本、必填参数,还是端口占用。

远程服务没有工具,先看返回了什么

截至 2026 年 11 月 20 日,Serverdex 同步的官方 MCP Registry 有 41,114 条记录。团队从 11 月 17 日起大约每天探测一次托管服务,不带凭据,发送 initialize 和 tools/list。在作者公布的 21,555 次检查中,13,717 个响应正常,5,371 个返回 401 或 403,1,470 个有响应但没有返回 MCP 协议内容,668 个完全没回应。

对于 401 或 403,先查服务要求的鉴权方式。Cursor、VS Code、Cline、Windsurf、Zed 可以通过 headers 配置密钥,Codex 可以用 bearer token 环境变量。走 OAuth 时,Claude Code 可用 /mcp 或 claude mcp login,Codex 可用 codex mcp login。Zed 会对没有 Authorization 头的 URL 提示登录,Claude Desktop 则从 Connectors 进入。按作者 2026 年 11 月 19 日查阅的客户端文档,Windsurf 的 stdio 服务不支持 OAuth。

如果期待 JSON-RPC,实际却收到 HTML,先核对 URL。文档页、旧路径和只在服务所在机器上生效的 localhost 都可能被误填进去。用服务文档给出的端点,常见路径以 /mcp 结尾。端点可达但握手卡住,再核对传输方式。Cline 只配 url 时默认走旧版 SSE,使用 Streamable HTTP 要写 "type": "streamableHttp"。VS Code 区分 "type": "http" 和 "type": "sse"。Claude Code 的 .mcp.json 可写 "type": "http",CLI 对应 --transport http。按原文,从 v2.1.265 起 Claude Code 先试 HTTP 再回退,旧版本连 SSE 要显式传 --transport sse。Continue 的 YAML 则写 type: streamable-http。

工具列出来了,模型为什么还是不用

工具定义也占上下文。作者估算,在有响应的服务中,单个服务的工具定义开销中位数约为 4.8k tokens,有些服务高得多。工具定义随请求提供给模型,所以即使还没执行工具,启用的工具也会影响上下文预算。连接正常但模型变慢、常挑错工具,或者客户端提示工具过多时,可以先关掉当前项目用不到的服务。客户端支持筛选工具的话,只保留任务所需的那几个。

我的判断

我会把这份清单当成按症状查找的索引。远程探测直接记录了状态码、响应类型和超时情况,足以说明为什么远程服务没有工具时,先查鉴权和端点比反复重启客户端更有针对性。无凭据请求收到 401 或 403 后,仍需结合服务文档区分缺少凭据和权限受限。一次超时也只能说明那次探测没有收到响应,作者因此记录连续失败次数。

开头把 12 类问题按常见程度排序,但托管端探测看不到用户本机的 JSON、PATH 或配置作用域,这几项的排序属于经验之谈。原文列出的四组远程结果合计 21,226,和总数相差 329,作者没有交代差额。4.8k tokens 也是工具定义的估算值,原文没有提供不同工具数量下的延迟或调用成功率对照,适合用来估算上下文预算。

能拿来做什么

  • 在 Cursor 或 Claude Code 接入本地 Node MCP 服务时,先校验 JSON,再手动运行 command 和 args。终端能跑而客户端报 ENOENT 时,优先核对客户端的 PATH 和可执行文件绝对路径。
  • 接入远程 MCP 时,先记录状态码和响应类型。遇到 401 或 403 就查鉴权,收到 HTML 就核对端点,端点可达但握手失败再查传输设置。
  • 给日常 AI 编程项目按需启用 MCP 服务。工具已经列出却经常选错时,先停用当前任务无关的服务,再用同一个任务复测。
Original source

本文由 AI 通读原文后重新编写,观点部分为站内判断,细节以原文为准,来源 dev.to · AI,原文版权归原作者所有。

阅读原文
上一篇
修图智能体通过质检仍可能漏改
下一篇
实测 16 个 Python Agent 包的依赖开销

资讯速览

dev.to · AI · 2026-11-20 21:57

AI 评分 8.0 / 10

相关标签

#MCP#故障排查#配置校验

继续阅读

  • 给编程智能体提供 Markdown 版 API 文档
  • 修图智能体通过质检仍可能漏改
  • 实测 16 个 Python Agent 包的依赖开销
  • 给 MCP 工具加上人工审批
  • AutoClip 开源长视频剪辑,支持 CLI 与 MCP