MCP 常见问题与排障

登录成功却 401、查不到项目、数据为空、超时或 429、时间对不上——按现象对照处理。

下面按"现象 → 原因 → 怎么办"整理。

一直 401（最常见）

最常见原因：scope 缺少 profile

登录流程正常、令牌也拿到了，但调用接口一直返回 401，且没有任何错误码提示。最常见的原因是申请令牌时 scope 漏了 profile：服务端需要令牌中的用户名（preferred_username）来识别账号，而该字段属于 profile scope。把 scope 补成 openid profile pg-mcp-audience 后重新登录即可。

按顺序自查：

令牌的 scope 是否包含 `profile`（脚本/自研客户端最常见的坑）；
账号是否已开通 MCP 数据权限（没开通时同样表现为查不到数据或 401）；
客户端是否真的把令牌带上了（请求头应为 Authorization: Bearer <token>）；
令牌是否已过期（15 分钟；客户端应自动续期，脚本需自行刷新）；
服务地址是否写全（https://dev.thuwater.com/mcp/data，不要漏掉 /data）。

如果以上都正常仍然 401，请把发起时间和客户端名称告知管理员，服务端可按时间点排查认证日志。

客户端没有弹出登录页

先在浏览器里打开 SSO 页面完成一次登录，再回到客户端重试；
确认客户端支持 Streamable HTTP 与 OAuth 自动发现（部分客户端需要手动开启远程 MCP 支持）；
公司网络若限制外网访问，请确认能访问 dev.thuwater.com 与 sso.thuwater.com。

登录成功但查不到任何项目 / 数据为空

现象	可能原因	怎么办
"没有可读项目"	账号未开通，或未授权任何项目	联系管理员开通权限并分配项目
只看到部分项目	授权范围就只有这些	如需更多项目，向管理员申请
点位/设备有，但没有最新数据	设备离线、数据陈旧或尚未上报	看项目总览的"新鲜/陈旧/无快照"统计；陈旧阈值默认 24 小时
某个时间段查不到数据	该时段设备未采集，或该窗口与设备安装期没有交集	换时间段；确认该设备当时是否安装在该点位
以前有数据、迁移后查不到	设备迁装后历史数据按"当时的点位"保存	按历史时间段查询，服务会自动关联迁装记录

查询慢、超时或 429

缩小范围：单次时间窗口越长、指标越多，耗时越长；建议不超过 7 天（服务端也会拒绝更长窗口）；
先取最新值：只想看现状时，问"最新数据"比拉一整天时序快得多；
429：触发了调用频率/并发限制，等待几秒后重试，或减少并发调用；
超时：跨大量点位或设备做汇总时，拆成按项目/按设备分别提问。

时间对不上

服务统一按 Asia/Shanghai（+08:00） 解释和返回时间。如果你在客户端里用 UTC 描述时间（例如"07:00Z"），助手会换算；直接用北京时间描述最不容易出错。返回里的 asOf 是服务端的当前时间戳，可用于核对。

怎么申请账号 / 服务账号

个人使用：用现有 THWater 账号登录即可，但需要管理员为你在 MCP 侧开通数据权限并分配项目；
脚本/系统对接：请向管理员申请服务账号（client_id/secret），不要使用个人密码；
MCP 的账号与"HTTP 数据接口"的账号是相互独立的两套权限，开通了接口不等于开通了 MCP，反之亦然。

能用它改数据吗

不能。MCP 数据服务是只读的，只提供查询能力，任何写入、控制指令都不在服务范围内（设备控制请使用控制接口文档）。

需要更细的技术信息

能力清单服务端实际提供的 20 个能力与参数接入指南scope、令牌与客户端配置