连不上先打 healthz：一条命令的分诊逻辑

Claude Code、Cursor 接 MCP 的教程满天飞但评论区翻车率最高的永远是同一类问题工具列表里没有察元、一调用就报 WPS_AGENT_OFFLINE、Agent 干脆说连不上服务。这些问题十有八九不用重装、不用改代码卡住的真正原因是排错没有章法东试一下西点一下越弄越乱。这篇给一套我自己沉淀的分诊流程核心就一句话连不上先打 healthz。适合所有刚把察元AI文档助手接进智能体的同学照着走。上周团队就遇到一例同事兴冲冲装好环境第二天说工具全没了报的就是 WPS_AGENT_OFFLINE最后发现只是 WPS 没开——要么手动打开 WPS要么让 Agent 调 wps_launch 冷启动这种问题重装一百遍也解决不了只能靠分诊逻辑。为什么第一步永远是 healthz排错最忌讳全线撒网。healthz 是察元本机 MCP 服务的健康检查端点一条命令就能把故障一刀切成两半服务侧问题和客户端侧问题。curlhttp://127.0.0.1:62588/healthz返回 online说明本机服务活着问题出在智能体那边的注册或配置连不上或者不返回 online说明服务本身没起来先修服务。两半的处理路径完全不同先分诊再动手五秒钟省两小时。第零步确认安装没欠账分诊的前提是东西装对了。察元的一行安装脚本自带四步体检加载项落位、健康检查、initialize 握手、桥接工具验证一路绿灯才算装完。如果你当时跳过了体检或者用了别的路子装先把这四步补着过一遍——很多连不上其实是安装阶段欠的账。底账也交代一下加载项随 WPS 自启MCP 服务是单文件常驻不依赖 Node.js 环境明白这些排错时就不会往是不是要装 Node上绕路。分支一返回 online查客户端注册服务在线但工具不出现九成是注册问题。Claude Code 直接重跑注册命令claude mcpadd--transporthttp chayuan-wps-mcp http://127.0.0.1:62588/mcp然后重开会话再看工具列表。Codex 用户检查 ~/.codex/config.toml 里的 url 字段Cursor 用户检查项目里的 .cursor/mcp.json最常见的低级错误是地址抄错一位数字。还不放心用 MCP Inspector 做独立验证npx modelcontextprotocol/inspector选 Streamable HTTP 类型填 http://127.0.0.1:62588/mcp点 Connect。工具列表能拉出来链路就是通的问题必然在客户端配置回去逐字核对你的配置文件。分支二连不上先把服务拉起来服务不在线先重启 WPS——加载项随 WPS 启动并把本机服务带起来4.1.2 版本对 sidecar 做了隐藏启动和掉线自愈多数情况重开 WPS 就恢复。如果服务已经 online 但工具调用报 WPS_AGENT_OFFLINE注意这个码的含义是 WPS 或加载项没连上 sidecar处理办法还是同一个重开 WPS让加载项、sidecar、服务三者重新握手。顺带说一句服务的底细它在三个平台分别注册到开机自启体系里Windows 是注册表运行键macOS 是 LaunchAgentLinux 是 systemd 用户服务正常情况开机即起4.1.2 之后 sidecar 隐藏启动、掉线自愈比早期版本稳了不少。第三步链路通了按错误码对症下药链路通了但具体调用失败看返回的错误码逐个对号DOCUMENT_TOO_LARGE 是文档超过约 80k 文本阈值改用 chunks 分块读取或者加 force:trueLOCATE_MISMATCH、LOCATE_NOT_FOUND 是锚点校验失败或未找到让 Agent 重新定位原文再操作MODEL_NOT_CONFIGURED 是还没配置校对模型先把模型端点配好LICENSE_REQUIRED 是免费额度用尽这个码不会弹购买窗看到它别以为程序死了CONFIRMATION_REQUIRED 则根本不算错误是写操作在等你传 confirmed:true属于设计如此确认后重发即可。错误码分诊的价值在于把一句不行翻译成为什么不行没有错误码的排错是玄学有错误码的排错是查表。建议把这张对照表贴进团队 wiki新人接手 MCP 环境先读它能省掉一半求助消息。三条心法收尾一只监听 127.0.0.1 是刻意设计本机即信任边界所以不存在 Token 配错这类问题别在找密钥上浪费时间。二远程访问场景需要代理或者用 CHAYUAN_MCP_PORT 调整端口那是另一个专题下一篇细说。三重装永远是最后一个选项绝大多数连不上停在 healthz 这一步就能定位。四排错要留痕healthz 的返回原文、错误码、当时的操作随手贴进工单或群消息下一个人接手时不必从零复现你自己复盘时也有据可依。排错和看病一个道理先验血再拍片——healthz 就是那次验血别一上来就推手术室。