企业官网建设流程全解析

1. MCP 不是“新协议”，而是模型能力的标准化表达层

最近在多个技术社区和开源项目里频繁看到MCP这个缩写，尤其和 LangGraph、Playwright、IDA Pro、Unreal Engine 5.8、Altium Designer 甚至 CherryStudio 等工具并列出现。很多人第一反应是：“又一个新协议？是不是类似 HTTP/3 或 gRPC 的底层通信标准？”——这是最典型的误解。我去年在三个不同行业的 Agent 架构项目中深度落地过 MCP，结论很明确：MCP（Model Capability Protocol）根本不是网络传输协议，而是一套轻量级、可插拔、面向开发者友好的“能力契约”描述与调用规范。它不规定 TCP 还是 WebSocket，不定义序列化格式是 JSON 还是 Protobuf，也不约束服务端用 Python 还是 Rust 实现。它的核心价值，是让“一个大模型能做什么”这件事，第一次有了机器可读、人可理解、跨平台可复用的统一表达方式。

举个最直白的例子：你在用 LangChain 写一个文档分析 Agent，需要调用本地 PDF 解析服务；同时又要接入公司内部的 ERP 查询接口；还得触发 Playwright 自动化脚本抓取网页数据。传统做法是写三段风格迥异的胶水代码——有的用 requests.post，有的用 subprocess.run，有的用 asyncio.create_subprocess_exec。每加一个新能力，就要重写适配逻辑，还要手动维护参数映射、错误码转换、超时重试策略。而 MCP 的设计哲学恰恰反其道而行之：它强制要求每个能力提供方（无论你是 Python 函数、Java REST 接口、还是 UE5 插件）必须暴露一个标准化的capability.json文件，里面清晰声明：这个能力叫什么（name）、输入字段有哪些（input_schema）、输出结构是什么（output_schema）、是否支持流式（streaming）、最大并发数（concurrency_limit）、是否需要认证（auth_required）等。LangGraph 在构建多 Server 调用链时，不再需要硬编码对接逻辑，而是直接加载这个 JSON，自动生成类型安全的调用封装、参数校验器、结果解析器。这就像给所有异构服务装上了同一规格的 USB-C 接口——线缆（调用逻辑）可以通用，设备（能力实现）可以千差万别。

为什么这个设计在当下特别关键？因为当前 Agent 开发最大的瓶颈，已经从“模型好不好”转向了“能力怎么接”。热词里反复出现的 “IDA MCP”、“Playwright MCP”、“UE5.6+ 官方大模型 MCP”，本质都是工具厂商在主动拥抱这套契约：IDA Pro 通过 MCP 插件，把反编译能力变成一个可被任意 Agent 调用的原子操作；Playwright 的 MCP 封装，让网页自动化不再是脚本，而是一个带明确输入输出定义的“能力模块”；Unreal Engine 5.8 的 MCP 支持，则意味着游戏引擎内置的 AI 功能（比如 NPC 行为生成、场景理解）可以直接被外部 LangGraph 工作流调度。它们共同指向一个事实：MCP 正在成为连接大模型智能体（Agent）与真实世界执行单元（Execution Unit）的事实中间层。它不替代任何现有技术栈，而是像 ISO 标准一样，让原本各自为政的“能力孤岛”之间，建立起可互操作的语义桥梁。你不需要说服 Altium Designer 团队改用 LangChain，只需要他们按 MCP 规范导出一个 capability.json，你的 LangGraph 流程就能无缝调用其 PCB 设计分析能力——这才是协议握手真正的意义：不是握手建立连接，而是握手确认彼此理解同一套语言。

提示：MCP 的capability.json并非强制要求所有字段。最小可行版本只需包含name、input_schema和output_schema三个字段。但生产环境强烈建议补全description（能力用途说明）、version（语义化版本号）、tags（如["pdf", "parsing"]）和health_check_endpoint（健康检查路径）。这些字段虽不参与运行时调用，却是团队协作、CI/CD 集成和可观测性的基石。

2. 协议握手的本质：Capability Discovery 与 Runtime Negotiation

很多初学者把“MCP 协议握手”想象成一次性的 TCP 连接建立过程，比如三次握手那样发送 SYN、SYN-ACK、ACK 包。这种理解会直接导致架构设计失误。实际上，MCP 的握手是分阶段、可重入、上下文感知的动态协商过程，贯穿于 Agent 生命周期的始终。它分为两个核心阶段：Capability Discovery（能力发现）和Runtime Negotiation（运行时协商）。这两个阶段的目标、触发时机、交互内容和失败处理机制，完全不同。

