1. 项目概述为什么我们需要拆解 MCP 协议如果你最近在折腾 AI 开发工具比如 Cursor、Claude Desktop 或者 Windsurf大概率会频繁听到一个词MCP。它像一阵风迅速席卷了 AI 辅助编程的圈子。但当你兴致勃勃地想把自己的工具、数据库或者 API 也接入进去却发现官方文档读起来像天书社区里的讨论又零散不全最后只能对着一个“黑盒”望而兴叹。这正是我写这篇文章的初衷——把 MCPModel Context Protocol这个听起来高大上的协议从里到外、掰开揉碎地讲清楚。MCP 本质上是一个通信协议它的核心使命是让大语言模型比如 Claude、GPT能够安全、标准化地访问和使用外部工具、数据源和系统。你可以把它想象成 AI 的“USB 接口”或“插件系统”。在没有 MCP 之前每个 AI 应用想要扩展功能都需要开发者针对其特定的 API 进行定制化开发费时费力且难以复用。MCP 的出现就是为了制定一套通用的“插拔”标准。理解了协议本身你就能自己动手将任何内部工具、私有 API 甚至命令行脚本都变成 AI 的“手”和“眼”极大提升开发效率。本文不会停留在概念层面。我们将深入协议的核心剖析其基于 JSON-RPC 的通信机制对比 STDIO 和 HTTP 两种传输方式的选择与实战并详解资源Resources、工具Tools、提示词Prompts等核心概念。更重要的是我会分享在开发真实 MCP 服务器过程中踩过的坑、总结的最佳实践以及如何让你的服务器更健壮、更高效。无论你是想为自己的团队构建一个内部知识库查询工具还是想将公司特有的部署脚本 AI 化这篇文章都将是你不可或缺的指南。2. MCP 协议核心架构与设计哲学要拆开“黑盒”我们得先看看这个盒子是怎么设计的。MCP 的架构清晰地区分了三个角色客户端Client、服务器Server和传输层Transport。这种设计借鉴了经典的客户端-服务器模型并为其注入了适应 AI 工作流的特性。2.1 角色定义Client, Server 与 TransportMCP 服务器Server是能力的提供者。它“知道”如何做某些事情或访问某些数据。例如一个数据库 MCP 服务器知道如何连接数据库、执行查询并格式化结果一个文件系统 MCP 服务器知道如何遍历目录、读取文件内容。服务器对外暴露三类核心能力资源Resources、工具Tools和提示词Prompts。你可以把它看作是一个“能力池”。MCP 客户端Client是能力的消费者和使用者。通常这就是你使用的 AI 应用本身比如 Claude Desktop 或 Cursor。客户端的核心职责是管理会话、维护上下文、调用服务器提供的工具并将结果巧妙地整合到与用户的对话或代码编辑中。客户端负责发起通信并按照协议与一个或多个服务器交互。传输层Transport是连接客户端和服务器的桥梁。MCP 协议本身是传输无关的它只定义消息的格式和语义。具体的通信方式由传输层实现。目前官方主要支持两种方式STDIO标准输入输出和Streamable HTTP。STDIO 通常用于本地进程间通信简单直接而 HTTP 则用于远程或需要更复杂网络拓扑的场景。这种将协议与传输解耦的设计赋予了 MCP 极大的灵活性。2.2 协议基石JSON-RPC 2.0MCP 的所有通信都构建在JSON-RPC 2.0之上。这是一个轻量级的远程过程调用协议使用 JSON 作为数据格式。选择 JSON-RPC 2.0 是明智之举因为它简单、广泛支持并且完美匹配了 MCP 的请求-响应模式。每一个 MCP 消息都是一个 JSON-RPC 消息。它必须包含jsonrpc: “2.0”字段。消息主要分为两类请求Request由客户端发起调用服务器的一个方法。必须包含id用于匹配响应、method方法名和params参数。通知Notification一种没有响应的请求。用于单向通信比如服务器主动通知客户端某个资源已更新。它没有id字段。例如客户端初始化时发送的请求大致如下{ jsonrpc: 2.0, id: 1, method: initialize, params: { protocolVersion: 2024-11-05, capabilities: { // 客户端声明自己支持哪些功能 } } }服务器则会回复一个包含其自身能力的initialize响应。注意id字段在请求/响应中至关重要它确保了异步通信中的消息对应关系。在实现服务器时必须确保响应的id与请求的id严格一致。我见过不少自定义服务器出错都是因为id处理混乱导致客户端无法正确解析响应。2.3 核心能力模型Resources, Tools, Prompts这是 MCP 协议的灵魂所在它定义了服务器能提供什么。资源Resources资源代表可读的数据块具有唯一的 URI如file:///path/to/doc或memory://key。它们类似于网络上的文件或数据库中的记录。客户端可以“读取”资源内容。资源的核心特性是可订阅。服务器可以通知客户端某个资源的内容发生了变化例如一个被监控的日志文件更新了客户端从而可以获取最新内容实现数据的实时同步。这对于需要保持信息新鲜的场景如监控仪表盘、实时日志非常有用。工具Tools工具代表可执行的操作。客户端可以调用工具并传入参数。服务器执行操作可能产生副作用如写入文件、调用 API、执行命令并返回结果。这是 MCP 中最具交互性的部分。例如一个“执行 SQL 查询”的工具或一个“重启服务器”的工具。工具调用是 AI 代理Agent完成复杂任务的主要手段。提示词Prompts提示词是预定义的、参数化的对话模板。它们允许服务器为特定任务提供结构化的引导。当客户端请求一个提示词时服务器可以返回一组预设的消息通常包含系统提示和用户示例帮助 AI 更好地理解上下文和完成任务。这相当于服务器为 AI 准备了一个“任务说明书”或“对话剧本”。这种能力模型非常优雅地将“数据”Resources、“操作”Tools和“引导”Prompts分离开同时又允许它们协同工作。一个完整的 MCP 服务器通常会混合提供这些能力。3. 传输层深度解析STDIO vs. Streamable HTTP理解了协议内容我们再来看看协议如何“跑”起来。传输层的选择直接关系到部署复杂性、性能和适用场景。3.1 STDIO简单直接的本地通信STDIO 是 MCP 最常用、也是最简单的传输方式。客户端直接启动服务器进程并通过标准输入stdin、标准输出stdout和标准错误stderr与之通信。JSON-RPC 消息以换行符分隔的 JSON 文本形式在 stdin/stdout 管道中传递。它的工作流程是这样的客户端如 Claude Desktop根据配置启动指定的服务器可执行文件例如一个 Python 脚本。客户端通过stdin向服务器发送 JSON-RPC 请求。服务器从stdin读取请求处理逻辑然后将 JSON-RPC 响应写入stdout。客户端从stdout读取响应。任何调试或错误信息可以写入stderr客户端通常会将其记录到日志中。优点零配置无需处理网络端口、防火墙、认证。开箱即用。高安全进程隔离通信完全在本地进行没有网络暴露风险。低延迟进程间通信速度极快。缺点与注意事项生命周期绑定服务器进程的生命周期完全由客户端管理。客户端退出服务器进程也会被终止。缓冲问题这是一个巨大的坑必须确保写入 stdout 后立即刷新flush缓冲区。在 Python 中需要设置sys.stdout.reconfigure(line_bufferingTrue)或在每次print(json.dumps(...))后调用sys.stdout.flush()。在 Node.js 中也要注意流的缓冲。否则消息可能会卡在缓冲区导致客户端一直等待最终超时。错误处理服务器崩溃或抛出未捕获的异常客户端会感知到进程退出。良好的实践是在服务器入口点用try...except包裹将错误信息以结构化的 JSON-RPC 错误响应形式输出而不是让进程崩溃。一个简单的 Python STDIO 服务器骨架import sys import json def main(): # 设置行缓冲确保消息及时发出 sys.stdout.reconfigure(line_bufferingTrue) while True: line sys.stdin.readline() if not line: break try: request json.loads(line) # 处理 request 根据 method 调用不同函数 response handle_request(request) # 发送响应末尾必须换行 sys.stdout.write(json.dumps(response) “\n”) sys.stdout.flush() # 关键立即刷新 except Exception as e: # 发送错误响应 error_response { “jsonrpc”: “2.0”, “id”: request.get(“id”) if request else None, “error”: {“code”: -32603, “message”: str(e)} } sys.stdout.write(json.dumps(error_response) “\n”) sys.stdout.flush() if __name__ “__main__”: main()3.2 Streamable HTTP灵活强大的远程通信当你的 MCP 服务器需要运行在远程机器、容器内或者需要被多个客户端共享时STDIO 就不适用了。此时Streamable HTTP 模式登场。在这种模式下服务器作为一个标准的 HTTP 服务运行监听某个端口如 8080。客户端通过 HTTP POST 请求与服务器通信。关键在于这里使用的是Server-Sent Events (SSE)或类似的长连接流式机制以实现服务器向客户端的主动通知例如资源更新。典型的工作流程以 SSE 为例客户端向服务器的/messages端点发起一个GET请求建立一个 SSE 长连接。这个连接用于接收来自服务器的消息包括对客户端请求的响应以及服务器主动发出的通知。客户端向服务器的/messages端点发起另一个POST请求用于向服务器发送消息即 JSON-RPC 请求。此后客户端通过 POST 发送请求并通过 SSE 连接接收所有来自服务器的消息。一个连接用于发一个连接用于收实现了全双工通信。优点部署灵活服务器可以独立部署和运行客户端只需知道其网络地址。多客户端支持一个服务器实例可以同时服务多个客户端需注意资源竞争和状态管理。便于集成更容易融入现有的微服务架构或云原生环境。挑战与实战要点连接管理你需要妥善管理 SSE 连接的生命周期处理连接中断和重连。认证与授权HTTP 模式引入了网络安全问题。你通常需要实现 API 密钥、JWT 令牌等认证机制。切勿将未经验证的 MCP HTTP 服务器暴露在公网消息路由由于可能存在多个客户端服务器需要维护一个连接池并将响应和通知正确地路由到对应的客户端 SSE 连接。心跳与超时为了防止代理或负载均衡器断开空闲连接服务器通常需要定期通过 SSE 连接发送注释行 heartbeat\n作为心跳。选择建议开发调试、个人使用优先选择STDIO简单省心。团队共享、容器化部署、需要 24/7 运行选择Streamable HTTP。混合模式成熟的 MCP 服务器框架如官方 JavaScript/TypeScript SDK通常同时支持两种模式通过启动参数进行切换。4. 从零实现一个 MCP 服务器以“系统信息查询”为例理论说得再多不如动手实践。让我们来实现一个简单的 MCP 服务器它提供一个工具获取当前系统负载和一个资源显示服务器运行时间。我们将使用 Python 进行演示因为它易于理解。4.1 项目初始化与依赖首先创建一个新的项目目录并安装基础依赖。我们不需要复杂的框架使用标准库和psutil一个跨平台系统库即可。mkdir mcp-system-info-server cd mcp-system-info-server python -m venv venv source venv/bin/activate # Linux/Mac # venv\Scripts\activate # Windows pip install psutil创建主文件server.py。4.2 实现协议握手与初始化任何 MCP 会话都始于initialize握手。客户端会声明其能力服务器则回复自己支持的能力。# server.py import sys import json import time import psutil from datetime import datetime, timedelta class SystemInfoMCPServer: def __init__(self): self.start_time datetime.now() # 用于存储客户端支持的能力在 initialize 中获取 self.client_capabilities {} # 简单的请求处理器映射 self.handlers { “initialize”: self._handle_initialize, “tools/list”: self._handle_list_tools, “tools/call”: self._handle_call_tool, “resources/list”: self._handle_list_resources, “resources/read”: self._handle_read_resource, “notifications/initialized”: self._handle_initialized, “$/cancelRequest”: lambda _: None, # 处理取消请求简单忽略 } def _send_response(self, response): 发送 JSON-RPC 响应到 stdout sys.stdout.write(json.dumps(response) “\n”) sys.stdout.flush() def _handle_initialize(self, params): 处理初始化请求 self.client_capabilities params.get(“capabilities”, {}) # 构建服务器能力声明 server_capabilities { “resources”: {“subscribe”: False}, # 本例不实现订阅 “tools”: {}, “prompts”: {} # 本例不提供 prompts } return { “jsonrpc”: “2.0”, “id”: params[“_jsonrpc_id”], # 我们稍后会注入这个id “result”: { “protocolVersion”: “2024-11-05”, “capabilities”: server_capabilities, “serverInfo”: { “name”: “system-info-server”, “version”: “0.1.0” } } } def _handle_initialized(self, params): 客户端确认初始化完成可以开始发送通知了 # 本例中我们不需要在初始化后立即做什么 return None # 这是一个通知不需要响应_handle_initialize方法返回了服务器的基本信息和支持的能力。注意我们目前只声明了resources和tools并且关闭了资源订阅功能。4.3 实现工具Tools的列出与调用接下来我们实现工具相关的方法。首先服务器需要告诉客户端自己提供了哪些工具tools/list然后当客户端调用某个工具时tools/call需要执行相应的逻辑。def _handle_list_tools(self, params): 列出所有可用的工具 tools_list [ { “name”: “get_system_load”, “description”: “获取当前系统的平均负载1分钟5分钟15分钟和CPU使用率。”, “inputSchema”: { “type”: “object”, “properties”: {}, # 此工具不需要参数 “additionalProperties”: False } } ] return { “jsonrpc”: “2.0”, “id”: params[“_jsonrpc_id”], “result”: {“tools”: tools_list} } def _handle_call_tool(self, params): 调用指定的工具 tool_name params[“name”] arguments params.get(“arguments”, {}) if tool_name “get_system_load”: # 使用 psutil 获取系统负载和 CPU 使用率 load_avg psutil.getloadavg() # (1min, 5min, 15min) cpu_percent psutil.cpu_percent(interval0.1) result_content { “loadAverage”: { “1min”: round(load_avg[0], 2), “5min”: round(load_avg[1], 2), “15min”: round(load_avg[2], 2) }, “cpuUsagePercent”: cpu_percent, “timestamp”: datetime.now().isoformat() } # MCP 工具调用结果需要包装在特定的结构中 return { “jsonrpc”: “2.0”, “id”: params[“_jsonrpc_id”], “result”: { “content”: [ { “type”: “text”, “text”: json.dumps(result_content, indent2) } ] } } else: # 工具不存在返回错误 return { “jsonrpc”: “2.0”, “id”: params[“_jsonrpc_id”], “error”: { “code”: -32601, “message”: f“Tool not found: {tool_name}” } }在_handle_call_tool中我们返回的content是一个列表其中包含类型为“text”的对象。这是 MCP 协议规定的格式用于支持未来可能的多媒体内容。我们将结果以格式化的 JSON 字符串形式返回。4.4 实现资源Resources的列出与读取资源的实现与工具类似需要实现resources/list和resources/read。def _handle_list_resources(self, params): 列出所有可用的资源可选也可以根据URI模式动态列出 # 我们提供一个固定的资源服务器运行时间 resources_list [ { “uri”: “system://info/uptime”, “name”: “服务器运行时间”, “description”: “显示本 MCP 服务器自启动以来的运行时间。”, “mimeType”: “text/plain” } ] return { “jsonrpc”: “2.0”, “id”: params[“_jsonrpc_id”], “result”: {“resources”: resources_list} } def _handle_read_resource(self, params): 读取指定URI的资源内容 uri params[“uri”] if uri “system://info/uptime”: uptime datetime.now() - self.start_time # 将 timedelta 转换为易读的字符串 total_seconds int(uptime.total_seconds()) hours, remainder divmod(total_seconds, 3600) minutes, seconds divmod(remainder, 60) uptime_str f“{hours}小时 {minutes}分钟 {seconds}秒” content_text f“服务器启动于{self.start_time.isoformat()}\n已运行{uptime_str}” return { “jsonrpc”: “2.0”, “id”: params[“_jsonrpc_id”], “result”: { “contents”: [ { “uri”: uri, “mimeType”: “text/plain”, “text”: content_text } ] } } else: return { “jsonrpc”: “2.0”, “id”: params[“_jsonrpc_id”], “error”: { “code”: -32601, “message”: f“Resource not found: {uri}” } }资源读取的响应格式与工具调用略有不同它返回的是contents列表其中每个内容项都关联着一个uri和mimeType。4.5 主循环与消息分发最后我们将所有部分串联起来实现主循环来读取、解析和分发 JSON-RPC 消息。def run(self): 启动服务器主循环 sys.stdout.reconfigure(line_bufferingTrue) sys.stderr.reconfigure(line_bufferingTrue) print(f“[{datetime.now()}] MCP Server starting...”, filesys.stderr) while True: try: line sys.stdin.readline() if not line: print(“[Info] stdin closed, exiting.”, filesys.stderr) break line line.strip() if not line: continue request json.loads(line) method request.get(“method”) request_id request.get(“id”) # 可能是 None对于通知 # 将 request_id 注入到 params 中方便处理器使用 params request.get(“params”, {}) if isinstance(params, dict): params[“_jsonrpc_id”] request_id handler self.handlers.get(method) if handler: response handler(params) # 只有请求有id才需要响应通知无id不需要 if response and request_id is not None: self._send_response(response) elif request_id is None: # 这是一个通知处理了即可无需响应 pass else: # 有id的请求但处理器返回了None理论上不应该 pass else: # 方法未找到 if request_id is not None: error_resp { “jsonrpc”: “2.0”, “id”: request_id, “error”: { “code”: -32601, “message”: f“Method not found: {method}” } } self._send_response(error_resp) except json.JSONDecodeError as e: print(f“[Error] JSON decode failed: {e}, line: {line}”, filesys.stderr) # 对于无法解析的请求如果它有id返回解析错误 if “id” in request: error_resp { “jsonrpc”: “2.0”, “id”: request[“id”], “error”: {“code”: -32700, “message”: “Parse error”} } self._send_response(error_resp) except Exception as e: print(f“[Error] Unexpected error: {e}”, filesys.stderr) import traceback traceback.print_exc(filesys.stderr) # 对于处理过程中的内部错误 if request_id is not None: error_resp { “jsonrpc”: “2.0”, “id”: request_id, “error”: {“code”: -32603, “message”: f“Internal error: {str(e)}”} } self._send_response(error_resp) if __name__ “__main__”: server SystemInfoMCPServer() server.run()4.6 配置与测试现在我们需要配置一个 MCP 客户端例如 Claude Desktop来使用我们的服务器。找到 Claude Desktop 的配置文件位置通常位于~/Library/Application Support/Claude/claude_desktop_config.json或%APPDATA%\Claude\claude_desktop_config.json。编辑配置文件在mcpServers部分添加我们的服务器{ “mcpServers”: { “system-info”: { “command”: “python”, “args”: [“/绝对路径/to/your/mcp-system-info-server/server.py”], “env”: {} } } }保存配置并重启 Claude Desktop。在 Claude 的聊天窗口中你应该能看到新工具的出现。尝试输入“请使用get_system_load工具查看一下系统状态。” Claude 会调用该工具并返回系统负载信息。实操心得在开发 STDIO 服务器时最常遇到的问题就是“客户端无响应”。十有八九是缓冲区未刷新导致的。请务必确认你的stdout是行缓冲或每次写入后都手动flush()。另一个常见问题是 JSON 格式错误确保每个消息是完整的 JSON 对象并以换行符\n结尾。5. 高级主题与性能优化实现一个基础服务器只是第一步。要让它在生产环境中可靠运行还需要考虑更多。5.1 资源订阅Subscription的实现我们之前的例子关闭了订阅功能。实现订阅意味着服务器需要记住哪些客户端对哪些资源感兴趣并在资源变化时主动推送notifications/resources/updated通知。实现思路在服务器类中维护一个订阅字典self.subscriptions {}键为资源 URI值为订阅了该资源的客户端 ID 列表在 HTTP 模式下客户端 ID 可能是连接标识在 STDIO 模式下通常只有一个客户端。当客户端调用resources/subscribe请求时将其添加到对应 URI 的订阅列表中。当资源内容发生变化时例如你监控的日志文件有了新行遍历self.subscriptions[uri]向每个订阅的客户端发送通知。在 STDIO 模式下直接通过stdout发送通知。在 HTTP SSE 模式下需要通过对应的 SSE 连接发送。这是一个强大的特性能实现真正的实时数据流。例如一个监控服务器 CPU 使用率的资源可以每秒更新一次客户端AI就能持续获得最新数据用于生成动态报告。5.2 错误处理与健壮性一个健壮的 MCP 服务器必须能优雅地处理各种错误。协议错误如无效的 JSON、缺少必需字段、方法不存在等。必须按照 JSON-RPC 2.0 规范返回对应的错误码如 -32700 解析错误-32601 方法未找到。业务逻辑错误如工具调用参数验证失败、资源访问权限不足、外部服务不可用等。这些应使用自定义错误码在 -32000 到 -32099 的预留范围内或使用标准错误码并附带详细的data字段说明。连接保活与超时在 HTTP 模式下需要处理网络不稳定性。客户端可能会重连服务器应能处理重复的初始化请求并清理旧的订阅状态。输入验证与清理对于从客户端接收的任何参数尤其是工具参数都必须进行严格的验证和清理防止注入攻击。例如如果一个工具是执行系统命令绝不能直接将用户输入拼接进命令字符串。5.3 性能考量与异步处理如果工具调用或资源读取涉及耗时的 I/O 操作如网络请求、复杂数据库查询同步处理会阻塞整个服务器影响其他请求的响应。解决方案是采用异步Async模型。在 Python 中可以使用asyncio库。你需要将主循环改为异步循环使用asyncio.StreamReader和asyncio.StreamWriter来处理 stdin/stdout或者使用异步 HTTP 框架如 FastAPI、aiohttp来构建 HTTP 传输层。在 Node.js 中天然就是异步的使用async/await即可轻松处理。关键点在于当一个耗时请求在处理时服务器仍然可以接收和解析新的请求并将其分发给对应的异步任务处理。对于计算密集型操作甚至可以考虑引入线程池或进程池但要注意线程/进程间的状态同步问题。5.4 安全性最佳实践最小权限原则MCP 服务器进程应该以尽可能低的权限运行。特别是提供系统级工具如执行 shell 命令的服务器。输入验证如前所述这是安全的第一道防线。认证HTTP 模式务必使用强认证机制。最简单的可以使用静态 API 密钥通过 HTTP Header 传递复杂的可以集成 OAuth 2.0。传输加密HTTP 模式必须使用HTTPSTLS来加密通信防止中间人攻击。审计日志记录所有工具调用和敏感资源访问便于事后追溯和审计。沙箱化对于执行不可信代码的工具如运行用户提供的脚本应考虑在 Docker 容器或安全沙箱中运行。6. 调试技巧与常见问题排查开发 MCP 服务器时调试可能有些棘手因为通信是进程间或网络间的。以下是我总结的一些实用技巧。6.1 日志记录是生命线将详细的日志输出到stderr。客户端如 Claude Desktop通常会将这些日志收集起来你可以在其日志目录中找到。在代码的关键节点收到请求、开始处理、处理完成、发生错误打印日志。import logging logging.basicConfig(levellogging.DEBUG, format‘%(asctime)s - %(levelname)s - %(message)s’) logger logging.getLogger(__name__) # 使用 logger.debug(“Received request: %s”, request) 代替 print6.2 使用“回显”测试服务器在开发初期可以写一个简单的测试脚本来模拟客户端验证服务器的基本通信。# test_client.py import subprocess import json import time def test_stdio_server(server_path): proc subprocess.Popen( [‘python’, server_path], stdinsubprocess.PIPE, stdoutsubprocess.PIPE, stderrsubprocess.PIPE, textTrue ) def send(req): print(“-”, req) proc.stdin.write(json.dumps(req) “\n”) proc.stdin.flush() def recv(): line proc.stdout.readline() print(“-“, line.strip()) return json.loads(line) if line else None # 1. 发送 initialize init_req { “jsonrpc”: “2.0”, “id”: 1, “method”: “initialize”, “params”: {“protocolVersion”: “2024-11-05”, “capabilities”: {}} } send(init_req) recv() # 2. 发送 initialized 通知 send({“jsonrpc”: “2.0”, “method”: “notifications/initialized”, “params”: {}}) # 3. 列出工具 list_req {“jsonrpc”: “2.0”, “id”: 2, “method”: “tools/list”, “params”: {}} send(list_req) recv() # 4. 调用工具 call_req {“jsonrpc”: “2.0”, “id”: 3, “method”: “tools/call”, “params”: {“name”: “get_system_load”, “arguments”: {}}} send(call_req) recv() proc.terminate() if __name__ “__main__”: test_stdio_server(“./server.py”)6.3 常见问题速查表问题现象可能原因排查步骤客户端提示“无法连接服务器”或“服务器未响应”1. 配置文件路径或命令错误。2. 服务器脚本存在语法错误启动即崩溃。3. 服务器进程启动但立即退出。1. 检查配置文件中的command和args路径是否正确。2. 直接在终端运行服务器命令看是否有 Python 语法报错。3. 在服务器脚本开头添加import time; time.sleep(10)并配置客户端连接看客户端是否在10秒后报错说明进程存活然后检查服务器日志。客户端连接成功但看不到工具/资源1. 服务器initialize响应中未正确声明能力。2.tools/list或resources/list响应格式错误。1. 用测试客户端检查initialize的响应确认capabilities字段存在且正确。2. 检查tools/list返回的 JSON 结构是否符合协议{“tools”: [...]}。调用工具时超时或无结果1. 服务器处理工具时卡住死循环、阻塞 IO。2. 工具处理完成但响应未正确输出缓冲区未刷新。3. 响应 JSON 格式错误。1. 查看服务器 stderr 日志确认是否进入工具处理函数。2.重点检查确保在stdout.write()后执行了flush()。3. 将服务器响应的 JSON 字符串复制到 JSON 验证器如 jsonlint.com检查。HTTP 模式连接失败1. 服务器未启动或端口被占用。2. 防火墙/网络策略阻止。3. 认证失败。1. 用curl或浏览器访问服务器的/messages端点GET 和 POST看是否返回预期结果或错误。2. 检查服务器日志中的认证相关错误。6.4 利用现有 SDK 加速开发从头实现协议解析和状态管理虽然有助于理解但在生产环境中更推荐使用官方或社区维护的SDK。它们处理了协议细节、错误处理、传输层等繁琐工作让你专注于业务逻辑。TypeScript/Node.js: 官方提供了modelcontextprotocol/sdk这是功能最全、最权威的 SDK。Python: 社区有mcp库但成熟度相对较低。你也可以参考我们上面的示例作为起点。其他语言: 社区正在积极为 Rust、Go、Java 等语言开发 SDK。使用 SDK 通常只需要你定义工具函数和资源获取函数然后调用几行代码来注册和启动服务器能节省大量时间并减少出错概率。拆解 MCP 协议的过程就像在组装一个精致的模型。从理解 JSON-RPC 这个通用接口到选择 STDIO 或 HTTP 这条数据通道再到精心设计 Resources、Tools、Prompts 这些功能模块每一步都需要对细节的把握和对整体架构的理解。我个人的体会是最开始可能会被其抽象性吓到但一旦亲手实现一个哪怕最简单的服务器并看到它在 Claude 或 Cursor 里活起来那种通透感和掌控感是非常棒的。这个协议的魅力在于它的简洁和强大它用一套相对简单的规范为 AI 打开了一扇通往无限可能世界的大门。当你掌握了它你就不仅仅是 AI 的使用者更是其能力的塑造者和扩展者。