MCP 接不上:一次 declarations=0 的排查
MCP 接不上时,第一反应总是「是不是网络问题」。我那次踩到的其实是启动竞态:连接器在会话建立时还没 ready,整个会话的 MCP 配置被冻结成 0 个声明。
2026-11-03 那天,我有个每日定时任务在 21:49 启动,结果第一次执行就废了。它不是执行到一半失败,而是连第一个工具都调不到——工具表里根本没有 mcp__wind-finance__* 这一族。
当时的排查路径是这样的:先怀疑 OAuth 过期,再怀疑网络,再怀疑配置写错。全部排除之后,才在日志里找到真正的答案。这篇把整个过程和后来总结的两类 MCP 用法一起写下来。
现象:工具表里少了一整族工具
那次执行记忆里的原文是这样的:
本次未取数、未写历史库、未出图,按硬性边界停在第一步之外(连交易日判断都没做成),等补跑。 根因:WorkBuddy 21:49 刚启动,
[ConnectorMcpSnapshot] declarations=0(启动竞态),而 wind-finance 的 OAuth 续期直到 13:49:11Z 才 connection-ready;本会话 sidecar 在 13:49:07Z 就以--mcp-config(runtimeMcpCount=7)一次性拉起,配置整个会话固定。
三个关键数字:declarations=0、会话拉起时刻 13:49:07Z、连接器 ready 时刻 13:49:11Z。差 4 秒。
排查:把"已排除"的路径记下来比找到答案更有用
那次最值钱的产出不是结论,是一份"别再试这些"的清单:
| 尝试过的补救路径 | 结果 |
|---|---|
| DeferExecuteTool 直呼 | 名字不存在 |
本地代理 127.0.0.1:8625 | 只有 26 个内建工具,无目标连接器 |
探测 /<hash>/mcp | 404 |
~/.workbuddy/mcp-tool-list.json | 存在但无用 |
~/.mcporter | 未安装 |
解 connectors/<uid>/.credentials.v3.json | AES-256-GCM 加密,不要尝试解密 |
最后一条我特意抄进文章,因为它涉及安全边界:凭证是加密的,尝试解密既不合法也没必要。正确的做法是让上层重新建立连接。
定位:日志里有两行决定性的证据
真正的判断依据只有两行 grep:
# 1. 当次会话的 MCP 声明数量
grep "ConnectorMcpSnapshot" "C:/Users/admin/.workbuddy/logs/daemon.log"
# 2. 会话拉起时实际注入的 server 数量
grep "runtimeMcpCount" "C:/Users/admin/.workbuddy/logs/daemon.log"正常状态的输出长这样(我从 daemon.log 里摘的真实行):
{"timestamp":"2026-11-20T13:27:32.372Z","level":"info",
"scope":"daemon-server:connector",
"message":["[ConnectorMcpSnapshot] end marketplaceEntries=6 declarations=4 manifestMs=0 totalMs=0 slowEntries=[]"]}declarations=4 是正常的。出问题那次是 declarations=0。而另一行:
{"scope":"daemon-server:WBDomain",
"message":["[conversation-runtime] resolveMcpServers resolved",
{"sessionId":"e23de2dc-...","totalDurationMs":18,"projectMcpCount":0,
"runtimeMcpCount":13,"hasMcpConfigResolver":true,"mcpConfigJsonAttached":true}]}runtimeMcpCount=13 说明这台机器平时能挂 13 个 server。出问题那次会话只有 7 个,且不含 wind-finance。
所以排查顺序应该反过来:先看这两行,再考虑别的。 我那次绕了快一个小时才回到这两行。
处置:不修旧会话,另开一个新会话补跑
一旦确认是"会话建立时快照已冻结",就不要再在当前会话里挣扎了。因为 --mcp-config 是一次性传给 sidecar 的,会话生命周期内不会重新 resolve。
我当时建了一个一次性补跑任务,指定 connectorIds=wind-finance:
补跑 id: 63c044fa-106f-409f-9d76-3b9824e33e78
触发时间: 22:25
判断依据: 新会话会重新 resolveMcpServers,此时 wind 已 ready,大概率能注入结果成功了,当天读数正常出来:A股 48.16℃、港股 28.02℃,历史库 59/58 点。补跑记忆里第一句就是"全程 WIND(wind-finance 连接器),未换源"。
这条经验后来变成了通用规则:应用启动后 1~2 分钟内触发的自动化,财务类连接器可能拿不到。
另一类 MCP:不是连接失败,是"连上了但用错"
wind 那次是连不上。但我用的另一类 MCP 完全是另一种坑——连得上,但返回的东西不一定对。
比如同一次排查里发现的 QPS 限流:
WIND 有 QPS 限流:一条消息并行发 44 个
get_index_fundamentals,只有前 4 个成功,其余全报「每秒请求频率(QPS)超过限制」。必须串行 + 间隔 ≥1.3 秒。
还有更阴的一个:问句会被换成同名的其他指数。
801030.SI 基础化工 → 返回 882202.WI(20 年序列,maxseq 4856)
801740.SI 国防军工 → 返回 882102.WI
HSSCHKY.HI → 返回 930915.CSI
801050.SI → 返回 000819.SH(序号1/4828、分位0)这些返回都是合法 JSON、都有数据、都不报错。只是不是你问的那个东西。
两类 MCP 的坑对比下来是这样的:
| 类型 | 典型表现 | 排查入口 | 防线 |
|---|---|---|---|
| 连接型(declarations=0) | 工具名整个不存在 | ConnectorMcpSnapshot 日志 | 另开会话,别在当前会话挣扎 |
| 语义型(返回错标的) | 有数据但口径不对 | 返回值里的代码字段 | 校验返回的代码 == 请求的代码 |
第二类的防线我封装成了固定句式:问句里必须带「Wind代码XXXXXX」并加「申万一级行业指数」前缀,拿到结果先核对返回行的代码与请求一致、日期等于今天,不一致就重问。
QPS 限流的另一个应对: 新建 fund_series.py
- 串行请求(不是 Promise.all 一把梭)
- 间隔 ≥ 1.3 秒
- 命中 QPS 报错自动重试
- 断点续跑(44 只跑一半挂了不用从头来)
- 代码/序号双校验复盘
三条:
- 连接失败先看两行日志,别先怀疑网络。
declarations和runtimeMcpCount能一句话定性。 - 会话级的 MCP 配置是冻结的。启动竞态导致的缺失,在当前会话内无法补救,直接新开会话。
- 连上了不等于对了。语义型 MCP 的校验成本必须内建到流程里,不能指望它自己报错。
还有一个尚未解决的问题:我没找到办法在自动化触发前"探活"连接器。现在的做法是让自动化自己在第一步检查工具表,缺了就直接退出并记一条记忆。这能止损,但不能自愈。下一步想试试提前 2 分钟起一个空会话预热,不过那要改调度逻辑,还没动手。