浏览 MCP与Skills教程与资源
MCP 连接失败与工具不出现：从配置到调用结果逐层定位
把未加载、进程失败、协议不兼容、工具为空与调用报错拆开，用同一配置和可观察结果定位，避免反复重装或同时更改多项设置。
‘已连接’和‘能完成任务’中间还有几层
| 看到的现象 | 先取哪份证据 | 优先查什么 |
|---|---|---|
| Server 名称都没有 | 客户端当前实际加载的配置、作用域和解析错误 | 配置未加载、同名覆盖、未启用；暂时不要查工具参数 |
| 名称有，但启动失败 | 启动命令、工作目录、退出码、stderr | 运行时或命令不存在、环境变量未继承、进程提前退出 |
| 远程地址可访问，但协议调用失败 | 真实 MCP 请求/响应、所用传输和协议版本 | endpoint、认证、协议兼容；HTTP 首页能开不能证明 MCP 正常 |
| 连接正常，工具列表空或缺项 | Server 原始 tools/list 与客户端最终展示列表 | Server 能力、分页、工具集、凭证过滤、客户端过滤 |
| 工具可见，调用失败 | 实际参数、原始错误或 isError 结果、目标资源 | schema、参数值、资源授权或下游故障 |
终端里能启动，不代表桌面客户端能启动
以 Windows Codex 和本地 Filesystem 为例，先回读同一连接，再核对运行时。终端从你的交互式 PATH 找到 npx，桌面应用可能使用启动时继承的旧 PATH；相对路径也会随 cwd 改变。不要同时改包版本、代理、权限和配置位置，否则恢复以后仍不知道原因。
确认命令与连接定义
Get-Command node,npx,cmd | Select-Object Name,Source node --version codex --version codex mcp get filesystem_lab # 在 Codex 交互界面查看当前会话： /mcp
分享配置或日志前检查是否含环境变量秘密。get 输出只能证明定义存在，不能证明进程已成功启动或工具发现已完成。
先分清进程没启动，还是输出不是 MCP 协议
ENOENT、找不到命令或不是可执行文件
- 原因
- 客户端执行的命令路径无法解析，或把脚本启动方式当成可执行文件。
- 怎么改
- 核对实际 command 和 args；Windows 的 npx 可采用 cmd /c 启动方式。使用完整路径时需匹配本机安装位置，不能抄别人用户目录。
进程退出并有缺失环境变量或无效目录错误
- 原因
- 包已经运行，但启动输入不满足该 Server 的要求。
- 怎么改
- 修正错误所指向的那一个变量或目录，再用相同命令复测。不要打印变量值；只确认所需变量是否在子进程环境中可见。
进程不退出，客户端却报解析失败
- 原因
- stdio 的 stdout 被欢迎语、调试日志或包装脚本污染，或者 Server 实际运行的是 HTTP 模式。
- 怎么改
- 核对该 Server 的传输参数；普通日志应走 stderr，stdout 留给协议消息。浏览器能打开的端口不等于这个命令在提供 stdio。
第一次启动超时，第二次才成功
- 原因
- 首次依赖下载、浏览器组件准备或冷启动可能占用了启动时限，也可能仍有其他问题。
- 怎么改
- 对照 stderr 和耗时，完成可验证的依赖准备后重试同一配置。有证据表明是稳定冷启动耗时，才调整启动时限；不要无限加大超时掩盖崩溃。
用 Inspector 复用同一启动命令
当 GUI 只显示一句失败时，MCP Inspector 可显示工具列表、schema 和调用结果。当前官方 Inspector 需要 Node 22.19.0 或更新版本；与 Server 的最低 Node 要求分别核对。下面以已有 C:/mcp-lab/allowed 为例，npx 会获取并执行 Inspector 与 Server 包，先核对来源，不在生产凭证环境试装。
连接同一 Filesystem Server
npx -y @modelcontextprotocol/inspector cmd /c npx -y @modelcontextprotocol/server-filesystem C:/mcp-lab/allowed
不要分享启动输出中的带 token 管理 URL。Inspector 成功只说明在它的环境下能工作；必须继续比较它与原客户端的 command、args、cwd、环境、Roots 和认证，不能直接宣称原客户端有 bug。
先比较原始列表与客户端列表，再决定改哪一边
Server 没有提供工具
MCP Server 可以提供资源、提示或其他能力，并非必须有 tools。先查看它的官方说明和能力响应。如果它本来仅提供 resources，工具面板为空可能是设计结果，应使用该客户端支持的资源入口，不能靠重装生出工具。
tools/list 本身为空
核对服务端是否启用了需要的工具集、身份是否有对应功能，以及返回是否分页。若响应带 nextCursor，读取后续页，不能把第一页当作完整列表。GitHub 只读模式删除写工具是预期行为，不能因为没有评论工具就扩大 Token 权限。
原始列表有工具，客户端却隐藏
比较工具 allow/deny 配置、当前会话是否重载，以及 schema 是否被客户端拒绝。保留具体被拒的工具名和校验信息。旧工具清单缓存、无效 schema、客户端不支持某特性都可能造成差异；需要证据才能区分。
版本兼容问题
记录双方实际协议版本。2025 系列的 initialize/会话流程与 2026-07-28 的协议机制存在差异；不要复制一段旧的 initialize 请求，就把新服务的拒绝认定为网络故障。使用支持双方版本的客户端或 Inspector 协商并观察错误，避免手动混搭旧头部与新请求格式。
HTTP 200 不等于工具执行成功
| 返回形态 | 能说明什么 | 下一步 |
|---|---|---|
| 客户端在发送前拒绝参数 | 请求尚未到 Server | 对照当前 inputSchema 的必填项、类型和枚举；不要只改自然语言描述 |
| JSON-RPC error，例如未知工具 | 请求方法、工具名或结构不被接受 | 重新取工具列表并使用当前名称；排除会话缓存旧工具 |
| 正常工具结果里 isError: true | 传输完成，实际工具操作失败 | 看工具错误中指出的资源、路径或下游响应；不要根据外层 HTTP 200 报告成功 |
| isError: false，但返回空内容 | 协议未报告错误，不保证业务对象被找到 | 用已知无敏感样本和同一参数复测，检查筛选、分页、身份和目标 |
| 请求超时，结果未知 | 不能确定是否执行或已产生副作用 | 先查询目标实际状态；写操作不要立即重复发送 |
把‘猜是代理’写成可验证的对照
一份有效记录可以只有几行：原请求是什么、在哪一层失败、改了哪一个条件、同一请求现在返回什么、恢复原条件是否仍失败。例如‘更正 command 路径后同一只读文件读取恢复’有可检查的差异；‘关了代理好像好了’若没有记录传输与请求，最多算临时缓解。
本地 stdio 通信并不经过 HTTP 代理，但 Server 自己下载依赖或访问下游可能经过网络。远程 HTTP 则可能经过系统代理、反向代理与上游 API。只有确定是哪段请求失败，才能判断该改哪里的代理；不要把所有握手超时都归咎于同一个开关。