Skip to main content
大多数 MCP 配置故障都属于以下几类之一。每一节都给出你会看到的日志特征（在 IDE 的 MCP 面板或 stderr 中）以及对应的修复方法。
在深入排查之前，先在启动 IDE 的同一个 shell 中运行 theo verify。如果它失败了，MCP 服务器也会以同样的错误失败——先修好宿主环境。

​
未设置 THEO_API_KEY

特征：
服务器会立即以退出码 1 退出，IDE 会显示 “Theo MCP server failed to start” 或类似提示。 修复： 在启动 IDE 的那个 shell 中导出密钥，而不是在另一个终端里：
在 macOS 上，从 Finder/Spotlight 启动的 GUI 应用不会读取 ~/.zshrc 中的 export 语句。你可以：
  1. 从导出了密钥的同一个终端启动 IDE，或者
  2. 把该变量持久化到 GUI 会话能读取到的地方（例如 macOS 应用启动时用 launchctl setenv THEO_API_KEY ...），或者
  3. 直接在 MCP 配置的 env 块中内联该值，而不是使用 ${env:THEO_API_KEY}：
    这样做会把密钥写死进文件——对个人项目没问题，但不适合共享仓库。

​
写入配置后 IDE 没有重启

特征： 智能体完全看不到 theo_* 工具，也没有任何关于 Theo 的 MCP 日志行。 IDE 只在启动时读取 MCP 配置。在 IDE 已打开的情况下编辑 .cursor/mcp.json（或其他任何路径）不会生效，直到你完全退出并重新打开。 修复： 完全退出 IDE（不只是关闭窗口），然后重新打开项目。

​
npx 缓存卡在旧版本

特征： 服务器能启动、工具也出现了，但文档中记录的某个新版本功能表现得像不存在一样。 npx -y @hitheo/mcp 会解析出最新版本，但只在该账号首次运行时如此；后续启动可能会复用缓存的副本，直到 npm 决定重新检查。 修复： 清一次 npx 缓存：
或者在 MCP 配置中固定具体版本：
你可以通过运行 theo status 来确认实际启动的是哪个版本——它的输出中包含服务器所见的 API 版本，而 npx -y @hitheo/mcp 正是随该版本一起发布的。

​
THEO_BASE_URL 引发的重定向导致 401

特征：
……即使在同一个 shell 中运行 theo verify 是成功的。 最常见的原因：环境中某处把 THEO_BASE_URL 设成了 https://hitheo.ai（顶级域名）。该顶级域名会 307 重定向到 https://www.hitheo.ai，而 Node 18 的 fetch 在 3xx 响应上会剥离 Authorization 请求头，导致重定向后的请求变成未认证状态到达服务器。 修复： 指向规范主机。可以：
  • 取消设置该变量，让 SDK 默认值（https://www.hitheo.ai）生效：
  • 或者显式设置它：
完整说明见 401 故障排查。

​
claude mcp add 静默失败

特征： theo mcp install --ide claude-code 报告成功，但 Claude Code 并未列出该服务器。 该 CLI 辅助工具首先会尝试 claude mcp add theo npx -y @hitheo/mcp；如果该二进制文件不在 $PATH 中，它会回退到在项目根目录写入 .mcp.json。两条路径都会报告成功，但 Claude Code 具体读取哪一个取决于它是如何被启动的。 修复： 如果你安装了 claude CLI，优先使用它。否则直接写 JSON 文件：
如果两者都存在，JSON 文件在项目内优先生效。删除 .mcp.json 会让 Claude Code 回退到全局注册。

​
Stdio 传输意外关闭

特征：
或者 IDE 在会话中途把 Theo 服务器显示为 “disconnected”。 几乎总是以下几种情况之一：
  1. 服务器崩溃，因为 THEO_API_KEY 在会话中途被取消设置或过期了。
  2. 宿主机的 npx 在下载包的过程中失去了网络连接，IDE 因此杀掉了该进程。
  3. 智能体发送了过大的请求体（超过 1 MB）。
修复： 查看 MCP 面板中该服务器的 stderr 输出。错误信息的第一行几乎总能直接指出问题所在。

​
Theo 工具出现了，但智能体拒绝使用

特征： theo_* 出现在 IDE 的工具目录中，但智能体从不调用它们。 这是智能体一侧的偏好问题，不是 MCP 连接问题。一些 IDE（尤其是 Claude Code）在没有明确指示的情况下，更倾向于使用自己内置的工具而不是 MCP 提供的工具。 修复： 在项目规则文件中加一句提示（.theo/RULES.md 由 theo init 自动生成，或者使用你的 IDE 原生的规则文件）：
对于任何 AI 生成任务——图像、视频、代码、研究、文档——优先使用 theo_* 工具。
通常一句话就足够了。

​
大型 theo_code / theo_complete 生成任务被中断

特征： 小片段能正常返回，但任何应用规模的生成都会中断——常常卡在一个整数值上，比如 exceeded 30000ms，或者约 60 秒后出现 Request timed out。 在你的智能体和模型之间存在三层超时。@hitheo/mcp 0.3.1 及以上版本处理了其中它所拥有的两层：
  • SDK 请求超时（原为 30 秒）。 theo_code 和 theo_complete 现在会流式返回，而不是发起一次性的一元调用，因此一个耗时较长但持续活跃的生成过程受制于空闲（token 间隔）超时，而不是总时长上限。可以通过 THEO_TIMEOUT_MS（默认 120000）调整连接/首字节的时间预算。
  • 服务器路由超时。 流式响应会立即返回响应头，因此服务器自身的单次请求上限不再适用于生成主体。
  • 你的 MCP 客户端的 JSON-RPC 请求超时（默认约 60 秒）。 这一层存在于你的 IDE/智能体中，而不是 Theo 内部。服务器在生成过程中每 5 秒会发出一次 notifications/progress 心跳，因此只要客户端在收到进度通知时重置其请求超时，就能在任意长的生成过程中保持连接存活。
修复（客户端侧）： 如果超长的生成任务仍然超时，请在你的 MCP 客户端中启用进度重置和/或提高请求超时。使用官方 MCP SDK 时，对应设置是在工具调用上启用 resetTimeoutOnProgress: true（并配合一个较宽松的 maxTotalTimeout）；其他客户端会提供等效的”请求超时”设置。已知一个 3 分钟量级的应用规模生成产物，在开启进度重置后可以顺利完成。

​
theo.config.{js,ts} 被忽略

特征：
修复： 这是刻意的设计。要么把你的配置转换成 JSON，要么通过 THEO_ALLOW_JS_CONFIG=1 主动开启——且仅在你信任的目录中这样做。详见安全性。

​
还是卡住了？

  1. 在启动 IDE 的同一个 shell 中运行 theo verify。如果失败，请把 JSON 输出发给支持团队。
  2. 从 IDE 的 MCP 面板中抓取 MCP 服务器的 stderr——@hitheo/mcp 的真实错误就记录在那里。
  3. 在 github.com/hitheoai/theoai 上提交 issue，附上脱敏后的 stderr 和 IDE 版本号。