该技能的目标是把 MCP 问题归约为对单个具体文件字段的修改：由使用者在客户端查看状态，由智能体直接读取和编辑配置文件。
配置文件位置与优先级：用户级配置为 ~/.zcode/cli/config.json，字段为 mcp.servers；用户级回退为 ~/.agents/mcp.json，字段为顶层 mcpServers，仅在 ~/.zcode/cli/config.json 未定义任何 MCP 服务器时使用。工作区级配置为 <repo>/.zcode/config.json 或 <repo>/zcode.json，从仓库根目录到工作目录的每一级都会被读取，字段为 mcp.servers；工作区级回退为 <repo>/.agents/mcp.json，字段为顶层 mcpServers，仅在对应工作区 .zcode 未定义 MCP 服务器时使用。插件级配置位于 <pluginRoot>/.mcp.json 或清单的 mcpServers 字段，键按 plugin:<plugin>:<server> 命名空间化。同一作用域内 .zcode 优先，.agents/mcp.json 为回退：若该作用域的 .zcode 定义了任何 MCP 服务器，则其 .agents/mcp.json 会被完全忽略。同名服务器跨作用域覆盖顺序为 CLI → 环境 → 用户 → 工作区 → 系统，即用户覆盖工作区；插件服务器构成基础层，被显式配置覆盖。
自动连接：来自用户、工作区、插件、环境和 CLI 各作用域的 MCP 服务器在会话启动时都会被信任并自动连接。工作区服务器过去不受信任并提示需要显式连接，现在与其他作用域一样默认连接。客户端中查看状态和修复配置的入口为 Settings → MCP。
配置模式：stdio 需要 command，可选 args、cwd、env、enabled、timeoutMs；http/sse 需要 url，可选 headers、enabled、timeoutMs。标准字段名为 env（stdio 环境变量）和 headers（HTTP/SSE 请求头）。command 是字符串，args 是字符串数组，不应把 OpenCode 风格的 command: ["npx", "-y", ...] 粘贴进 ZCode 的 JSON 编辑器。省略 type 时会推断：有 command 视为 stdio，有 url 视为 http。CLI 直接读取配置时会自动迁移旧形式（type: "remote" → http，environment → env，enable → enabled，http_headers → headers），但桌面应用管理的会话创建可能绕过部分 CLI 文件解析器，因此桌面 Settings → MCP 读取的文件应使用规范字段。配置文件的服务器模式是严格的：出现未知键会导致该服务器被丢弃。模板变量 ${...} 仅对插件提供的 MCP 服务器展开（如 ${CLAUDE_PLUGIN_ROOT}、${ZCODE_PLUGIN_ROOT}、${CLAUDE_PROJECT_DIR}、${user_config.KEY}）；配置文件中的 MCP 服务器不展开模板，应使用绝对路径。默认超时为 30000 ms。
查看状态：在客户端打开 Settings → MCP，每个条目显示已连接、已禁用、已断开或失败，并内联显示错误；插件提供的服务器标记为内置。编辑后重启受影响的会话，若设置页仍显示旧数据则重启 ZCode，再重新打开 Settings → MCP 确认。stdio 服务器捕获的错误流写入 ZCode 日志，要查看完整输出，可在终端直接运行服务器命令及其参数。
常见陷阱按症状、原因、修复组织：工作区服务器不连接时，先看 Settings → MCP 状态，失败则按失败排查，未列出则可能是配置未加载或被回退文件遮蔽；command not found（如 spawn npx ENOENT）应使用绝对路径、必要时加 cwd，Windows 上指向 .cmd/.exe；${...} 字面传入进程说明配置文件不展开模板，应改用具体绝对路径；插件缺少环境值或密钥时在插件管理的高级设置中配置或导出所需环境变量，敏感值只能放在 env/headers；传输类型错误或未知键会使服务器被静默丢弃，需让 type 与字段匹配、移除多余顶层键、确保 command 与 url 恰有其一；工作区编辑无效通常是用户级同名服务器覆盖，应改用户条目或重命名；连接或工具列表超时可加 timeoutMs: 60000 并处理启动慢问题；仅显示 Connection closed 时查看日志或在终端直接运行命令；JSON 语法错误会导致服务器甚至整个文件消失，需校验并修复；服务器显示禁用应设 enabled: true 或删除该字段；桌面管理的服务器列表会覆盖文件，此时应通过 Settings → MCP 管理；.agents/mcp.json 编辑无效或键错误，可能是同作用域 .zcode 已定义 MCP 服务器导致其被忽略，或误放在 mcp.servers 而非顶层 mcpServers；日志中有服务器名但模型请求无 MCP 工具，通常是启动失败导致 toolCount 与 registeredToolCount 为零，常见原因是 ~/.zcode/cli/config.json 中的旧 environment 字段，应改为 env 后重启；编辑 JSON 后 Settings → MCP 崩溃并报 command.trim is not a function，说明 command 非字符串，应手动改为 "command": "npx" 并把其余放入 args，然后重启。
定位工作流按顺序执行，找到原因即停止：确认 MCP 已启用；在 Settings → MCP 读取状态，禁用按对应陷阱处理，失败读取内联错误，未列出则检查配置是否加载；校验 ~/.zcode/cli/config.json 与 <repo>/.zcode/config.json（及 zcode.json）的 JSON 有效性；失败服务器按 ENOENT、超时、Connection closed、http/sse 网络错误分别排查；若日志有服务器名但模型请求无 mcp__ 工具，检查启动日志中 mcp.startup.completed 与 mcp.tools.registered，toolCount=0 时先检查字段名；编辑无效时检查用户覆盖工作区或桌面管理列表；出现字面 ${...} 时检查模板与插件变量；最后应用具体修复（通常是编辑 ~/.zcode/cli/config.json 的 mcp.servers.<name> 下的命令、参数、cwd、env、headers、timeoutMs、enabled），重启会话并重新打开 Settings → MCP 确认。