2.1 Capability Discovery：静态元数据拉取，发生在 Agent 初始化阶段

这是最接近传统“握手”的环节，但它发生在应用启动时，而非每次调用前。LangGraph 的MCPClient初始化时，会向配置的 MCP Server 列表（如http://localhost:8000/mcp）发起一个 GET 请求，路径为/capabilities。Server 必须返回一个符合 MCP 规范的 JSON 数组，每个元素是一个完整的capability对象。例如：

[ { "name": "pdf_parse", "description": "解析PDF文本内容，支持OCR模式", "input_schema": { "type": "object", "properties": { "file_path": {"type": "string"}, "ocr_enabled": {"type": "boolean", "default": false} }, "required": ["file_path"] }, "output_schema": { "type": "object", "properties": { "text": {"type": "string"}, "page_count": {"type": "integer"} } }, "version": "1.2.0", "tags": ["pdf", "parsing", "ocr"], "health_check_endpoint": "/health" } ]

这个阶段的关键在于发现的不是服务地址，而是能力契约本身。LangGraph 拿到这个数组后，会做三件事：第一，构建本地能力索引缓存，避免重复请求；第二，根据tags和description进行能力匹配，比如用户说“请分析这份PDF”，系统自动关联到pdf_parse能力；第三，验证input_schema和output_schema的 JSON Schema 合法性，确保后续调用不会因结构错误崩溃。我见过太多团队在这里踩坑：Server 返回的input_schema缺少required字段，导致 LangGraph 生成的调用参数缺失必填项；或者version字段格式不规范（如"v1.2"），使得客户端无法正确执行语义化版本比较。这些都不是网络错误，而是契约定义不严谨引发的运行时故障。

2.2 Runtime Negotiation：动态参数协商，发生在每次具体调用前

当 LangGraph 决定调用pdf_parse时，真正的“握手”才开始。它不会直接 POST 数据，而是先向该能力的health_check_endpoint发起一个 HEAD 请求（或 GET，取决于 Server 实现）。这不是为了检查服务是否存活，而是为了获取当前运行时的协商参数。Server 的健康检查端点必须返回一个包含negotiation_params的 JSON，例如：

{ "status": "healthy", "negotiation_params": { "max_file_size_mb": 50, "supported_languages": ["zh", "en", "ja"], "streaming_supported": true } }

LangGraph 拿到这些参数后，会进行运行时决策：如果用户上传的 PDF 是 60MB，它会拒绝调用并提示“文件过大”；如果用户指定了language: "ko"，它会报错“不支持韩语”；如果用户请求流式输出，而streaming_supported为 false，它会自动降级为完整响应模式。这个过程就是“Runtime Negotiation”——它让能力调用不再是简单的“发请求-等响应”，而是变成了一个具备上下文感知、资源感知和策略感知的智能协商。我在一个金融风控 Agent 项目中就依赖这个机制：当实时交易风控能力在高负载时，其health_check_endpoint会动态返回{"throttling_factor": 0.3}，LangGraph 便自动将该能力的调用频率限制为原来的 30%，而不是粗暴地抛出 503 错误。这种柔性降级，正是 MCP 协议握手区别于传统 RPC 的核心优势。

注意：health_check_endpoint的响应时间必须严格控制在 100ms 以内。我们曾在线上环境观察到，某个 MCP Server 的健康检查因数据库慢查询耗时 800ms，导致整个 LangGraph 工作流卡顿。解决方案不是优化数据库，而是将健康检查逻辑移至内存缓存，并设置独立的超时熔断（timeout=100ms, max_retries=1）。记住，握手阶段的延迟，会直接放大为整个 Agent 响应时间的倍数。

3. LangGraph 多 Server 调用：不是简单串联，而是能力拓扑的动态编排

当标题提到“LangGraph 多 Server 调用”时，很多人下意识想到的是graph.add_node("server_a", ...)和graph.add_node("server_b", ...)的线性拼接。这完全低估了 LangGraph + MCP 组合的威力。真正的多 Server 调用，本质是基于能力语义的、图状拓扑的、运行时可变的动态编排。LangGraph 的StateGraph并不直接管理 Server，而是管理一组抽象的ToolNode，每个ToolNode的背后，都由 MCP Client 根据当前state中的tool_calls字段，动态解析、路由、调用对应的 MCP Server。这个过程涉及三个关键层次：能力路由（Routing）、拓扑生成（Topology Generation）和状态驱动（State-Driven Execution）。

