当前位置:首页 > 编程开发 > 正文

MCP 连不上:六类症状与三层排查法实战

约 3508 字 · 预计阅读 9 分钟
一句话总结:MCP 连不上,报错几乎不给线索。按症状分成六类,每类都有固定判据:406 查 Accept 头、空回包查通知、列不出工具查初始化、返回一坨字符串查二次解析、发布变草稿查状态字段、图片传不上去查文件名。

这篇是给「已经在连、但连不通」的人写的。

如果你还没写出第一行客户端,先看四十行那个版本,回来再对症状。

排查的核心原则只有一条:一次只验证一层。从握手到工具调用,中间有三层,跳着试只会得到「不行」两个字。

症状一:406,连握手都不给

表现:请求被挡在门口,响应码 406,正文只有一句「不接受」。这层还没走通,别往下看。

判据:翻你的请求头。只声明接受 JSON 的那版代码,十个有九个停在这。

修法:把流式类型一起声明上。服务端有权用事件流回包,客户端不提前说「我能收」,它只会拒绝。

这一类错误最容易自己发现,因为它在第一层就炸了,不会牵扯到后面的逻辑。

症状二:回包是空的,但连接是通的

表现:第二个请求 HTTP 200,响应体长度 0。看着像服务端坏了,其实不是。

判据:对方法名。前缀是 notifications/ 的,本来就该回空。

修法:这类请求发完就返回。想在统一出口处解析所有响应,就会在这里撞墙。 反过来,如果方法名不是通知却回了空体,那才是问题:多半是令牌没通过认证,服务端选择不告诉你。

症状三:能列出工具,但一个都调不动

表现:tools/list 有返回,里面躺着十几个工具,调任意一个都报错。

判据:先确认握手第二步发了没有。有些服务端在没收到 notifications/initialized 之前,会拒绝执行工具。

修法:在 initialize 之后立刻补发那条通知,再干活。

还有一种情况是工具名带命名空间。列表里叫 x_list_articles,你在客户端里写成 list_articles,就会找不到。名字照抄最稳。

症状四:调用成功,但返回的是一坨字符串

表现:取 result.content[0].text 打印,满屏转义反斜杠。

判据:看首字符。左花括号开头,说明它本身就是一段 JSON 文本,只是被装进字符串里又转了一次。 修法:再解析一次。协议允许工具把结构化结果当文本塞回来,两层是约定,不是怪事。

我在发布助手那篇里提过。当时以为编码坏了,查了半小时日志。

症状五:接口说成功了,但文章进了草稿箱

表现:发布调用返回成功,文章列表里找不到,后台一看在草稿箱。 判据:看你有没有传状态字段。不传时走服务端的默认值,而默认值通常是草稿。

修法:显式传公开状态。发完立刻回读一次,确认返回里有文章 id 和正式地址,再认为成功。 这一类最坑,因为接口是「成功」的,你的流程也认为自己「成功」了,只有去前台看才发现没有。所以流程里必须有一句回读。

症状六:图片传不上去

表现:上传返回里没有媒体对象,脚本报「读不到返回内容」。 判据:看媒体库里是不是已经有同名文件。同名覆盖被拒,是很多服务端的默认行为。

修法:换一个新文件名。所以配图命名要带版本或日期,别用 cover.png 这种通用名。

这一条我踩过两次。第一次以为是编码问题,第二次才意识到是文件名冲突。

MCP 连不上:六类症状与三层排查法实战

图 1:三层挨着过,比跳层乱试快

三层验证法:把问题切小

上面六类症状,其实分布在三个层次上。把三层挨个过一遍,比乱试快得多。 第一层是传输:Accept 头、认证头、地址对不对。过了这一层,至少能拿到 initialize 的结果。

第二层是会话:初始化发完没有、通知补了没有。过了这一层,tools/list 能正常返回。

第三层是业务:参数名、状态字段、返回结构。过了这一层,工具才真正按你的意图工作。 每层都用最小请求验证,不要让上一层的错误在下一层才暴露。

两个还没有答案的疑点

第一个:令牌权限不足时,有些服务端回 401,有些回空体,有些回一个「工具不存在」。同一类问题三种表现,我没法给出统一的判据,只能建议先拿一个有完整权限的令牌试通,再收窄权限。

第二个:并发调用时 id 冲突。我用递增整数,目前没出过事,但这不算严谨。理论上服务端不该因为 id 重复而串包,实践中我没测过大并发。

这两条先记在这里,等有实测机会再补。

FAQ

Q:报 401 怎么查?

先确认令牌前缀和中文全角字符没混进去,再看服务端要求的认证方案是不是 Bearer。这两项排除完再怀疑权限。

Q:工具列表是空的,但没报错?

多半是工具集或权限过滤把工具挡掉了。换一个全权限的令牌对比一下,就能分清是配置还是权限。

Q:一定要按三层顺序吗?

建议按。跳层排查最典型的后果是把认证问题当成参数问题,然后开始乱改参数。

参考资料

  1. MCP 规范 · 2025-06-18(初始化、通知与工具调用的定义)
  2. GitHub · github-mcp-server(可对照的官方实现)

口径与核验:六类症状都是我在自己站的对接里实际遇到的,判据和修法对应真实改过的代码;三层验证法是排障时形成的顺序,不是规范要求。令牌权限不足的三种表现、并发 id 冲突这两条没有实测,已在文中标明。

目录导航
  • 症状一:406,连握手都不给
  • 症状二:回包是空的,但连接是通的
  • 症状三:能列出工具,但一个都调不动
  • 症状四:调用成功,但返回的是一坨字符串
  • 症状五:接口说成功了,但文章进了草稿箱
  • 症状六:图片传不上去
  • 三层验证法:把问题切小
  • 两个还没有答案的疑点
    • FAQ
    • 参考资料
  • 相关文章:

  • 把 AI 接进本地软件:插件、MCP、脚本怎么选
  • 在安卓手机上跑 Linux 写代码:proot 能干什么
  • 判断开源项目能不能用:六条硬指标和三个反例
  • 技术文配图:用 Python 画一张能被复核的数据图
  • 被打回八次之后:我改掉的七个 AI 味动作
  • 给 Z-Blog 接一个 AI 发布助手:从装插件到能发文
  • 40 行写一个 MCP 客户端:四个必踩的坑
  • 官方 MCP 服务 3 万星:25 个工具集白名单怎么用
  • 发表评论

    ◎欢迎参与讨论,请在这里发表您的看法、交流您的观点。