MCP 接入后调不通，通常不是单点故障，而是 Host、Client、Server 三层中某一层的配置、通信方式或调试信息缺失导致的。本篇作为《手搓生产级 AI Agent 系统》第 21 篇，进入 MCP 全链路排错与验证。
先分清三层职责
MCP 基于 C/S 架构，由多个组件构成。资料提到 MCP Server 提供 command 和 SSE 两种类型功能。MCP Host 是承载 LLM 的应用，MCP Client 负责与 Server 建立连接并转发调用。排错第一步是确认问题出在哪一层：Host 是否配置了支持 function calling 的 LLM，Client 是否成功初始化，Server 是否正常启动并暴露工具。
资料中提到的 ChatMCP 可作为 Host 配置示例，配置时需关注 LLM 是否支持 function calling。如果 Host 侧 LLM 不支持 function calling，即使 Client 和 Server 都正常，工具调用也不会被触发。
通信方式：stdio 与 SSE 的选择
资料提到 MCP 支持标准输入输出（stdio）和服务器发送事件（SSE）两种通信方式。stdio 适合本地进程间通信，Server 作为子进程启动，Client 通过标准输入输出读写消息。SSE 适合远程或实时数据更新场景，具有高效、实时、易用的优势。
排错时先确认通信方式与部署形态匹配：本地调试优先 stdio，远程服务优先 SSE。如果 stdio 模式下 Server 启动失败，常见原因是本地 node 环境版本不够高。资料明确指出，调试需本地有高版本 node 环境。这是容易被忽略的前置条件。
用 MCP Inspector 做隔离验证
资料中提到的 MCP Inspector 调试工具，按调试工具常见用法整理，可在不依赖 Host 的情况下直接连接 Server，验证工具列表、参数 schema 和调用结果。该工具的具体功能边界需以官方文档核验。排错顺序建议：先用 Inspector 确认 Server 本身可用，再接入 Client，最后接入 Host。
如果 Inspector 能列出工具但 Host 调不通，问题在 Client 或 Host 的配置与 LLM function calling 支持上。如果 Inspector 也连不上，问题在 Server 启动、通信方式或环境依赖上。
SDK 实现中的常见断点
资料提到 MCP 官方支持 Python、TypeScript、Java、Kotlin 四种语言的 SDK。以 Java SDK 0.7.0 版本为例，McpClient 接口是核心入口，McpAsyncClient 是异步实现的核心依赖。基于 SDK 开发 Client 时，需关注初始化是否完成、传输层是否建立、工具列表是否成功拉取。
Spring AI 集成 MCP 时，资料提到可通过第三方服务、单 MCP、多 MCP 及 Playwright 自动化等示例展示 MCP Client 使用，并基于 Spring AI 框架开发 MCP Server 的两种接口方式。集成报错常见于依赖版本不匹配、Server 描述字段缺失或传输配置错误。
Server 实现：description 字段不能省
资料强调 MCP Server 实现中 description 字段的重要性。工具描述直接影响 LLM 能否正确选择工具。如果 description 缺失或过于模糊，Host 侧 LLM 可能不调用或调错工具，表现为“调不通”。排错时先检查每个工具的 description 是否准确描述用途和参数。
验证清单
按以下顺序逐层验证：
- 环境：本地 node 版本是否满足要求。
- Server：能否独立启动，description 是否完整。
- Inspector：能否连接并列出工具、调用成功。
- Client：SDK 初始化、传输层、工具拉取是否正常。
- Host：LLM 是否支持 function calling，MCP 配置是否正确。
- 通信方式：stdio 与 SSE 是否与部署形态匹配。
边界说明
以上排错思路基于资料中已提到的 stdio/SSE 通信、MCP Inspector、SDK 实现和 Spring AI 集成方式。具体版本兼容性、错误码含义和平台差异需以官方文档为准。资料未提供的内容，如特定 SDK 版本的 API 变更细节，不在本篇展开。
下一篇将继续沿生产级 Agent 系统方向推进，进入 MCP 接入后的可观测性与治理话题。