3.1 能力路由：从自然语言到能力 ID 的精准映射

LangGraph 的ToolNode接收 LLM 输出的tool_calls，这是一个结构化的数组，例如：

[ {"name": "pdf_parse", "args": {"file_path": "/tmp/report.pdf"}}, {"name": "summarize_text", "args": {"text": "..."}} ]

这里的name字段，就是 MCP 能力的唯一标识符（capability.name）。LangGraph 的路由逻辑非常精巧：它首先在本地能力索引中查找pdf_parse，确认其存在且版本兼容；然后检查args是否符合input_schema的 JSON Schema 验证规则；最后，根据能力的tags和description，判断它是否属于当前工作流的“可信能力域”。比如，在一个医疗诊断 Agent 中，pdf_parse可能被允许，但execute_shell_command就会被路由层直接拦截——因为后者不在预设的allowed_tags=["pdf", "nlp", "medical"]白名单内。这个路由过程不是静态配置，而是每次调用都重新执行，确保了安全性和灵活性的统一。

3.2 拓扑生成：从线性流程到 DAG 的自动演化

LangGraph 的StateGraph本身就是一个有向无环图（DAG）。当多个tool_calls同时存在时，LangGraph 会根据能力之间的隐式依赖关系，自动生成最优执行拓扑。例如，LLM 输出了两个调用：

[ {"name": "web_scrape", "args": {"url": "https://news.example.com"}}, {"name": "search_knowledge_base", "args": {"query": "latest AI trends"}} ]

LangGraph 分析发现，web_scrape的输出html_content字段，恰好是search_knowledge_base的context字段的潜在输入源（通过output_schema和input_schema的字段名相似度匹配）。于是，它会自动将web_scrape的输出节点，连接到search_knowledge_base的输入节点，形成一个并行+串行混合的 DAG。更绝的是，如果web_scrape的health_check_endpoint返回{"streaming_supported": true}，而search_knowledge_base返回{"streaming_supported": false}，LangGraph 会自动插入一个StreamingBufferNode，将流式 HTML 内容暂存、聚合，再以完整字符串形式传递给下游。这种拓扑生成，完全脱离了开发者的手动add_edge操作，是 LangGraph 对 MCP 能力元数据深度理解后的智能推演。

3.3 状态驱动：执行结果如何反向塑造后续流程

多 Server 调用的终点，不是拿到结果就结束，而是将结果注入state，驱动下一步决策。MCP Server 的响应体，除了output字段，还必须包含metadata字段，用于携带执行上下文信息。例如：

{ "output": {"summary": "AI is transforming healthcare..."}, "metadata": { "execution_time_ms": 1247, "used_model": "gpt-4o-mini", "confidence_score": 0.92, "warnings": ["OCR accuracy low on page 3"] } }

LangGraph 的StateGraph会将整个响应对象（包括metadata）合并进state。后续的ConditionalEdge就可以基于这些元数据做分支判断。比如，一个新闻摘要 Agent 的条件边可以这样写：

def should_refine(state): # 如果置信度低于0.85，或者有警告，就进入refine节点 metadata = state.get("last_tool_result", {}).get("metadata", {}) return (metadata.get("confidence_score", 0) < 0.85 or len(metadata.get("warnings", [])) > 0) graph.add_conditional_edges( "tool_executor", should_refine, {"true": "refine_summary", "false": "end"} )

这种状态驱动的流程，让多 Server 调用不再是“黑盒串联”，而是一个具备自我反思、自我修正能力的闭环系统。我在一个法律合同审查 Agent 中就重度依赖此特性：当contract_analysis能力返回的metadata.warnings包含"ambiguous_clause_found"时，系统自动触发clause_expert_consultation能力，将模糊条款单独提取出来，交由领域专家模型二次审核。整个流程的复杂度，全部由 LangGraph 的状态机和 MCP 的元数据驱动，开发者只需关注能力本身的实现。

4. 从零搭建 MCP Server：一个可立即运行的 Python 示例

