安全、鉴权与故障排查
35-MCP 指南 · 2026-10-12 · 2.5 KB
面向使用的一篇：讲清"能用/不能用"的边界、连上后调不动的三种原因，以及一张对号入座的故障表。
快照 2026-10-12；界面细节以你应用里的设置为准 ✓
一、安全边界（先记住这四条）
- 只在本机：MCP 服务只监听本机回环地址 ⇒ 同一台电脑上的应用才能连它。
产品不提供公网 / 内网穿透 / 远程接入 ⇒ ⛔ 请不要用隧道、端口转发等方式把它暴露出去（不安全，且不受支持）。
- Token 等同完全权限：拿到 token 的应用能操作你的画布 ⇒ ⛔ 别贴进聊天、工单、截图、代码仓库。
- 不用就关：设置 → MCP Agent 关掉「启用 MCP 服务」⇒ 端口不再对外提供服务（最稳妥）。
- 换人/换环境就重置：把电脑借给别人、怀疑泄露 ⇒ 点「重新生成」，再更新所有客户端。
二、鉴权：连上之后的三道门
第三方应用"能连上"不代表"能干活" —— 依次要过三道门：
| 门 | 什么情况下会被挡 | 表现 | 用户怎么处理 |
|---|---|---|---|
| ① 鉴权 Token | 客户端没填 token、填的是旧 token（被"重新生成"过） | 401 | 设置 → MCP Agent：显示并复制当前 token，更新客户端 |
| ② 账号授权 | 未激活 / 已过期 / 换机后未重新激活 | 403（调用被拒） | 设置 → 授权与激活（应用内帮助「授权与激活」有指引） |
| ③ API 节点开关 | 设置 → MCP Agent 里「允许 Agent 调用 API 节点」被关闭 | AI 不能运行云端 API 节点（其它节点正常） | 打开该开关；或让 AI 申请一次会话级放行（会弹桌面确认框，你点同意即可） |
另外两个"看不见的门"（用起来的常见困惑）：
- 画布「AI 编辑授权」：没在画布顶栏打开它 ⇒ AI 能列工具、但改不了这张画布 ⇒ 打开即可 ✓
- 模板被关 / 缺 Key：被用户在"模板管理"里关掉的模板不可用；云端模型还需正确的 Key 配置（应用会给出提示）
Token 的几条常识
- 产品是单一全局 Token：所有第三方应用共用；没有"每个客户端一个 token"
- 不会自动过期；只有你点「重新生成」才变 ⇒ 变了之后所有已挂载的客户端都要更新（否则 401）
- Token 由应用自身保存，你在设置 → MCP Agent 里查看 / 复制 / 重置即可（不需要手工改任何文件 ✓）
三、故障速查表（对号入座）
| 现象 | 最可能的原因 | 怎么确认 | 怎么修 |
|---|---|---|---|
| 客户端连不上 / 超时 | 应用没开；服务没启用；端口改了没重启；端点填错 | 浏览器打开 http://127.0.0.1:<端口>/health | 开着应用；设置页启用服务；改端口后重启应用；核对端点 |
| 401 | token 缺失 / 旧 / 被重置过 | 客户端配置里的 token 与设置页是否一致 | 复制当前 token 更新客户端 |
| 403 | 账号未激活 / 过期 / 换机未激活 | 应用内授权状态 | 设置 → 授权与激活 |
| 工具能列，但画布改不动 | 画布「AI 编辑授权」没开 | 画布顶栏按钮状态 | 打开「AI 编辑授权」 |
| 云端 API 节点跑不了，其它能跑 | 「允许 Agent 调用 API 节点」被关 | 设置 → MCP Agent 该开关 | 打开它（或让 AI 申请会话级放行） |
| 客户端看不到工具 | 客户端只在启动时读配置 | 客户端 MCP 列表是否为空 | 重启客户端（或重载 MCP） |
| 工具名报"不存在" | 用了旧名 | 用帮助弹框「MCP 接口手册」现查 | 换成现役名（旧名一般有别名兜底） |
| 模板创建不出来 | 该模板被"模板管理"里关掉了 | 让 AI 现查模板清单（含启用状态） | 换模板，或到模板管理里开启 |
| 本地引擎任务失败 | ComfyUI 等本地引擎没启动 | 让 AI 查一次引擎健康（uc_do_health） | 启动引擎后只重跑那一步 |
| 任务一直排队 | 有别的任务在跑 / 上游没完成 | 让 AI 列一下运行中任务 | 等，或先跑上游，或取消无关任务 |
| 换台机器连不上 | 设计如此（仅本机） | —— | 不支持跨机：第三方应用请与 UnlimitCanvas 同机 |
四、排错三条纪律（省时间）
- 先用浏览器探活：
http://127.0.0.1:<端口>/health不需要 token ⇒ 一次就能区分"服务没起来"和"鉴权不对" ✓ - 先现查、再怀疑参数：工具与模板状态一律在帮助弹框「MCP 接口手册」里看（权威、实时）——⛔ 别拿离线清单当依据
- 只重跑失败的那一步：⛔ 别整批重来（既慢又可能覆盖已出的产物）
五、长期使用建议
- 不用时关掉服务（设置 → MCP Agent），需要时再开 ✓
- 定期轮换 token（怀疑泄露就点「重新生成」），并同步所有客户端
- 给第三方应用最小范围：只在需要的项目里用它；不需要时移除它的 MCP 配置
- 别把带 token 的配置文件放进会同步/上传的地方（网盘、代码仓库、共享目录）
来源：E:/workbuddyProj/unlimitCanvas/ai_manual/mcp_guide/05-安全、鉴权与故障排查.md