第34篇-MCP调试全攻略-Inspector-日志-网络抓包

【MCP 全栈教程】第 34 篇MCP 调试全攻略——Inspector、日志、网络抓包本系列定位从协议原理到 Server 开发、Client 开发、再到各大平台实战集成系统化掌握 MCPModel Context Protocol全栈技术体系。本篇你将学到掌握 MCP Inspector 的进阶用法多 Server 场景、协议版本切换、手动调用工具学会分析 STDIO Server 的 stderr 日志定位启动与运行时问题掌握 HTTP Server 的请求/响应抓包技巧理解_meta字段在调试中的作用与检查方法运用连接问题排查决策树快速定位故障根因熟记 MCP / JSON-RPC 常见错误码速查表一句话总结调试 MCP 应用的核心三板斧是Inspector 看交互、stderr 看进程、抓包看协议配合错误码速查表能覆盖 90% 以上的常见问题。一、MCP Inspector 进阶用法1.1 Inspector 是什么MCP Inspector 是协议规范提供的官方可视化调试工具用于在不编写 Client 代码的情况下与 Server 交互。它的核心价值能力说明可视化握手展示initialize请求/响应的完整内容手动调用工具填表式调用tools/call无需写代码资源/Prompt 浏览列出并预览resources、prompts协议版本切换测试 Server 对不同协议版本的支持扩展协商检查查看capabilities.extensions的协商结果1.2 启动与连接连接 STDIO Server# 通过命令行参数指定 Server 的启动命令npx modelcontextprotocol/inspector --\python /path/to/my_server.py# 带 Server 启动参数npx modelcontextprotocol/inspector --\node/path/to/server.js--port3000--debug连接 HTTP Servernpx modelcontextprotocol/inspector--urlhttps://api.example.com/mcp启动后浏览器会打开 Inspector 界面分为以下区域区域功能Connection Panel连接配置、传输类型选择Handshake Tabinitialize握手详情Tools Tab工具列表与手动调用Resources Tab资源浏览Prompts TabPrompt 模板预览Extensions Tab扩展协商状态Logs Tab消息收发日志1.3 多 Server 场景调试真实项目中 Host 通常同时连接多个 Server。Inspector 支持在单个界面中管理多个连接// inspector-config.json{servers:{database:{transport:stdio,command:python,args:[./servers/db_server.py]},filesystem:{transport:stdio,command:node,args:[./servers/fs_server.js]},weather:{transport:http,url:https://weather.example.com/mcp}}}npx modelcontextprotocol/inspector--configinspector-config.json在多 Server 场景中常见的调试任务任务操作方法查看某 Server 的工具列表在 Server 下拉中选择切到 Tools Tab对比两个 Server 的 capabilities切换 Server 查看 Handshake Tab定位工具名冲突搜索工具名Inspector 会高亮来源 Server验证跨 Server 调用顺序在 Logs Tab 按时间线查看消息流1.4 协议版本切换Inspector 允许手动指定initialize请求中的protocolVersion测试 Server 对旧版本的兼容性测试目标设置 protocolVersion观察点最新特性2026-07-28扩展协商是否成功向后兼容2025-06-18Server 是否降级处理不支持的版本2024-01-01是否返回-32022 UnsupportedProtocolVersion1.5 手动调用工具Inspector 的 Tools Tab 提供了一个表单界面根据工具的inputSchema自动生成输入框工具search_users ┌─────────────────────────────────────┐ │ query [________________________] │ ← string │ limit [10_____________________] │ ← number, default 10 │ active [☑] │ ← boolean │ role [admin ▼] │ ← enum └─────────────────────────────────────┘ [调用] [清除]调用结果会以 JSON 高亮的形式展示在下方。这对于验证工具的inputSchema定义是否正确非常有用——如果 Inspector 无法生成合理的输入框说明 Schema 本身有问题。二、STDIO Server 的 stderr 日志分析2.1 为什么用 stderrMCP 规范规定STDIO 传输中Server 的 stdout 只能用于 JSON-RPC 消息。任何日志、调试信息都必须写到 stderr否则会破坏协议帧。通道用途能否写日志stdinClient → Server 的 JSON-RPC 请求——stdoutServer → Client 的 JSON-RPC 响应绝对不能stderr诊断日志、错误输出推荐2.2 结构化日志实践Python使用 structlogimportstructlogimportsys# 配置日志输出到 stderrJSON 格式structlog.configure(processors[structlog.processors.add_log_level,structlog.processors.TimeStamper(fmtiso),structlog.processors.JSONRenderer(),],wrapper_classstructlog.make_filtering_bound_logger(20),# INFOlogger_factorystructlog.PrintLoggerFactory(filesys.stderr),)logstructlog.get_logger()asyncdefhandle_tool_call(name:str,args:dict):每次工具调用都记录结构化日志。log.info(tool_call_start,toolname,args_keyslist(args.keys()))try:resultawaitdispatch_tool(name,args)log.info(tool_call_success,toolname,duration_msresult.get(_duration_ms),)returnresultexceptExceptionase:log.error(tool_call_failed,toolname,errorstr(e),error_typetype(e).__name__,)raise日志输出示例stderr{event:tool_call_start,tool:search_users,args_keys:[query,limit],level:info,timestamp:2026-07-30T10:15:22Z}{event:tool_call_success,tool:search_users,duration_ms:142,level:info,timestamp:2026-07-30T10:15:22Z}TypeScript使用 pinoimportpinofrompino;// pino 默认输出到 stderrconstlogpino({level:process.env.LOG_LEVEL??info,formatters:{level(label){return{level:label};},},});asyncfunctionhandleToolCall(name:string,args:Recordstring,unknown){conststartDate.now();log.info({tool:name,msg:tool_call_start});try{constresultawaitdispatchTool(name,args);log.info({tool:name,durationMs:Date.now()-start,msg:tool_call_success,});returnresult;}catch(e:any){log.error({tool:name,error:e.message,errorType:e.constructor.name,msg:tool_call_failed,});throwe;}}2.3 日志分析技巧问题现象关注日志字段排查方向Server 启动失败event: server_init_error检查端口冲突、依赖缺失工具调用超时duration_ms异常大数据库慢查询、外部 API 延迟间歇性错误error_type统计连接池耗尽、内存不足协议解析失败event: json_parse_errorstdout 被意外写入非 JSON 内容2.4 捕获 stderr 的方法Python Host 捕获子进程 stderrimportsubprocessimportasyncioasyncdefrun_stdio_server_with_logs(command:list[str],log_file:strserver_stderr.log):启动 STDIO Server 并把 stderr 写入文件。procawaitasyncio.create_subprocess_exec(*command,stdinasyncio.subprocess.PIPE,stdoutasyncio.subprocess.PIPE,stderrasyncio.subprocess.PIPE,)# 异步读取 stderr避免缓冲区满导致死锁asyncdefdrain_stderr():withopen(log_file,w)asf:whileTrue:lineawaitproc.stderr.readline()ifnotline:breakf.write(line.decode())f.flush()asyncio.create_task(drain_stderr())returnproc三、HTTP Server 的请求/响应抓包3.1 抓包工具选择工具适用场景特点mitmproxy开发调试可编程代理支持脚本Wireshark网络层分析抓 TCP/TLS 包curl verbose快速验证轻量适合单次请求浏览器 DevToolsWeb Client查看 SSE/EventSource3.2 使用 mitmproxy 抓包# 启动 mitmproxy监听 8080mitmproxy --listen-port8080# 让 MCP Client 通过代理发送请求exportHTTPS_PROXYhttp://127.0.0.1:8080exportHTTP_PROXYhttp://127.0.0.1:8080# 如果是自签证书需让 Client 信任 mitmproxy 的 CAexportNODE_EXTRA_CA_CERTS~/.mitmproxy/mitmproxy-ca-cert.pem在 mitmproxy 界面中可以逐条查看 MCP 的 JSON-RPC 请求和响应 POST https://api.example.com/mcp Request: { jsonrpc: 2.0, id: 1, method: initialize, params: { protocolVersion: 2026-07-28, ... } } Response (200): { jsonrpc: 2.0, id: 1, result: { protocolVersion: 2026-07-28, ... } }3.3 使用 curl 手动测试# 1. initialize 握手curl-XPOST https://api.example.com/mcp\-HContent-Type: application/json\-d{ jsonrpc: 2.0, id: 1, method: initialize, params: { protocolVersion: 2026-07-28, capabilities: {}, clientInfo: {name: curl-test, version: 1.0} } }# 2. 建立初始化通知curl-XPOST https://api.example.com/mcp\-HContent-Type: application/json\-HMcp-Session-Id: 从上一步响应获取\-d{jsonrpc: 2.0, method: notifications/initialized}# 3. 列出工具curl-XPOST https://api.example.com/mcp\-HContent-Type: application/json\-HMcp-Session-Id: session-id\-d{jsonrpc: 2.0, id: 2, method: tools/list}# 4. 调用工具curl-XPOST https://api.example.com/mcp\-HContent-Type: application/json\-HMcp-Session-Id: session-id\-d{ jsonrpc: 2.0, id: 3, method: tools/call, params: {name: search, arguments: {query: test}} }3.4 SSE 流抓包Streamable HTTP 传输使用 SSEServer-Sent Events推送消息。用 curl 可以实时查看 SSE 流# 订阅 SSE 流实时查看推送的消息curl-Nhttps://api.example.com/mcp\-HAccept: text/event-stream\-HMcp-Session-Id: session-id# 输出示例# data: {jsonrpc:2.0,method:notifications/progress,params:{progressToken:abc,progress:50}}## data: {jsonrpc:2.0,method:notifications/progress,params:{progressToken:abc,progress:100}}四、_meta 字段检查4.1 _meta 的作用MCP 的无状态设计要求所有上下文信息显式传递。_meta字段是协议预留的自由扩展通道可出现在请求和响应的多个层级位置示例用途请求 params._meta携带 trace ID、超时提示响应 result._meta返回 Server 自定义诊断信息content item._meta单条内容的附加元数据4.2 调试中检查 _meta# Client 端注入调试用的 _metaasyncdefcall_with_trace(transport,tool:str,args:dict)-dict:importuuid trace_idstr(uuid.uuid4())returnawaittransport.request(tools/call,{name:tool,arguments:args,_meta:{traceId:trace_id,debugFlags:[timing,sql],requestSource:inspector,}})# Server 端读取 _meta 用于诊断asyncdefhandle_tool_call_with_meta(params:dict)-dict:metaparams.get(_meta,{})trace_idmeta.get(traceId,no-trace)iftiminginmeta.get(debugFlags,[]):importtime t0time.time()resultawaitexecute_tool(params)result[_meta]{traceId:trace_id,serverTimingMs:round((time.time()-t0)*1000,2),}returnresultreturnawaitexecute_tool(params)4.3 _meta 检查清单调试时优先检查_meta中以下信息字段意义异常时的动作traceId全链路追踪 ID在日志中搜索该 ID 关联请求serverTimingMsServer 内部耗时与端到端耗时对比定位网络瓶颈warningsServer 发出的告警查看是否有降级操作featureFlags功能开关状态确认特性是否被意外关闭五、连接问题排查决策树5.1 STDIO 连接问题STDIO Server 无法连接 │ ├─ 子进程是否启动成功 │ ├─ 否 → 检查命令路径、依赖是否安装 │ └─ 是 → 继续 │ ├─ stderr 是否有错误日志 │ ├─ 是 → 根据日志排查端口冲突、权限不足等 │ └─ 否 → 继续 │ ├─ stdout 是否有 JSON-RPC 消息 │ ├─ 否 → 检查是否误将日志写入了 stdout │ └─ 是 → 继续 │ ├─ initialize 是否收到响应 │ ├─ 否 → Server 可能阻塞在初始化检查启动逻辑 │ └─ 是 → 继续 │ ├─ 响应中的 protocolVersion 是否匹配 │ ├─ 否 → 返回 -32022检查版本协商 │ └─ 是 → 连接正常排查上层问题5.2 HTTP 连接问题HTTP Server 无法连接 │ ├─ 网络是否可达(curl -v url) │ ├─ 否 → DNS、防火墙、VPN 问题 │ └─ 是 → 继续 │ ├─ TLS 握手是否成功 │ ├─ 否 → 证书过期、不信任 CA、TLS 版本不匹配 │ └─ 是 → 继续 │ ├─ HTTP 状态码是什么 │ ├─ 401 → 授权问题检查 Token │ ├─ 403 → 权限不足检查 scope / EMA 决策 │ ├─ 404 → 端点路径错误 │ ├─ 426 → 需要升级协议如 HTTP/1.1 → HTTP/2 │ ├─ 5xx → Server 内部错误查 Server 日志 │ └─ 200 → 继续 │ ├─ Mcp-Session-Id 是否正确携带 │ ├─ 否 → 400 Bad Request后续请求被拒 │ └─ 是 → 继续 │ ├─ SSE 流是否正常建立 │ ├─ 否 → Accept 头是否包含 text/event-stream │ └─ 是 → 检查消息内容是否符合 JSON-RPC 格式六、常见错误码速查表6.1 MCP 专属错误码错误码名称含义常见原因-32020HeaderMismatch请求头不匹配Mcp-Session-Id缺失或不一致-32021MissingRequiredClientCapabilityClient 缺少必要能力调用了需要扩展支持的工具但未协商-32022UnsupportedProtocolVersion不支持的协议版本initialize中版本号 Server 不认识-32023InvalidResourceURI无效的资源 URIURI 格式错误或不存在-32024ResourceNotFound资源未找到资源已被删除或路径错误6.2 JSON-RPC 标准错误码错误码名称含义调试建议-32700Parse errorJSON 解析失败检查请求体是否合法 JSON-32600Invalid Request请求格式不合法缺少 jsonrpc / method 字段-32601Method not found方法不存在拼写错误或 Server 未实现-32602Invalid params参数无效对照 Schema 检查参数-32603Internal errorServer 内部错误查看 stderr 日志定位堆栈6.3 错误响应结构{jsonrpc:2.0,id:42,error:{code:-32021,message:Client capability tasks is required for this tool,data:{requiredExtension:io.modelcontextprotocol/tasks,hint:Add the extension to capabilities.extensions in initialize}}}data字段是可选的诊断信息优秀的 Server 实现应当尽量填充帮助 Client 快速定位问题。6.4 错误处理最佳实践TypeScriptclassMcpErrorHandler{/** 根据错误码生成用户可读的诊断信息。 */staticdiagnose(error:{code:number;message:string;data?:any}):string{consthints:Recordnumber,string{[-32020]:检查请求头中 Mcp-Session-Id 是否与握手时一致,[-32021]:需在 initialize 中声明扩展:${error.data?.requiredExtension???},[-32022]:Server 支持的协议版本请查看 discover 响应,[-32601]:确认方法名拼写正确或调用 tools/list 查看可用方法,[-32602]:对照工具的 inputSchema 检查参数类型与必填项,[-32603]:Server 内部错误请联系 Server 管理员或查看日志,};consthinthints[error.code]??未知错误请检查协议规范;return[${error.code}]${error.message}\n建议:${hint};}}// 使用try{awaittransport.request(tools/call,params);}catch(e:any){if(e.code){console.error(McpErrorHandler.diagnose(e));}else{console.error(非 MCP 错误:,e.message);}}本篇小结调试手段主要用途适用传输MCP Inspector交互式调试、协议版本测试STDIO HTTPstderr 日志进程级错误、启动失败STDIOmitmproxy / curlHTTP 请求/响应抓包HTTPSSE 流监听推送消息检查HTTP (Streamable)_meta 字段追踪 ID、诊断信息通用错误码速查表快速定位错误类别通用下篇预告第 35 篇MCP 性能优化与生产部署从进程启动到连接池、从超时熔断到监控告警全面覆盖 MCP 生产环境的性能与稳定性。如果本篇内容对你有帮助欢迎点赞收藏有任何疑问欢迎在评论区交流。