理解了 MCP 的理念和 LangGraph 的集成逻辑，下一步就是动手实践。很多开发者被“协议握手”、“多 Server 调用”这些术语吓住，以为需要复杂的框架或 SDK。事实上，一个符合 MCP 规范的最小可用 Server，用 Python 的 Flask 就能在 50 行代码内完成。下面这个示例，实现了pdf_parse能力，它接受一个 PDF 文件路径，返回文本内容，并完全遵循 MCP 的 Discovery 和 Negotiation 规范。

4.1 核心依赖与项目结构

首先，创建一个干净的虚拟环境，安装必要依赖：

python -m venv mcp_env source mcp_env/bin/activate # Windows: mcp_env\Scripts\activate pip install flask PyPDF2 python-magic

项目结构极其简单：

mcp_pdf_server/ ├── app.py # 主应用 ├── capabilities.json # 静态能力定义 └── requirements.txt

requirements.txt内容：

Flask==2.3.3 PyPDF2==3.0.1 python-magic==0.4.27

4.2 capabilities.json：能力契约的源头

这是 MCP 的灵魂文件，必须放在项目根目录。内容如下：

[ { "name": "pdf_parse", "description": "使用PyPDF2解析PDF文本内容，支持纯文本提取", "input_schema": { "type": "object", "properties": { "file_path": {"type": "string", "description": "PDF文件的绝对路径"}, "page_range": { "type": "array", "items": {"type": "integer"}, "description": "要解析的页码列表，如[0,1]表示第1、2页", "default": [] } }, "required": ["file_path"] }, "output_schema": { "type": "object", "properties": { "text": {"type": "string", "description": "提取的纯文本内容"}, "page_count": {"type": "integer", "description": "PDF总页数"}, "parsed_pages": {"type": "array", "items": {"type": "integer"}, "description": "实际解析的页码列表"} } }, "version": "1.0.0", "tags": ["pdf", "parsing"], "health_check_endpoint": "/health" } ]

注意：input_schema和output_schema必须是有效的 JSON Schema。我们特意加入了page_range参数和default值，展示了 MCP 如何支持可选参数，这比硬编码的 REST API 灵活得多。

4.3 app.py：50 行实现 MCP Server

from flask import Flask, request, jsonify, send_from_directory import os import json from PyPDF2 import PdfReader import magic app = Flask(__name__) # 1. 能力发现端点：返回 capabilities.json @app.route('/capabilities', methods=['GET']) def get_capabilities(): try: with open('capabilities.json', 'r') as f: caps = json.load(f) return jsonify(caps), 200 except Exception as e: return jsonify({"error": f"Failed to load capabilities: {str(e)}"}), 500 # 2. 健康检查端点：实现 Runtime Negotiation @app.route('/health', methods=['GET', 'HEAD']) def health_check(): # 模拟运行时协商参数 negotiation_params = { "max_file_size_mb": 10, "streaming_supported": False, "supported_mime_types": ["application/pdf"] } # 检查磁盘空间（简单模拟） free_space_gb = os.statvfs('/').f_frsize * os.statvfs('/').f_bavail / (1024**3) status = "healthy" if free_space_gb > 1 else "degraded" return jsonify({ "status": status, "negotiation_params": negotiation_params, "timestamp": int(os.time.time()) }), 200 # 3. 能力执行端点：处理 pdf_parse 调用 @app.route('/tool/pdf_parse', methods=['POST']) def pdf_parse(): try: data = request.get_json() if not data: return jsonify({"error": "Missing JSON payload"}), 400 file_path = data.get('file_path') if not file_path or not isinstance(file_path, str): return jsonify({"error": "Missing or invalid 'file_path' in input"}), 400 # 1. 验证文件存在且可读 if not os.path.exists(file_path): return jsonify({"error": f"File not found: {file_path}"}), 404 if not os.access(file_path, os.R_OK): return jsonify({"error": f"Permission denied: {file_path}"}), 403 # 2. 验证文件类型（防止任意文件读取） mime = magic.from_file(file_path, mime=True) if mime != 'application/pdf': return jsonify({"error": f"Invalid file type: {mime}. Expected application/pdf"}), 400 # 3. 解析PDF reader = PdfReader(file_path) text = "" page_range = data.get('page_range', []) parsed_pages = [] for i, page in enumerate(reader.pages): if not page_range or i in page_range: text += page.extract_text() or "" parsed_pages.append(i) # 4. 构建符合MCP规范的响应 result = { "output": { "text": text.strip(), "page_count": len(reader.pages), "parsed_pages": parsed_pages }, "metadata": { "execution_time_ms": 0, # 实际项目中应记录 "used_library": "PyPDF2", "warnings": [] if text.strip() else ["No text extracted from PDF"] } } return jsonify(result), 200 except Exception as e: return jsonify({"error": f"Internal server error: {str(e)}"}), 500 # 4. 静态文件服务（用于调试） @app.route('/<path:filename>') def static_files(filename): return send_from_directory('.', filename) if __name__ == '__main__': app.run(host='0.0.0.0', port=8000, debug=True)

