AI Agent / 系统课时

排查 MCP 连接问题

排查 MCP 连接问题

MCP 连接失败时,不要从“工具为什么不能用”开始猜。更有效的做法是沿传输、初始化、版本协商、权限、方法调用和响应格式逐层缩小范围,直到找到第一处不满足协议约定的环节。

学习目标

  • 按固定顺序定位 MCP 握手、协议版本和超时问题
  • 区分传输故障、权限拒绝与响应格式错误
  • 用最小化日志和格式校验确认修复是否生效

先确定失败发生在哪一层

把一次 MCP 调用拆成五层:传输建立、initialize 初始化、权限校验、具体方法调用、结果解析。排查时只追“第一处失败”,因为后续报错常常只是前一层失败的连锁反应。

MCP 连接问题的分层排查流程

如果是本地 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 值。

python
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 提示词、工具实现和网络配置之间反复试错。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

排查 MCP 连接问题

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通