MCP 已配置但连接失败或没有工具

本文处理 mcp.json 已写入，但 mogick mcp list、TUI /mcp 或 Agent 工具中看不到预期 MCP server / tool 的情况。字段定义和正常配置方式见 MCP 配置。

先做快速检查

mogick mcp list
mogick doctor

同时在 TUI 中输入 /mcp，确认服务器来源、启用状态和当前状态。

MCP 配置按服务器名称合并：项目 .mogick/mcp.json 中的同名 server 会覆盖全局 <config-dir>/mcp.json 中的同名 server；不同名 server 会同时保留。ACP 宿主注入的 MCP 配置优先级更高。

按你看到的状态处理

服务器没有出现在列表中

优先检查配置是否被加载到当前工作区：

文件名必须是 mcp.json。
顶层结构应为 servers 对象。
项目配置路径是启动 Mogick 时工作目录下的 .mogick/mcp.json。
同名 server 可能被项目配置或 ACP 宿主注入配置覆盖。
MOGICK_CONFIG_FILE 只替代主 config.json，不会改变 MCP 配置文件位置。

如果 mogick doctor 报 JSON 解析错误，先修复对应 mcp.json。

服务器显示为 disabled

enabled 省略时等同于未启用。需要连接的 server 应显式写入：

json

{
  "enabled": true
}

也可以在 TUI 的 /mcp 面板中把该 server 设为 Enabled。

服务器显示为 cold

cold 通常不是错误。它表示该 server 启用了 startup: "lazy"，当前还没有发起连接。

处理方式：

如果希望启动后立即连接，把 startup 改为 "eager"，或省略该字段。
如果希望保持懒加载，可在需要时让 Agent 使用 MCP 元工具连接和调用。

服务器显示为 connecting

connecting 表示 Mogick 已记录这个启用的 server，但连接尚未进入 connected 或 failed。

常见原因：

本地 stdio 进程启动较慢。
command 路径或参数不正确，进程无法完成 MCP 初始化。
远程 url 不可达或协议不匹配。

先确认配置中的 type、transport、command 或 url 与服务端实际启动方式一致。timeout 单位是毫秒；只在确认服务端初始化确实较慢时再调大。

服务器显示为 failed

failed 表示最近一次连接尝试失败。修复配置后，Mogick 会在配置变更时重新协调连接；如果只是服务端临时故障恢复，也可以让 Agent 使用 mcp.reconnect 对指定 server 发起一次重连。

不要把反复失败的问题简单理解为需要更长超时。更常见的是命令、路径、权限、URL、认证或协议不匹配。

本地 stdio server 检查项

本地 server 使用 type: "local" + transport: "stdio"，command 是数组，第一项是可执行文件，其余是参数。

优先检查：

command[0] 是否能在启动 Mogick 的同一个终端中执行。
如果依赖 Node.js、Python 等运行时，该运行时是否在当前终端的 PATH 中。
相对命令路径是否相对于启动 Mogick 时的工作目录可解析。
env 是否填写了服务端真正需要的环境变量。

本地进程会继承 Mogick 的进程环境；env 中的值按字面量追加或覆盖，不会展开 ${VAR} 占位符。

远程 HTTP / SSE server 检查项

远程 server 使用 type: "remote"，并通过 url 连接。

优先检查：

transport 是否与服务端一致：常见为 http，只有服务端明确要求 SSE 时才用 sse。
url 是否是 MCP 服务端实际暴露的地址。
headers 中的认证信息是否仍有效。
当前网络环境是否能访问该地址。

包含凭据的 headers 不应提交到版本控制，也不要粘贴到问题报告中。

已连接但 Agent 看不到具体工具

先区分“server 未连接”和“工具没有直接展开到模型工具列表”。

可以让 Agent 使用 MCP 元工具查看：

text

mcp.list
mcp.status
mcp.search
mcp.help
mcp.call

当 MCP 工具 schema 较多、占用上下文较大时，Mogick 会切换为渐进式发现模式：不把所有 server tools 直接塞进模型工具列表，而是通过 mcp.search、mcp.help、mcp.call 搜索、查看参数并调用。此时看不到每个具体工具，不一定代表连接失败。

如果 mcp.status 显示 server 已 connected，但工具数为 0 或缺少预期工具，应回到 MCP server 本身，确认它是否实现并返回了 tools/list。

确认问题已经解决

bash

mogick mcp list
mogick doctor

一般可以按以下状态判断：

状态	判断
`connected`	已连接，可以继续看工具和资源是否符合预期
`cold`	懒加载 server 的正常状态；需要时再连接
`disabled`	配置存在但未启用
`connecting`	仍在连接或初始化，继续看命令、URL、timeout
`failed`	最近一次连接失败，需要看错误信息和配置

仍未解决

反馈问题时请提供：

操作系统和 Mogick 启动目录。
mogick mcp list 输出。
mogick doctor 报告。
脱敏后的 server 配置。
本地 server 的手动启动结果，或远程 server 的可达性检查结果。

删除 API Key、Authorization 头、Cookie、内部地址和其他敏感环境变量。

MCP 已配置但连接失败或没有工具 ​

先做快速检查 ​

按你看到的状态处理 ​

服务器没有出现在列表中 ​

服务器显示为 disabled ​

服务器显示为 cold ​

服务器显示为 connecting ​

服务器显示为 failed ​

本地 stdio server 检查项 ​

远程 HTTP / SSE server 检查项 ​

已连接但 Agent 看不到具体工具 ​

确认问题已经解决 ​

仍未解决 ​

相关文档 ​