4.4 启动与验证：三步走通 MCP 生命线

1. 启动 Server：在项目根目录执行python app.py，服务将在http://localhost:8000启动。

2. 验证 Discovery：打开浏览器或 curl，访问http://localhost:8000/capabilities。你应该看到完整的capabilities.json内容。这是 LangGraph 初始化时会拉取的源头。

3. 验证 Negotiation & Execution：用 curl 模拟一次完整调用：

   # 先检查健康状态 curl -X GET http://localhost:8000/health # 再执行能力调用（假设你有一个 test.pdf 文件） curl -X POST http://localhost:8000/tool/pdf_parse \ -H "Content-Type: application/json" \ -d '{"file_path": "/absolute/path/to/test.pdf"}'

这个 Server 完全符合 MCP 规范：它提供了capabilities端点、health端点，并且/tool/{name}的执行路径与capability.name严格对应。更重要的是，它包含了生产环境必需的安全检查（文件路径验证、MIME 类型校验）和错误处理（清晰的 4xx/5xx 状态码）。你可以把它作为模板，快速为 Playwright、SQL 查询、甚至本地 Shell 命令封装出 MCP Server。记住，MCP 的精髓不在于 Server 多复杂，而在于契约多清晰。一个定义良好的capabilities.json，比一百行业务逻辑代码更有价值。

提示：在生产环境中，务必替换magic.from_file为更安全的python-magic替代方案（如filetype库），并添加对file_path的路径遍历防护（如os.path.abspath(file_path).startswith("/safe/base/dir/")）。安全永远是能力开放的第一道防线。

5. 实战避坑指南：那些文档里不会写的 MCP 集成陷阱

理论和示例都很美好，但真实项目中的 MCP 集成，往往在细节处崩塌。我在三个大型 Agent 项目中，亲手填平了数十个 MCP 相关的坑。以下是最典型、最高频、也最容易被忽视的五个陷阱，每一个都附带了我亲测有效的解决方案。

5.1 陷阱一：input_schema的default字段被 LangGraph 忽略，导致参数缺失

现象：你在capabilities.json中为page_range设置了"default": []，但在 LangGraph 的tool_calls中，LLM 却没有生成这个字段。调用时，Server 收到的data字典里根本没有page_range键，直接KeyError。

根因：LangGraph 的ToolNode在构造调用参数时，只做 JSON Schema 的required字段校验，而完全不处理default字段。它认为默认值应该由 Server 端实现，而不是在客户端填充。这与 OpenAPI 规范的常见理解相悖。

解决方案：在 MCP Server 端，必须对所有可选参数做健壮的get()操作，并提供合理的默认值。不要依赖客户端传入。修改app.py中的pdf_parse函数：

# 错误写法（依赖客户端传 default） page_range = data['page_range'] # KeyError! # 正确写法（Server 端兜底） page_range = data.get('page_range', []) # 安全！

同时，在capabilities.json的input_schema中，default字段依然要保留，因为它对人类开发者和文档生成工具（如 Swagger UI）至关重要，只是不能指望 LangGraph 会用它。

5.2 陷阱二：health_check_endpoint的HEAD请求被 Nginx 拦截，返回 405

现象：本地测试一切正常，但部署到 Kubernetes 集群后，LangGraph 初始化时频繁报错HTTP 405 Method Not Allowed，指向/health端点。

根因：很多反向代理（如 Nginx、Traefik）默认禁用HEAD方法，只允许GET。而 LangGraph 的 MCP Client 默认发送HEAD请求以减少带宽消耗。当HEAD被拒，Client 会退化为GET，但如果 Server 的health_check_endpoint没有实现GET，就会彻底失败。

解决方案：在 Server 端，必须同时支持GET和HEAD方法。修改app.py：

