1. 从“能跑”到“敢上线”MCP Server 的四个断层很多开发者第一次接触 MCP Server 的时候都会经历一个极其相似的阶段照着官方文档把示例代码复制下来本地起一个进程用客户端连上去工具列表能拉出来调用一个最简单的 echo 或者 add 方法返回结果正确。那一刻的感觉是“我懂了这东西不难”。然后你把它接到真实的工作流里问题就开始一个接一个地冒出来。客户端偶尔连不上工具调用超时了没有任何反馈参数传错了直接抛一个看不懂的堆栈多个客户端同时连过来的时候行为诡异日志里什么都看不到出了问题只能靠猜。这时候你才意识到之前那个“跑通”的版本和生产环境之间隔着的不是一行配置而是一整套工程化的思考。MCPModel Context ProtocolServer 的本质是什么它是一个对外暴露能力的服务端进程客户端通过标准协议来发现和调用你注册的工具、资源和提示模板。它和普通的 HTTP API 有一个关键区别MCP 的调用方通常是 AI 应用或者自动化编排系统这意味着调用行为更加不可预测参数组合更加发散错误处理的要求也更高。一个 HTTP API 如果参数错了前端可以弹个提示让用户改但 MCP Server 面对的是一个自动化的调用方它不会“问用户”它只会根据你返回的结果决定下一步。你返回的东西质量如何直接决定了整个链路的可靠性。所以这篇文章想聊的不是“怎么写出第一个 MCP Server”而是“你那个已经能跑的 MCP Server距离生产级还差哪几步”。我会围绕四个核心断层来展开连接生命周期的管理、工具描述的精确性、错误处理与可观测性、以及并发与资源控制。这四个方向不是拍脑袋想出来的而是我在把几个 MCP Server 从 demo 推到实际使用的过程中反复踩坑之后总结出来的。每一个断层我都会讲清楚它为什么重要、常见做法哪里有问题、以及我会怎么改。如果你现在手里的 MCP Server 还停留在“本地能跑通”的阶段这篇文章应该能帮你省下不少调试时间。如果你已经上线了一段时间但总觉得不够稳也可以对照着看看哪个环节还有欠账。2. 连接生命周期为什么你的 Server 总是“第一次好用第二次就出问题”2.1 传输层选择背后的真实取舍MCP 支持多种传输方式最常见的是 stdio 和基于 HTTP 的 SSEServer-Sent Events。很多人在选的时候只看“哪个简单”但实际上这两个传输方式的适用场景和坑点完全不同。stdio 传输的意思是客户端启动你的 Server 进程通过标准输入输出进行通信。这种方式的好处是简单直接不需要网络配置不需要端口管理进程的生命周期和客户端绑定。但它的限制也很明显一个 Server 进程只能服务一个客户端而且如果客户端崩溃了没有正确关闭管道你的 Server 进程可能会变成孤儿进程一直挂着。SSE 传输则是你的 Server 作为一个独立的 HTTP 服务运行客户端通过网络连接过来。这种方式支持多个客户端同时连接Server 的生命周期独立于客户端。但问题在于SSE 是一个长连接连接的管理、心跳的维护、断线重连的处理都需要你自己来管。我见过不少人用 stdio 做开发然后直接换成 SSE 部署到服务器上结果发现行为完全不一样。stdio 模式下你不需要考虑连接状态因为进程就是连接但 SSE 模式下连接是一个需要你主动管理的资源。如果你只是做本地工具集成stdio 就够了别给自己找麻烦。但如果你要让多个客户端或者远程客户端访问SSE 是必须的这时候连接管理就不是可选项而是必选项。2.2 会话初始化阶段的隐藏陷阱MCP 协议有一个初始化握手的过程客户端发送 initialize 请求Server 返回自己的能力信息然后客户端发送 initialized 通知之后才能正常调用工具。这个流程看起来很简单但实际实现的时候有几个容易忽略的点。第一个点是能力声明的准确性。在 initialize 响应里你需要声明自己支持哪些能力比如 tools、resources、prompts 等。如果你声明了 tools 但实际上没有正确注册任何工具客户端可能会在后续调用中出现意料之外的行为。反过来如果你实际有工具但没有声明 tools 能力客户端根本不会去查询你的工具列表。第二个点是初始化超时。有些客户端在 initialize 阶段有比较严格的超时限制如果你的 Server 在启动时需要做一些耗时的初始化操作比如加载模型、连接数据库这些操作如果放在 initialize 请求的处理路径里很容易导致握手超时。正确的做法是把这些耗时操作放在 Server 进程启动阶段完成initialize 请求的处理应该尽可能轻量。第三个点是重复初始化。SSE 模式下同一个客户端可能因为网络抖动而重新发送 initialize 请求。如果你的 Server 没有正确处理这种情况可能会创建多个会话状态导致后续调用行为混乱。我的做法是给每个会话分配一个唯一的 session ID在 initialize 时返回给客户端后续请求都带上这个 IDServer 根据 ID 来查找和维护会话状态。2.3 断线重连与会话恢复的工程实践SSE 连接断开是必然会发生的事情问题只是什么时候发生。你的 Server 需要能够处理两种情况客户端主动断开和网络异常断开。对于客户端主动断开你需要及时清理对应的会话资源避免内存泄漏。对于网络异常断开你需要考虑是否支持会话恢复。MCP 协议本身没有强制要求会话恢复机制但在生产环境中如果一个长连接断了之后客户端需要重新初始化、重新拉取工具列表、重新建立上下文这个开销是很大的。我的做法是在 Server 端维护一个会话表每个会话有一个过期时间。当连接断开时不立即销毁会话而是标记为“断连”状态保留一段时间。如果客户端在过期时间内重新连接并带上之前的 session ID就恢复会话如果超时了还没有重连再清理资源。这个过期时间需要根据实际场景来定太短了起不到恢复的作用太长了会占用不必要的资源。一般来说几分钟到十几分钟是一个比较合理的范围。另外要注意的是会话恢复不仅仅是恢复连接状态还需要考虑在断连期间产生的状态变化。比如你的 Server 在断连期间执行了某个长时间任务重连之后客户端需要知道这个任务的状态。这需要在会话状态里维护一个操作日志或者状态快照重连时同步给客户端。3. 工具描述调用方不是人它只看你写了什么3.1 工具名称与描述的“机器可读性”这是最容易被低估的一个环节。很多人在写工具定义的时候习惯性地用人类可读的方式来命名和描述比如工具名叫doStuff描述写“处理一些东西”。这种写法对人来说可能勉强能理解但对一个 AI 调用方来说信息量几乎为零。MCP 的工具定义包含名称、描述和参数 schema。调用方通常是 LLM会根据这些信息来决定是否调用这个工具、传什么参数。如果你的描述模糊不清调用方要么不敢调用要么传错参数。这不是调用方的问题是你的描述没有做到“机器可读”。什么叫机器可读就是描述里要明确说清楚这个工具做什么、什么时候应该用它、什么时候不应该用它、每个参数的含义和格式、返回值的结构。我举个例子对比一下{ name: search, description: 搜索东西, inputSchema: { type: object, properties: { q: { type: string } } } }这个定义的问题在于搜索什么在哪里搜索q 是什么格式返回什么调用方看到这个定义只能靠猜。{ name: search_documents, description: 在内部文档库中按关键词搜索文档。当用户询问需要查阅内部资料的问题时使用此工具。返回匹配文档的标题、摘要和链接。如果不需要查阅内部资料不要使用此工具。, inputSchema: { type: object, properties: { query: { type: string, description: 搜索关键词支持多个关键词用空格分隔例如部署 流程 }, max_results: { type: integer, description: 返回的最大结果数量默认 5最大 20, default: 5 } }, required: [query] } }第二个定义明显更好。它不仅说清楚了工具的功能还给出了使用场景的边界“当用户询问需要查阅内部资料的问题时使用”参数格式有示例默认值和取值范围也标明了。这些信息对调用方来说都是决策依据。3.2 参数 Schema 设计中的常见错误参数 schema 是工具定义中最容易出问题的地方。我总结了几类常见错误。第一类是类型不精确。比如一个参数应该是枚举值但你写成了 string调用方可能会传入任意字符串。正确的做法是用 enum 约束取值范围{ format: { type: string, enum: [json, markdown, plain], description: 返回内容的格式 } }第二类是缺少必填标记。有些参数是必须的但你没有放在 required 数组里调用方可能不传然后你的代码在运行时才报错。应该在 schema 层面就把必填项标清楚让调用方在构造请求时就知道哪些是必须的。第三类是嵌套结构过于复杂。有些工具的参数是一个深层嵌套的对象调用方很容易在嵌套层级上出错。如果可能的话尽量把参数扁平化或者提供多个简单的工具而不是一个复杂的工具。第四类是缺少参数间的约束说明。比如参数 A 和参数 B 互斥或者参数 C 在参数 D 为某个值时才有效。这些约束如果不在描述里写清楚调用方很可能会传入无效的组合。虽然 JSON Schema 本身对跨字段约束的支持有限但你可以在 description 里用自然语言说明。3.3 工具粒度的取舍一个大的还是多个小的这个问题没有标准答案但有一个判断原则如果一个工具的调用需要调用方先做很多前置判断才能确定参数那可能应该拆成多个工具。举个例子假设你有一个“查询数据”的工具它支持按不同维度查询按 ID 查、按名称查、按时间范围查。你可以做成一个工具参数里有一个query_type字段来决定用哪种查询方式也可以做成三个独立的工具get_by_id、get_by_name、get_by_time_range。前者的问题是调用方需要理解query_type和各个参数之间的对应关系容易传错。后者的好处是每个工具的参数都很清晰调用方只需要根据当前场景选择对应的工具。代价是工具列表变长了调用方需要在更多选项里做选择。我的经验是当不同查询方式的参数差异很大时拆成多个工具当参数差异很小时合并成一个工具。比如按 ID 查只需要一个 id 参数按时间范围查需要 start 和 end 两个参数这两种情况差异较大拆开更好。但如果只是排序字段不同参数结构基本一样合并成一个工具加一个 sort_by 参数就够了。还有一个相关的考虑是工具的数量。有些客户端在工具数量很多的时候调用方的选择准确率会下降。如果你的 Server 注册了几十个工具可能需要考虑分组或者提供某种导航机制。不过这是调用方侧的问题作为 Server 端你能做的是确保每个工具的描述足够清晰让调用方能够准确区分。4. 错误处理与可观测性出问题的时候你能看到什么4.1 MCP 错误响应的正确构造方式MCP 协议对错误响应有明确的格式要求。一个常见的错误做法是在工具执行出错时直接抛一个异常让框架去处理。这样做的结果是调用方收到的错误信息可能是一个通用的内部错误没有任何有用的上下文。正确的做法是区分协议层错误和工具执行错误。协议层错误是指请求格式不对、方法不存在、参数不符合 schema 等这些应该返回标准的 JSON-RPC 错误码。工具执行错误是指工具本身的逻辑出错了比如查询不到数据、外部服务不可用等这些应该作为工具调用的正常返回但在返回内容里标明错误状态。# 不推荐直接抛异常 async def handle_tool_call(name, arguments): result do_something(arguments) # 如果这里抛异常调用方收到的是通用错误 return result # 推荐区分错误类型返回结构化错误信息 async def handle_tool_call(name, arguments): try: result do_something(arguments) return {content: [{type: text, text: result}]} except ValidationError as e: return { content: [{type: text, text: f参数校验失败: {e.message}}], isError: True } except ExternalServiceError as e: return { content: [{type: text, text: f外部服务暂时不可用: {e.service_name}请稍后重试}], isError: True }这样做的意义在于调用方能够根据错误信息做出不同的决策。参数校验失败可能需要修改参数重试外部服务不可用可能需要等待或者换一个工具而一个通用的“内部错误”让调用方完全无法判断下一步该怎么做。4.2 日志与追踪让每一次调用都有迹可循MCP Server 的日志有一个特殊之处你不能往标准输出写日志stdio 模式下标准输出是协议通信通道必须写到标准错误或者文件。这一点如果搞错了会导致协议通信被日志内容污染客户端解析失败。在 SSE 模式下虽然没有这个限制但日志的规范性同样重要。我建议在日志里至少包含以下信息请求 ID每次工具调用生成一个唯一 ID方便串联同一次调用的所有日志会话 ID标识是哪个客户端发起的调用工具名称调用了哪个工具参数摘要参数的关键信息注意脱敏不要记录敏感数据执行耗时从收到请求到返回响应的总时间结果状态成功还是失败失败的话错误类型是什么这些信息看起来简单但在排查问题的时候非常有用。比如你发现某个工具偶尔超时通过日志可以看到是特定参数组合导致的还是所有调用都慢还是某个时间段集中出现。没有这些日志你只能靠猜。对于更复杂的场景可以考虑引入分布式追踪。每次工具调用生成一个 trace如果工具内部还调用了其他服务把子调用的 span 关联起来。这样可以看到整个调用链的耗时分布快速定位瓶颈在哪个环节。4.3 健康检查与就绪探针的落地细节如果你的 MCP Server 是以 SSE 模式运行的独立服务那么健康检查和就绪探针是必须的。健康检查用来判断进程是否还活着就绪探针用来判断服务是否已经准备好接受请求。健康检查的实现很简单暴露一个 HTTP 端点返回 200 就行。但就绪探针需要更细致的考虑你的 Server 在什么状态下才算“就绪”是进程启动完成了就算还是所有工具都注册好了才算还是依赖的外部服务都连通了才算我的做法是把就绪状态分为几个级别进程启动完成、工具注册完成、外部依赖连通。只有三个级别都满足时才返回就绪。如果某个外部依赖暂时不可用Server 可以返回“降级就绪”并在响应里标明哪些能力当前不可用。这样调用方可以根据自己的需求决定是否使用这个 Server。就绪探针不要做得太重。有些实现会在就绪探针里做一次完整的端到端测试调用这会导致探针本身成为性能瓶颈。探针应该只检查关键依赖的连通性不需要验证完整的业务逻辑。5. 并发与资源控制当多个调用同时打过来5.1 工具执行的并发模型选择MCP Server 需要处理并发请求这一点在 SSE 模式下尤其明显。并发模型的选择直接影响 Server 的吞吐量和稳定性。最简单的模型是串行处理收到一个请求处理完再处理下一个。这种模型实现简单不存在并发问题但吞吐量极低。如果一个工具调用需要几秒钟那同时来的其他请求就只能等着。稍微好一点的是线程池模型每个请求分配一个线程线程池的大小决定了最大并发数。这种模型适合 IO 密集型的工具比如网络请求、文件读写因为线程在等待 IO 的时候可以让出 CPU。但如果工具是 CPU 密集型的线程数超过 CPU 核心数反而会导致上下文切换开销。对于 Python 这样的语言还需要考虑 GIL 的影响。如果工具执行涉及大量 CPU 计算多线程并不能真正并行。这时候可能需要用多进程或者异步 IO 来提升并发能力。我的建议是根据工具的类型来选择并发模型。如果大部分工具是 IO 密集型的用异步 IOasyncio是最合适的单线程就能处理很高的并发。如果工具有 CPU 密集型的操作考虑把这些操作放到单独的进程池里执行避免阻塞事件循环。5.2 超时控制与取消传播超时控制是生产级 MCP Server 的必备能力。没有超时控制一个卡住的工具调用可能会占用资源直到天荒地老。超时控制需要分层设置连接超时、请求超时、工具执行超时。连接超时是指客户端建立连接的时间限制请求超时是指从收到请求到返回响应的总时间限制工具执行超时是指工具内部逻辑的执行时间限制。这三个超时的关系是连接超时 请求超时工具执行超时 请求超时。如果工具执行超时了Server 应该主动中断执行并返回超时错误而不是等请求超时了才被动断开。取消传播是另一个相关的问题。当客户端取消一个请求时比如用户手动中断了操作这个取消信号应该能够传播到工具的执行逻辑里。如果你的工具在执行一个长时间的操作收到取消信号后应该尽快停止并清理资源。这需要在工具的实现里支持取消检查比如定期检查一个 cancel token 的状态。async def long_running_tool(params, cancel_token): for i in range(1000): if cancel_token.is_cancelled(): raise CancelledError(操作已被取消) await do_step(i) return 完成5.3 资源配额与限流策略如果你的 MCP Server 是对外提供服务的资源配额和限流是保护自己的必要手段。没有限流一个异常客户端可能会耗尽所有资源导致其他客户端无法使用。限流可以从几个维度来做并发请求数限制、单位时间请求数限制、单个请求的资源消耗限制。并发请求数限制是最基本的防止同时处理太多请求导致内存溢出。单位时间请求数限制用来防止某个客户端高频调用。单个请求的资源消耗限制包括执行时间限制、内存使用限制、返回数据大小限制等。实现限流的时候要注意限流本身也会消耗资源。如果限流逻辑太重反而会成为瓶颈。对于简单的场景一个基于内存的计数器就够了。对于更复杂的场景可能需要引入令牌桶或者漏桶算法。还有一个容易被忽略的点是限流的反馈。当请求被限流时返回的错误信息应该明确告诉调用方是限流导致的以及建议的重试时间。这样调用方可以做出合理的退避决策而不是立即重试导致更严重的拥塞。控制维度推荐策略注意事项并发请求数根据内存和 CPU 核数设定上限留出余量给系统本身请求频率令牌桶按客户端维度限流区分不同客户端的配额执行时间分层超时工具级 请求级超时后要能中断执行返回大小限制单次返回的数据量超大结果考虑分页内存使用监控 硬限制防止 OOM 导致进程崩溃6. 把这些串起来一个可落地的改造清单6.1 优先级排序先改什么后改什么如果你手里的 MCP Server 已经能跑通但还没做生产级改造不要试图一次性把所有东西都改完。我的建议是按以下优先级来推进第一优先级错误处理与日志。这是投入产出比最高的改造。你不需要改变架构只需要在现有的工具处理逻辑里加上结构化的错误返回和关键日志。改完之后你至少能在出问题的时候知道发生了什么。第二优先级超时控制。给每个工具调用加上超时限制防止单个请求卡死整个 Server。这个改造也不复杂但能显著提升稳定性。第三优先级连接生命周期管理。如果你用的是 SSE 模式会话管理和断线重连是必须的。如果你用的是 stdio 模式这部分可以暂时跳过。第四优先级并发控制与限流。这部分在早期用户量不大的时候可以缓一缓但一旦有多个客户端同时使用就需要尽快补上。第五优先级工具描述的优化。这是一个持续改进的过程不需要一次性做完但每次发现调用方用错工具或者传错参数的时候都应该回头看看是不是描述不够清晰。6.2 改造过程中的验证方法每做一项改造都需要有对应的验证方法。不能改完了觉得“应该没问题”就上线了。对于错误处理可以构造各种异常场景来测试传非法参数、模拟外部服务超时、模拟内部逻辑异常看返回的错误信息是否清晰、是否包含足够的上下文。对于超时控制可以故意写一个会 sleep 很久的工具看 Server 是否能在超时后正确返回错误以及资源是否被正确释放。对于会话管理可以模拟连接断开和重连看会话状态是否正确恢复以及过期会话是否被正确清理。对于并发控制可以用压力测试工具模拟多个客户端同时调用观察 Server 的响应时间和资源使用情况确认没有出现死锁或者资源泄漏。这些验证不需要很复杂的工具很多时候写几个测试脚本就够了。关键是要有验证的意识而不是改完就完事。6.3 我踩过的几个印象深刻的坑最后分享几个我在改造过程中踩过的坑希望能帮你省点时间。第一个坑是在 stdio 模式下往标准输出打日志。这个坑很隐蔽因为本地测试的时候可能不会出问题但一旦日志量大了协议通信就会被污染客户端会收到无法解析的内容。解决方法是把所有日志都写到标准错误或者文件标准输出只用于协议通信。第二个坑是会话过期时间设得太短。我一开始设了 30 秒结果发现客户端稍微网络抖动一下会话就过期了重连之后所有状态都丢了。后来改成 5 分钟体验好了很多。这个值需要根据实际网络环境和客户端行为来调整。第三个坑是工具描述里用了太多专业术语。我以为调用方能够理解这些术语但实际上调用方在决定是否使用某个工具的时候依赖的是描述里的自然语言。如果描述里全是术语调用方可能无法准确判断这个工具是否适合当前场景。后来我把描述改得更直白调用准确率明显提升了。第四个坑是没有限制单个请求的返回数据量。有一个工具会返回一个很大的 JSON结果调用方在处理的时候内存爆了。后来加上了分页和大小限制问题就解决了。这个坑让我意识到Server 端不仅要考虑自己不出问题还要考虑返回的数据对调用方是否友好。这些坑说起来都不复杂但都是在实际运行中才会暴露出来的。希望你在改造自己的 MCP Server 的时候能够提前避开。
1. 从“能跑”到“敢上线”MCP Server 的四个断层很多开发者第一次接触 MCP Server 的时候都会经历一个极其相似的阶段照着官方文档把示例代码复制下来本地起一个进程用客户端连上去工具列表能拉出来调用一个最简单的 echo 或者 add 方法返回结果正确。那一刻的感觉是“我懂了这东西不难”。然后你把它接到真实的工作流里问题就开始一个接一个地冒出来。客户端偶尔连不上工具调用超时了没有任何反馈参数传错了直接抛一个看不懂的堆栈多个客户端同时连过来的时候行为诡异日志里什么都看不到出了问题只能靠猜。这时候你才意识到之前那个“跑通”的版本和生产环境之间隔着的不是一行配置而是一整套工程化的思考。MCPModel Context ProtocolServer 的本质是什么它是一个对外暴露能力的服务端进程客户端通过标准协议来发现和调用你注册的工具、资源和提示模板。它和普通的 HTTP API 有一个关键区别MCP 的调用方通常是 AI 应用或者自动化编排系统这意味着调用行为更加不可预测参数组合更加发散错误处理的要求也更高。一个 HTTP API 如果参数错了前端可以弹个提示让用户改但 MCP Server 面对的是一个自动化的调用方它不会“问用户”它只会根据你返回的结果决定下一步。你返回的东西质量如何直接决定了整个链路的可靠性。所以这篇文章想聊的不是“怎么写出第一个 MCP Server”而是“你那个已经能跑的 MCP Server距离生产级还差哪几步”。我会围绕四个核心断层来展开连接生命周期的管理、工具描述的精确性、错误处理与可观测性、以及并发与资源控制。这四个方向不是拍脑袋想出来的而是我在把几个 MCP Server 从 demo 推到实际使用的过程中反复踩坑之后总结出来的。每一个断层我都会讲清楚它为什么重要、常见做法哪里有问题、以及我会怎么改。如果你现在手里的 MCP Server 还停留在“本地能跑通”的阶段这篇文章应该能帮你省下不少调试时间。如果你已经上线了一段时间但总觉得不够稳也可以对照着看看哪个环节还有欠账。2. 连接生命周期为什么你的 Server 总是“第一次好用第二次就出问题”2.1 传输层选择背后的真实取舍MCP 支持多种传输方式最常见的是 stdio 和基于 HTTP 的 SSEServer-Sent Events。很多人在选的时候只看“哪个简单”但实际上这两个传输方式的适用场景和坑点完全不同。stdio 传输的意思是客户端启动你的 Server 进程通过标准输入输出进行通信。这种方式的好处是简单直接不需要网络配置不需要端口管理进程的生命周期和客户端绑定。但它的限制也很明显一个 Server 进程只能服务一个客户端而且如果客户端崩溃了没有正确关闭管道你的 Server 进程可能会变成孤儿进程一直挂着。SSE 传输则是你的 Server 作为一个独立的 HTTP 服务运行客户端通过网络连接过来。这种方式支持多个客户端同时连接Server 的生命周期独立于客户端。但问题在于SSE 是一个长连接连接的管理、心跳的维护、断线重连的处理都需要你自己来管。我见过不少人用 stdio 做开发然后直接换成 SSE 部署到服务器上结果发现行为完全不一样。stdio 模式下你不需要考虑连接状态因为进程就是连接但 SSE 模式下连接是一个需要你主动管理的资源。如果你只是做本地工具集成stdio 就够了别给自己找麻烦。但如果你要让多个客户端或者远程客户端访问SSE 是必须的这时候连接管理就不是可选项而是必选项。2.2 会话初始化阶段的隐藏陷阱MCP 协议有一个初始化握手的过程客户端发送 initialize 请求Server 返回自己的能力信息然后客户端发送 initialized 通知之后才能正常调用工具。这个流程看起来很简单但实际实现的时候有几个容易忽略的点。第一个点是能力声明的准确性。在 initialize 响应里你需要声明自己支持哪些能力比如 tools、resources、prompts 等。如果你声明了 tools 但实际上没有正确注册任何工具客户端可能会在后续调用中出现意料之外的行为。反过来如果你实际有工具但没有声明 tools 能力客户端根本不会去查询你的工具列表。第二个点是初始化超时。有些客户端在 initialize 阶段有比较严格的超时限制如果你的 Server 在启动时需要做一些耗时的初始化操作比如加载模型、连接数据库这些操作如果放在 initialize 请求的处理路径里很容易导致握手超时。正确的做法是把这些耗时操作放在 Server 进程启动阶段完成initialize 请求的处理应该尽可能轻量。第三个点是重复初始化。SSE 模式下同一个客户端可能因为网络抖动而重新发送 initialize 请求。如果你的 Server 没有正确处理这种情况可能会创建多个会话状态导致后续调用行为混乱。我的做法是给每个会话分配一个唯一的 session ID在 initialize 时返回给客户端后续请求都带上这个 IDServer 根据 ID 来查找和维护会话状态。2.3 断线重连与会话恢复的工程实践SSE 连接断开是必然会发生的事情问题只是什么时候发生。你的 Server 需要能够处理两种情况客户端主动断开和网络异常断开。对于客户端主动断开你需要及时清理对应的会话资源避免内存泄漏。对于网络异常断开你需要考虑是否支持会话恢复。MCP 协议本身没有强制要求会话恢复机制但在生产环境中如果一个长连接断了之后客户端需要重新初始化、重新拉取工具列表、重新建立上下文这个开销是很大的。我的做法是在 Server 端维护一个会话表每个会话有一个过期时间。当连接断开时不立即销毁会话而是标记为“断连”状态保留一段时间。如果客户端在过期时间内重新连接并带上之前的 session ID就恢复会话如果超时了还没有重连再清理资源。这个过期时间需要根据实际场景来定太短了起不到恢复的作用太长了会占用不必要的资源。一般来说几分钟到十几分钟是一个比较合理的范围。另外要注意的是会话恢复不仅仅是恢复连接状态还需要考虑在断连期间产生的状态变化。比如你的 Server 在断连期间执行了某个长时间任务重连之后客户端需要知道这个任务的状态。这需要在会话状态里维护一个操作日志或者状态快照重连时同步给客户端。3. 工具描述调用方不是人它只看你写了什么3.1 工具名称与描述的“机器可读性”这是最容易被低估的一个环节。很多人在写工具定义的时候习惯性地用人类可读的方式来命名和描述比如工具名叫doStuff描述写“处理一些东西”。这种写法对人来说可能勉强能理解但对一个 AI 调用方来说信息量几乎为零。MCP 的工具定义包含名称、描述和参数 schema。调用方通常是 LLM会根据这些信息来决定是否调用这个工具、传什么参数。如果你的描述模糊不清调用方要么不敢调用要么传错参数。这不是调用方的问题是你的描述没有做到“机器可读”。什么叫机器可读就是描述里要明确说清楚这个工具做什么、什么时候应该用它、什么时候不应该用它、每个参数的含义和格式、返回值的结构。我举个例子对比一下{ name: search, description: 搜索东西, inputSchema: { type: object, properties: { q: { type: string } } } }这个定义的问题在于搜索什么在哪里搜索q 是什么格式返回什么调用方看到这个定义只能靠猜。{ name: search_documents, description: 在内部文档库中按关键词搜索文档。当用户询问需要查阅内部资料的问题时使用此工具。返回匹配文档的标题、摘要和链接。如果不需要查阅内部资料不要使用此工具。, inputSchema: { type: object, properties: { query: { type: string, description: 搜索关键词支持多个关键词用空格分隔例如部署 流程 }, max_results: { type: integer, description: 返回的最大结果数量默认 5最大 20, default: 5 } }, required: [query] } }第二个定义明显更好。它不仅说清楚了工具的功能还给出了使用场景的边界“当用户询问需要查阅内部资料的问题时使用”参数格式有示例默认值和取值范围也标明了。这些信息对调用方来说都是决策依据。3.2 参数 Schema 设计中的常见错误参数 schema 是工具定义中最容易出问题的地方。我总结了几类常见错误。第一类是类型不精确。比如一个参数应该是枚举值但你写成了 string调用方可能会传入任意字符串。正确的做法是用 enum 约束取值范围{ format: { type: string, enum: [json, markdown, plain], description: 返回内容的格式 } }第二类是缺少必填标记。有些参数是必须的但你没有放在 required 数组里调用方可能不传然后你的代码在运行时才报错。应该在 schema 层面就把必填项标清楚让调用方在构造请求时就知道哪些是必须的。第三类是嵌套结构过于复杂。有些工具的参数是一个深层嵌套的对象调用方很容易在嵌套层级上出错。如果可能的话尽量把参数扁平化或者提供多个简单的工具而不是一个复杂的工具。第四类是缺少参数间的约束说明。比如参数 A 和参数 B 互斥或者参数 C 在参数 D 为某个值时才有效。这些约束如果不在描述里写清楚调用方很可能会传入无效的组合。虽然 JSON Schema 本身对跨字段约束的支持有限但你可以在 description 里用自然语言说明。3.3 工具粒度的取舍一个大的还是多个小的这个问题没有标准答案但有一个判断原则如果一个工具的调用需要调用方先做很多前置判断才能确定参数那可能应该拆成多个工具。举个例子假设你有一个“查询数据”的工具它支持按不同维度查询按 ID 查、按名称查、按时间范围查。你可以做成一个工具参数里有一个query_type字段来决定用哪种查询方式也可以做成三个独立的工具get_by_id、get_by_name、get_by_time_range。前者的问题是调用方需要理解query_type和各个参数之间的对应关系容易传错。后者的好处是每个工具的参数都很清晰调用方只需要根据当前场景选择对应的工具。代价是工具列表变长了调用方需要在更多选项里做选择。我的经验是当不同查询方式的参数差异很大时拆成多个工具当参数差异很小时合并成一个工具。比如按 ID 查只需要一个 id 参数按时间范围查需要 start 和 end 两个参数这两种情况差异较大拆开更好。但如果只是排序字段不同参数结构基本一样合并成一个工具加一个 sort_by 参数就够了。还有一个相关的考虑是工具的数量。有些客户端在工具数量很多的时候调用方的选择准确率会下降。如果你的 Server 注册了几十个工具可能需要考虑分组或者提供某种导航机制。不过这是调用方侧的问题作为 Server 端你能做的是确保每个工具的描述足够清晰让调用方能够准确区分。4. 错误处理与可观测性出问题的时候你能看到什么4.1 MCP 错误响应的正确构造方式MCP 协议对错误响应有明确的格式要求。一个常见的错误做法是在工具执行出错时直接抛一个异常让框架去处理。这样做的结果是调用方收到的错误信息可能是一个通用的内部错误没有任何有用的上下文。正确的做法是区分协议层错误和工具执行错误。协议层错误是指请求格式不对、方法不存在、参数不符合 schema 等这些应该返回标准的 JSON-RPC 错误码。工具执行错误是指工具本身的逻辑出错了比如查询不到数据、外部服务不可用等这些应该作为工具调用的正常返回但在返回内容里标明错误状态。# 不推荐直接抛异常 async def handle_tool_call(name, arguments): result do_something(arguments) # 如果这里抛异常调用方收到的是通用错误 return result # 推荐区分错误类型返回结构化错误信息 async def handle_tool_call(name, arguments): try: result do_something(arguments) return {content: [{type: text, text: result}]} except ValidationError as e: return { content: [{type: text, text: f参数校验失败: {e.message}}], isError: True } except ExternalServiceError as e: return { content: [{type: text, text: f外部服务暂时不可用: {e.service_name}请稍后重试}], isError: True }这样做的意义在于调用方能够根据错误信息做出不同的决策。参数校验失败可能需要修改参数重试外部服务不可用可能需要等待或者换一个工具而一个通用的“内部错误”让调用方完全无法判断下一步该怎么做。4.2 日志与追踪让每一次调用都有迹可循MCP Server 的日志有一个特殊之处你不能往标准输出写日志stdio 模式下标准输出是协议通信通道必须写到标准错误或者文件。这一点如果搞错了会导致协议通信被日志内容污染客户端解析失败。在 SSE 模式下虽然没有这个限制但日志的规范性同样重要。我建议在日志里至少包含以下信息请求 ID每次工具调用生成一个唯一 ID方便串联同一次调用的所有日志会话 ID标识是哪个客户端发起的调用工具名称调用了哪个工具参数摘要参数的关键信息注意脱敏不要记录敏感数据执行耗时从收到请求到返回响应的总时间结果状态成功还是失败失败的话错误类型是什么这些信息看起来简单但在排查问题的时候非常有用。比如你发现某个工具偶尔超时通过日志可以看到是特定参数组合导致的还是所有调用都慢还是某个时间段集中出现。没有这些日志你只能靠猜。对于更复杂的场景可以考虑引入分布式追踪。每次工具调用生成一个 trace如果工具内部还调用了其他服务把子调用的 span 关联起来。这样可以看到整个调用链的耗时分布快速定位瓶颈在哪个环节。4.3 健康检查与就绪探针的落地细节如果你的 MCP Server 是以 SSE 模式运行的独立服务那么健康检查和就绪探针是必须的。健康检查用来判断进程是否还活着就绪探针用来判断服务是否已经准备好接受请求。健康检查的实现很简单暴露一个 HTTP 端点返回 200 就行。但就绪探针需要更细致的考虑你的 Server 在什么状态下才算“就绪”是进程启动完成了就算还是所有工具都注册好了才算还是依赖的外部服务都连通了才算我的做法是把就绪状态分为几个级别进程启动完成、工具注册完成、外部依赖连通。只有三个级别都满足时才返回就绪。如果某个外部依赖暂时不可用Server 可以返回“降级就绪”并在响应里标明哪些能力当前不可用。这样调用方可以根据自己的需求决定是否使用这个 Server。就绪探针不要做得太重。有些实现会在就绪探针里做一次完整的端到端测试调用这会导致探针本身成为性能瓶颈。探针应该只检查关键依赖的连通性不需要验证完整的业务逻辑。5. 并发与资源控制当多个调用同时打过来5.1 工具执行的并发模型选择MCP Server 需要处理并发请求这一点在 SSE 模式下尤其明显。并发模型的选择直接影响 Server 的吞吐量和稳定性。最简单的模型是串行处理收到一个请求处理完再处理下一个。这种模型实现简单不存在并发问题但吞吐量极低。如果一个工具调用需要几秒钟那同时来的其他请求就只能等着。稍微好一点的是线程池模型每个请求分配一个线程线程池的大小决定了最大并发数。这种模型适合 IO 密集型的工具比如网络请求、文件读写因为线程在等待 IO 的时候可以让出 CPU。但如果工具是 CPU 密集型的线程数超过 CPU 核心数反而会导致上下文切换开销。对于 Python 这样的语言还需要考虑 GIL 的影响。如果工具执行涉及大量 CPU 计算多线程并不能真正并行。这时候可能需要用多进程或者异步 IO 来提升并发能力。我的建议是根据工具的类型来选择并发模型。如果大部分工具是 IO 密集型的用异步 IOasyncio是最合适的单线程就能处理很高的并发。如果工具有 CPU 密集型的操作考虑把这些操作放到单独的进程池里执行避免阻塞事件循环。5.2 超时控制与取消传播超时控制是生产级 MCP Server 的必备能力。没有超时控制一个卡住的工具调用可能会占用资源直到天荒地老。超时控制需要分层设置连接超时、请求超时、工具执行超时。连接超时是指客户端建立连接的时间限制请求超时是指从收到请求到返回响应的总时间限制工具执行超时是指工具内部逻辑的执行时间限制。这三个超时的关系是连接超时 请求超时工具执行超时 请求超时。如果工具执行超时了Server 应该主动中断执行并返回超时错误而不是等请求超时了才被动断开。取消传播是另一个相关的问题。当客户端取消一个请求时比如用户手动中断了操作这个取消信号应该能够传播到工具的执行逻辑里。如果你的工具在执行一个长时间的操作收到取消信号后应该尽快停止并清理资源。这需要在工具的实现里支持取消检查比如定期检查一个 cancel token 的状态。async def long_running_tool(params, cancel_token): for i in range(1000): if cancel_token.is_cancelled(): raise CancelledError(操作已被取消) await do_step(i) return 完成5.3 资源配额与限流策略如果你的 MCP Server 是对外提供服务的资源配额和限流是保护自己的必要手段。没有限流一个异常客户端可能会耗尽所有资源导致其他客户端无法使用。限流可以从几个维度来做并发请求数限制、单位时间请求数限制、单个请求的资源消耗限制。并发请求数限制是最基本的防止同时处理太多请求导致内存溢出。单位时间请求数限制用来防止某个客户端高频调用。单个请求的资源消耗限制包括执行时间限制、内存使用限制、返回数据大小限制等。实现限流的时候要注意限流本身也会消耗资源。如果限流逻辑太重反而会成为瓶颈。对于简单的场景一个基于内存的计数器就够了。对于更复杂的场景可能需要引入令牌桶或者漏桶算法。还有一个容易被忽略的点是限流的反馈。当请求被限流时返回的错误信息应该明确告诉调用方是限流导致的以及建议的重试时间。这样调用方可以做出合理的退避决策而不是立即重试导致更严重的拥塞。控制维度推荐策略注意事项并发请求数根据内存和 CPU 核数设定上限留出余量给系统本身请求频率令牌桶按客户端维度限流区分不同客户端的配额执行时间分层超时工具级 请求级超时后要能中断执行返回大小限制单次返回的数据量超大结果考虑分页内存使用监控 硬限制防止 OOM 导致进程崩溃6. 把这些串起来一个可落地的改造清单6.1 优先级排序先改什么后改什么如果你手里的 MCP Server 已经能跑通但还没做生产级改造不要试图一次性把所有东西都改完。我的建议是按以下优先级来推进第一优先级错误处理与日志。这是投入产出比最高的改造。你不需要改变架构只需要在现有的工具处理逻辑里加上结构化的错误返回和关键日志。改完之后你至少能在出问题的时候知道发生了什么。第二优先级超时控制。给每个工具调用加上超时限制防止单个请求卡死整个 Server。这个改造也不复杂但能显著提升稳定性。第三优先级连接生命周期管理。如果你用的是 SSE 模式会话管理和断线重连是必须的。如果你用的是 stdio 模式这部分可以暂时跳过。第四优先级并发控制与限流。这部分在早期用户量不大的时候可以缓一缓但一旦有多个客户端同时使用就需要尽快补上。第五优先级工具描述的优化。这是一个持续改进的过程不需要一次性做完但每次发现调用方用错工具或者传错参数的时候都应该回头看看是不是描述不够清晰。6.2 改造过程中的验证方法每做一项改造都需要有对应的验证方法。不能改完了觉得“应该没问题”就上线了。对于错误处理可以构造各种异常场景来测试传非法参数、模拟外部服务超时、模拟内部逻辑异常看返回的错误信息是否清晰、是否包含足够的上下文。对于超时控制可以故意写一个会 sleep 很久的工具看 Server 是否能在超时后正确返回错误以及资源是否被正确释放。对于会话管理可以模拟连接断开和重连看会话状态是否正确恢复以及过期会话是否被正确清理。对于并发控制可以用压力测试工具模拟多个客户端同时调用观察 Server 的响应时间和资源使用情况确认没有出现死锁或者资源泄漏。这些验证不需要很复杂的工具很多时候写几个测试脚本就够了。关键是要有验证的意识而不是改完就完事。6.3 我踩过的几个印象深刻的坑最后分享几个我在改造过程中踩过的坑希望能帮你省点时间。第一个坑是在 stdio 模式下往标准输出打日志。这个坑很隐蔽因为本地测试的时候可能不会出问题但一旦日志量大了协议通信就会被污染客户端会收到无法解析的内容。解决方法是把所有日志都写到标准错误或者文件标准输出只用于协议通信。第二个坑是会话过期时间设得太短。我一开始设了 30 秒结果发现客户端稍微网络抖动一下会话就过期了重连之后所有状态都丢了。后来改成 5 分钟体验好了很多。这个值需要根据实际网络环境和客户端行为来调整。第三个坑是工具描述里用了太多专业术语。我以为调用方能够理解这些术语但实际上调用方在决定是否使用某个工具的时候依赖的是描述里的自然语言。如果描述里全是术语调用方可能无法准确判断这个工具是否适合当前场景。后来我把描述改得更直白调用准确率明显提升了。第四个坑是没有限制单个请求的返回数据量。有一个工具会返回一个很大的 JSON结果调用方在处理的时候内存爆了。后来加上了分页和大小限制问题就解决了。这个坑让我意识到Server 端不仅要考虑自己不出问题还要考虑返回的数据对调用方是否友好。这些坑说起来都不复杂但都是在实际运行中才会暴露出来的。希望你在改造自己的 MCP Server 的时候能够提前避开。
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
