AI Agent / 系统课时
排查 MCP 连接问题
排查 MCP 连接问题
MCP 连接失败时,不要从“工具为什么不能用”开始猜。更有效的做法是沿传输、初始化、版本协商、权限、方法调用和响应格式逐层缩小范围,直到找到第一处不满足协议约定的环节。
学习目标
- 按固定顺序定位 MCP 握手、协议版本和超时问题
- 区分传输故障、权限拒绝与响应格式错误
- 用最小化日志和格式校验确认修复是否生效
先确定失败发生在哪一层
把一次 MCP 调用拆成五层:传输建立、initialize 初始化、权限校验、具体方法调用、结果解析。排查时只追“第一处失败”,因为后续报错常常只是前一层失败的连锁反应。

如果是本地 stdio 传输,先确认服务进程能启动、工作目录正确、依赖齐全,并且协议消息只写到标准输出;普通日志应写到标准错误,否则一行调试文本就可能破坏 JSON-RPC 消息流。HTTP 传输则先确认地址、TLS、代理和网络策略可达。
检查初始化与协议版本
旧版连接通过 initialize 与后续通知建立会话。采用 2026-07-28 版时,检查每个请求的版本元数据以及 server/discover 或不支持版本响应。先确认实际使用的版本,再定位缺少能力还是方法调用失败。
当日志出现“unsupported protocol version”“method not available”或握手后立即断开时,优先检查客户端与服务端实际声明的协议版本,而不是只看 SDK 包版本。升级一端后如果问题出现,也要确认另一端是否仍支持协商出的版本以及对应能力。
把超时拆成连接超时和调用超时
“超时”至少有两种。连接或初始化超时说明问题还没进入业务方法;工具调用超时则表示握手已经完成,应继续看服务端是否收到请求、外部依赖是否阻塞,以及客户端超时阈值是否过短。
排查时记录四个时间点:开始建立连接、收到初始化响应、发出方法请求、收到方法响应。只要确定最后一个成功时间点,就能把搜索范围压缩到一个阶段。动态时间值可记为 <TIME>,不要用一次运行的毫秒数作为固定基线。
核对权限和运行环境
HTTP 服务出现 401 或 403 时,检查令牌是否传递、是否过期、请求主体对应的 scope 或受众是否正确。对于本地 stdio 服务,还要检查启动 MCP 服务的宿主进程是否继承了需要的环境变量、文件权限和当前目录。
权限问题和协议问题不要混在一起处理:前者通常表现为请求已被服务端识别但被拒绝,后者则常发生在初始化、方法解析或响应解码阶段。修复后应重新执行同一个最小请求,而不是立刻回到完整 Agent 工作流。
校验响应是不是合法 JSON-RPC
如果怀疑响应配对有误,先截取一条脱敏后的 JSON-RPC 响应对象。保存下面的脚本为 mcp_response_check.py。本例只接受 MCP 请求常用的字符串或整数 ID,并要求在命令行传入原请求 ID 的 JSON 值。
import json
from pathlib import Path
import sys
def validate_response(data, expected_id):
if type(expected_id) not in (int, str):
raise ValueError("expected id must be an integer or string")
if not isinstance(data, dict) or data.get("jsonrpc") != "2.0":
raise ValueError("expected a JSON-RPC 2.0 response object")
actual_id = data.get("id")
if type(actual_id) is not type(expected_id) or actual_id != expected_id:
raise ValueError("response id does not match request")
if ("result" in data) == ("error" in data):
raise ValueError("response must contain one of result or error")
if "error" in data:
error = data["error"]
if (not isinstance(error, dict) or type(error.get("code")) is not int
or not isinstance(error.get("message"), str)):
raise ValueError("invalid error object")
if __name__ == "__main__":
if len(sys.argv) != 3:
sys.exit("usage: python mcp_response_check.py response.json expected-id-json")
try:
data = json.loads(Path(sys.argv[1]).read_text(encoding="utf-8"))
expected_id = json.loads(sys.argv[2])
validate_response(data, expected_id)
except (OSError, ValueError) as error:
sys.exit(f"response format: ERROR - {error}")
print("response format: OK")将 {"jsonrpc":"2.0","id":1,"result":{"tools":[]}} 保存为 response.json,运行 python mcp_response_check.py response.json 1,应输出 response format: OK。改用请求 ID 2 会报错。若原请求 ID 是字符串,应把其 JSON 双引号作为参数内容保留下来。
该检查只验证单条已配对的响应,未验证每个方法的结果模式,也未解析 Streamable HTTP 的 SSE 外壳。遇到无法匹配任何请求的错误响应,应按独立协议错误排查。工具超时或取消也无法证明副作用已经停止,应通过服务端状态或幂等键核对。
用最小闭环确认修复
修复后不要先跑完整业务链路。先用最小客户端完成所用版本的协议启动与发现;再调用一个无副作用、输入最简单的方法;最后再恢复真实工具调用。每一步都保留请求方法、请求 id、响应类型和耗时,且日志中不要记录令牌等敏感值。
当同一个最小请求能够稳定完成“传输可用 → 版本兼容 → 权限通过 → 方法返回 → 响应可解析”这条链路,才说明 MCP 连接问题真正关闭。这样排查能避免在 Agent 提示词、工具实现和网络配置之间反复试错。