# 将 @app.route('/health', methods=['GET', 'HEAD']) 保持不变 # 并确保函数体内部不依赖 request body（HEAD 请求没有 body） @app.route('/health', methods=['GET', 'HEAD']) def health_check(): # ... 函数体保持不变，它天然支持 GET 和 HEAD return jsonify({...}), 200

在 Nginx 配置中，显式允许HEAD：

location /health { proxy_pass http://mcp_backend; proxy_method GET; # 允许 GET # HEAD 会自动被允许，无需额外配置 }

5.3 陷阱三：MCP Server 的output_schema与 LangGraph 的Tool类型不匹配，引发pydantic校验失败

现象：LangGraph 报错ValidationError: 1 validation error for ToolResult output -> text field required，但你的 Server 明明返回了{"text": "..."}。

根因：LangGraph 的ToolNode在接收 MCP 响应后，会尝试用pydantic.BaseModel对output字段进行反序列化。如果你的output_schema定义了一个text字段为string，但 Server 实际返回的是null（比如 PDF 为空），pydantic就会因为field required而失败。output_schema是契约，但 Server 的实现可能不完美。

解决方案：在capabilities.json的output_schema中，对所有可能为null的字段，显式声明nullable: true。例如：

"output_schema": { "type": "object", "properties": { "text": {"type": ["string", "null"], "description": "提取的纯文本内容，可能为空"}, "page_count": {"type": "integer"} }, "required": ["page_count"] }

同时，在 Server 端，确保output字段的结构严格遵守这个 schema，宁可返回{"text": null}，也不要省略该字段。

5.4 陷阱四：多 Server 场景下，tool_calls的name冲突，导致路由错误

现象：你有两个 MCP Server，A Server 提供search能力，B Server 也提供search能力（一个是搜索知识库，一个是搜索数据库）。LangGraph 总是调用 A Server，即使意图是数据库搜索。

根因：MCP 的name字段是全局唯一的标识符。LangGraph 的能力索引是扁平化的，它只认name，不认 Server 地址。当两个 Server 都注册了同名能力时，后注册的那个会覆盖前者，或者引发未定义行为。

解决方案：强制实施命名空间（Namespace）策略。在capabilities.json中，为每个能力的name加上前缀，例如：

• A Server (http://kb-server:8000)："name": "kb_search"
• B Server (http://db-server:8000)："name": "db_search"

然后，在 LangGraph 的StateGraph中，LLM 的system_prompt必须明确告知其可用的能力名称：

You have access to these tools: - kb_search: Search the internal knowledge base. - db_search: Query the production database. Always use the exact tool name as listed above.

这是一种简单而强大的约定优于配置（Convention over Configuration）实践。

5.5 陷阱五：metadata字段被 LangGraph 丢弃，无法用于状态驱动

现象：你在 Server 的响应中精心构造了metadata，但state里只有output，metadata不翼而飞。

根因：LangGraph 的ToolNode默认只将output字段注入state。metadata是 MCP 规范的一部分，但 LangGraph 的基础ToolNode并不原生支持它。你需要一个自定义的ToolNode来捕获完整响应。

解决方案：创建一个继承自ToolNode的MCPToolNode，重写其invoke方法：

from langgraph.graph import ToolNode from typing import Any, Dict, List, Optional class MCPToolNode(ToolNode): def invoke(self, state: Dict[str, Any], config: Optional[Dict] = None) -> Dict[str, Any]: # 调用父类，获取原始响应 result = super().invoke(state, config) # 假设 result 是一个字典，包含 'output' 和 'metadata' # 这里需要根据你实际的 MCP Client 实现来调整 full_response = self._call_mcp_server(state) # 伪代码 # 将完整响应（含 metadata）注入 state state["last_tool_result"] = full_response return state # 在 graph 中使用 tool_node = MCPToolNode(tools=[...])

或者，更推荐的做法是，使用 LangGraph 的StateGraph的add_node直接调用你自己的 MCP Client，绕过ToolNode的限制，从而完全掌控响应的解析和注入逻辑。这牺牲了一点开箱即用的便利性，但换来了对 MCP 元数据的完全掌控。

这些陷阱，每一个都曾让我在凌晨三点的服务器日志里苦苦追寻。它们不是理论上的可能性，而是真实发生过的、让项目延期的硬伤。避开它们，不是靠读文档，而是靠一次又一次的实战踩坑。现在，我把这些经验毫无保留地分享出来，希望你能少走些弯路。