1. 从能跑到敢上线MCP Server 的鸿沟到底在哪很多人第一次写 MCP Server 的经历都差不多照着官方 SDK 的示例定义一个 tool写个 handler本地用客户端连上看到工具被正确调用、返回了预期结果然后心里想成了。这个阶段我称之为跑通它证明你理解了 MCP 协议的基本交互模型——客户端发起请求服务端暴露工具、资源和提示词双方通过标准化的 JSON-RPC 消息通信。但跑通和生产级之间的距离远比大多数人想象的要大。我自己踩过这个坑一个内部用的 MCP Server本地测试一切正常接入到实际的 LLM 工作流之后问题一个接一个冒出来——工具描述写得含糊导致模型选错工具、参数校验缺失导致非法输入直接把进程搞崩、并发请求下状态互相污染、日志里什么都看不到出了问题完全没法排查。这些问题在 demo 阶段根本不会暴露因为 demo 的输入是你精心构造的、调用是串行的、出错了你就在旁边盯着。MCPModel Context Protocol本质上是一套让 LLM 与外部能力对接的协议层。它解决的核心问题是模型本身只有推理能力要让它真正干活就得给它工具。而 MCP Server 就是这些工具的提供方。关键词里提到的 TypeScript、Python、SDK、LLM基本覆盖了当前 MCP Server 开发的主流技术栈——官方和社区提供了 TypeScript SDK 和 Python SDK绝大多数人会用其中之一来搭建服务端。这篇文章面向的是已经写出过能跑的 MCP Server、但还没把它推到生产环境的开发者。我会把从跑通到生产级之间最关键的四个步骤拆开讲清楚工具契约的设计、输入输出的防御性处理、可观测性建设、以及部署与生命周期管理。每一步我都会说明为什么这么做、不这么做会出什么事、以及具体怎么落地。如果你正在用 TypeScript 或 Python 写 MCP Server准备把它接入真实的 LLM 应用这篇内容应该能帮你少走不少弯路。2. 第一步把工具契约当成 API 设计来做而不是随手写个 description2.1 工具描述是给模型看的不是给人看的这是最容易被忽视的一点。很多人写 tool 的 description 时心态是我自己知道这个工具干嘛的就行于是写出来的东西是这样的{ name: query, description: 查询数据, inputSchema: { type: object, properties: { q: { type: string } } } }问题在于MCP 的工具描述不是给你看的文档它是给 LLM 看的使用说明书。模型在决定调用哪个工具、传什么参数时唯一的依据就是你提供的 name、description 和 inputSchema。描述写得含糊模型就会选错工具或者传错参数而且这种错误非常隐蔽——它不会报错只会给你一个看起来合理但实际不对的结果。生产级的工具描述应该包含几个要素这个工具做什么、什么场景下应该用它、什么场景下不应该用它、每个参数的含义和格式要求、返回值的结构。我通常会这样写{ name: search_orders, description: 根据条件搜索订单记录。适用于用户询问订单状态、订单历史、订单详情等场景。不适用于创建或修改订单。返回匹配的订单列表每条包含订单号、状态、金额和创建时间。, inputSchema: { type: object, properties: { order_id: { type: string, description: 订单号格式为 ORD- 开头的 12 位字符串例如 ORD-202401011234 }, status: { type: string, enum: [pending, paid, shipped, completed, cancelled], description: 订单状态筛选不传则返回所有状态 }, limit: { type: number, description: 返回条数上限默认 20最大 100 } }, required: [order_id] } }对比一下就能看出差别。后者明确告诉了模型什么时候用、什么时候不用、参数长什么样、返回什么。这些信息直接决定了模型调用的准确率。2.2 参数 schema 要严格别用 any 糊弄TypeScript SDK 里 inputSchema 用的是 JSON SchemaPython SDK 也类似。我见过太多人为了省事把所有参数都定义成{ type: string }然后在 handler 里自己解析。这种做法在 demo 里没问题但生产环境里模型传过来的东西千奇百怪你不约束它它就会给你惊喜。几个实操要点能用 enum 就用 enum。状态、类型、模式这类有限取值的参数一定要用 enum 约束。模型看到 enum 会自然地从中选择而不是自己编一个。数字参数标明范围。minimum和maximum不只是校验也是给模型的提示。你写maximum: 100模型就知道不该传 1000。必填和选填分清楚。required数组里只放真正必须的参数。把可选参数标成必填会逼着模型瞎编一个值填进去。嵌套结构要展开描述。如果参数是个对象或数组每一层的字段都要有 description。模型对嵌套结构的理解能力有限你不写清楚它就猜。2.3 工具粒度太粗和太细都是坑工具设计有个经典的粒度问题。一个工具干太多事模型很难用对一个工具干太少事模型要调很多次才能完成一个任务既慢又容易出错。我的经验法则是一个工具对应一个明确的意图。比如搜索订单和取消订单应该是两个工具而不是一个订单操作工具加一个 action 参数。因为模型在决定要不要取消订单和怎么搜索订单时用的是完全不同的推理路径混在一起会让它困惑。但也不要细到获取订单号、获取订单状态、获取订单金额这种程度。这些信息应该在一个查询订单工具里一次性返回。判断标准很简单如果两个操作在业务上总是同时发生就合并如果它们的触发场景完全不同就分开。一个实用的检验方法把你的工具列表和描述拿给一个不了解你系统的同事看让他判断用户说 X 的时候该用哪个工具。如果他犹豫了说明你的描述或粒度有问题模型也会犹豫。3. 第二步防御性处理别让一个非法输入搞崩整个服务3.1 MCP Server 的输入是不可信的这一点必须刻在脑子里模型传给你的参数等同于用户输入完全不可信。模型可能会传错类型、传超长字符串、传不存在的 ID、传格式不对的日期。你的 handler 不能假设输入是合法的。我见过最典型的翻车场景handler 里直接JSON.parse(params.data)结果模型传了个不是 JSON 的字符串整个进程抛异常挂掉。如果这个 Server 是单进程处理多个客户端请求的一个请求的崩溃会影响所有连接。防御性处理分三层第一层是 schema 校验。前面说的 inputSchema 不只是给模型看的也应该在服务端做实际校验。TypeScript SDK 和 Python SDK 通常会在调用 handler 前做基础校验但不要完全依赖它尤其是嵌套结构。第二层是 handler 内的边界检查。拿到参数后先检查关键字段是否存在、类型是否正确、值是否在合理范围内。比如def handle_search_orders(params): order_id params.get(order_id) if not order_id or not isinstance(order_id, str): return error_response(order_id 必须是非空字符串) if not order_id.startswith(ORD-) or len(order_id) ! 16: return error_response(forder_id 格式不正确: {order_id}) limit params.get(limit, 20) if not isinstance(limit, int) or limit 1 or limit 100: limit 20 # 或者返回错误看你的策略 # 到这里才真正开始业务逻辑第三层是全局异常兜底。handler 里所有可能抛异常的地方都要包在 try-catch 里确保任何意外都不会让进程崩溃。返回给模型的应该是一个结构化的错误信息而不是一个堆栈。3.2 错误返回要结构化别只给一句话模型拿到错误信息后会尝试理解并决定下一步怎么做。如果你只返回出错了模型完全不知道该怎么办。生产级的错误返回应该包含错误类型、错误原因、可能的修复建议。function errorResponse(code: string, message: string, suggestion?: string) { return { content: [{ type: text, text: JSON.stringify({ error: true, code, message, suggestion: suggestion || 请检查输入参数后重试 }) }], isError: true }; }这样模型看到code: INVALID_ORDER_ID和suggestion: 订单号应以 ORD- 开头就有机会自己纠正参数重新调用。这比直接失败要好得多。3.3 超时和资源限制必须有生产环境里你的工具可能会调用外部 API、查数据库、读文件。这些操作都可能慢或者卡住。如果没有超时控制一个慢请求会占着连接不放积累多了整个服务就废了。我的做法是给每个工具设置一个合理的超时时间在 handler 里用Promise.raceTypeScript或asyncio.wait_forPython来强制超时async function withTimeoutT(promise: PromiseT, ms: number, label: string): PromiseT { const timeout new Promisenever((_, reject) setTimeout(() reject(new Error(${label} 超时 (${ms}ms))), ms) ); return Promise.race([promise, timeout]); }超时时间设多少看你的工具类型。纯内存计算 1-2 秒够了调外部 API 给 10-30 秒涉及批量数据处理可以放宽到 60 秒。关键是要有而不是设多少。资源限制还包括单次返回的数据量上限别把整个数据库返回给模型、并发请求数上限、内存使用上限。这些在 demo 里都不需要考虑但生产环境里任何一个失控都会导致服务不可用。4. 第三步可观测性出问题时你得知道发生了什么4.1 日志不是可选项是必需品MCP Server 有个特殊之处它的调用方是 LLM不是人。这意味着当出现问题时你没法问你刚才点了什么只能靠日志还原现场。没有日志的 MCP Server 在生产环境里就是个黑盒出了问题只能靠猜。生产级日志至少要记录这几类信息请求进入谁调的、调了哪个工具、参数是什么注意脱敏处理过程关键步骤、耗时、中间状态请求返回返回了什么、是否成功、总耗时异常错误类型、堆栈、上下文用结构化日志JSON 格式而不是纯文本方便后续检索和分析import logging import json import time logger logging.getLogger(mcp_server) def log_tool_call(tool_name, params, result, duration_ms, errorNone): entry { event: tool_call, tool: tool_name, params: sanitize(params), duration_ms: duration_ms, success: error is None, error: str(error) if error else None, timestamp: time.time() } logger.info(json.dumps(entry, ensure_asciiFalse))4.2 关键指标要能观测光有日志还不够你还需要能回答我的服务现在健康吗这个问题。几个核心指标指标含义关注点调用次数每个工具被调用的频率突增突降都可能是问题成功率成功调用 / 总调用低于 95% 要警惕P95 延迟95% 请求的耗时上限反映用户体验错误分布各类错误的比例定位主要问题并发数同时处理的请求数接近上限要扩容这些指标不需要多复杂的监控系统一个简单的内存计数器加定期输出就够了。关键是你要有意识地去采集和观察。4.3 追踪把一次调用串起来当你的 MCP Server 调用链变长比如工具内部又调了其他服务单条日志就不够用了。你需要一个 trace ID 把一次完整调用串起来。做法很简单请求进入时生成一个唯一 ID在后续所有日志里都带上这个 ID。这样出问题时你用这个 ID 一搜就能看到完整的调用链路。import { randomUUID } from crypto; function handleRequest(toolName: string, params: any) { const traceId randomUUID(); const startTime Date.now(); logger.info({ traceId, tool: toolName, event: start, params }); try { const result doWork(params); logger.info({ traceId, tool: toolName, event: end, duration: Date.now() - startTime }); return result; } catch (err) { logger.error({ traceId, tool: toolName, event: error, error: err.message }); throw err; } }这个 traceId 最好也能返回给调用方放在返回结果的 metadata 里这样当用户反馈刚才那个操作有问题时你能快速定位到具体是哪次调用。一个容易忽略的点日志里不要记录敏感信息。用户的订单号、手机号、地址这些要么脱敏要么只记录哈希值。日志泄露导致的数据安全问题比服务本身出问题更严重。5. 第四步部署与生命周期让服务能稳定地活着5.1 传输方式的选择stdio 还是 HTTPMCP 支持多种传输方式最常见的是 stdio 和 HTTP包括 SSE。这个选择直接决定了你的部署方式。stdio适合本地运行、单客户端的场景。客户端启动你的 Server 进程通过标准输入输出通信。优点是简单、无需网络配置、天然隔离。缺点是每个客户端一个进程无法共享状态也不适合远程访问。HTTP/SSE适合远程部署、多客户端共享的场景。你的 Server 作为一个独立服务运行客户端通过网络连接。优点是能集中管理、共享资源、方便扩容。缺点是要处理网络、认证、并发这些额外问题。我的建议是如果只是本地个人使用stdio 就够了如果要给团队或产品用直接上 HTTP。不要等到 stdio 撑不住了再迁移那时候改造成本更高。5.2 优雅启动和关闭生产级服务必须能优雅地处理启动和关闭。启动时要做的加载配置、初始化连接池、预热缓存、注册信号处理器。关闭时要做的停止接受新请求、等待进行中的请求完成、释放资源、退出进程。import signal import sys class MCPServer: def __init__(self): self.running True self.active_requests 0 def handle_signal(self, signum, frame): logger.info(f收到信号 {signum}开始优雅关闭) self.running False def run(self): signal.signal(signal.SIGTERM, self.handle_signal) signal.signal(signal.SIGINT, self.handle_signal) while self.running: # 主循环 pass # 等待进行中的请求完成 while self.active_requests 0: time.sleep(0.1) self.cleanup() logger.info(服务已关闭)为什么要这么麻烦因为粗暴地 kill 进程会导致正在处理的请求丢失、数据库连接没释放、临时文件残留、客户端收到莫名其妙的错误。这些问题在开发时看不出来在生产环境里会变成偶发的、难以复现的故障。5.3 配置管理别把配置写死在代码里生产环境的配置和开发环境不一样数据库地址、API 密钥、超时时间、日志级别这些都应该通过环境变量或配置文件注入而不是硬编码。const config { dbUrl: process.env.MCP_DB_URL || localhost:5432, apiKey: process.env.MCP_API_KEY, timeoutMs: parseInt(process.env.MCP_TIMEOUT_MS || 30000), logLevel: process.env.MCP_LOG_LEVEL || info, maxConcurrency: parseInt(process.env.MCP_MAX_CONCURRENCY || 10), }; // 启动时校验必填配置 if (!config.apiKey) { throw new Error(MCP_API_KEY 未配置服务无法启动); }启动时校验配置这个动作很重要。宁可启动失败也不要带着错误配置跑起来然后在运行时出问题。启动失败你能立刻发现运行时出问题可能要等到用户投诉。5.4 版本管理和向后兼容MCP Server 的工具定义会随着业务变化而调整。但你的客户端可能是别人的 LLM 应用不一定能同步更新。所以工具定义的变更要考虑向后兼容。几个原则不要删除已有的工具除非确认没有客户端在用。要下线就标记为 deprecated保留一段时间。不要修改已有参数的含义。要改就加新参数旧参数保留兼容逻辑。新增必填参数是破坏性变更。如果非要加给个默认值让它变成可选。返回结构只增不减。模型可能依赖某个字段你删了它就会出错。这些原则和设计 REST API 是一样的道理。MCP 工具本质上就是 API只是调用方从人变成了模型。6. 那些只有踩过才知道的细节6.1 工具返回的内容格式很讲究MCP 工具的返回不是随便一个字符串就行。返回内容的结构直接影响模型的理解。我踩过的坑返回一大段自然语言描述模型提取信息时经常漏掉关键字段。后来改成结构化返回准确率明显提升。推荐的做法是返回 JSON 字符串字段名清晰层级不要太深{ orders: [ { order_id: ORD-202401011234, status: shipped, amount: 299.00, created_at: 2024-01-01T12:34:00Z } ], total: 1, has_more: false }如果返回内容很长考虑在 text 之外用 MCP 支持的 resource 类型让模型按需读取。但大多数场景下控制返回长度比换类型更实际。6.2 并发下的状态污染如果你的 handler 里用了模块级的变量来存状态并发请求下会互相污染。这是我在一个 Python MCP Server 上真实踩过的坑用一个全局 dict 缓存查询结果结果两个并发请求的缓存键撞了返回了错误的数据。解决办法要么用请求级别的局部变量要么用线程安全的数据结构要么干脆无状态。MCP Server 最好设计成无状态的所有需要持久化的东西都放外部存储。6.3 模型会创造性地使用你的工具即使你的工具描述写得很清楚模型有时还是会用出你意想不到的方式。比如你定义了一个查询订单工具模型可能会用它来验证订单是否存在然后根据返回结果决定下一步。这本身不是问题但你要确保你的工具在这种非预期用法下也不会出问题。一个实用的做法是在测试阶段故意用各种奇怪的参数调用你的工具看看会不会崩。我通常会写一组恶意测试用例空字符串、超长字符串、特殊字符、错误类型、边界值。能扛过这些基本就稳了。6.4 别忽视冷启动如果你的 MCP Server 需要加载模型、建立连接池、预热缓存冷启动可能需要几秒甚至几十秒。这期间客户端发来的请求会失败或超时。解决办法是在启动完成前不对外提供服务或者提供一个健康检查接口让客户端知道什么时候可以开始调用。7. 上线前的自查清单把上面四步走完你的 MCP Server 基本就具备生产级的底子了。最后给一份我自己的上线前自查清单你可以对照着过一遍检查项合格标准工具描述每个工具都有明确的用途、场景、参数说明参数校验所有输入都经过类型和范围检查异常处理任何异常都不会导致进程崩溃超时控制每个外部调用都有超时日志关键路径都有结构化日志含 trace ID指标能观测调用量、成功率、延迟优雅关闭收到信号能完成进行中的请求再退出配置管理配置通过环境变量注入启动时校验并发安全无共享可变状态或已做同步向后兼容工具变更不破坏已有客户端这份清单不是教条不同场景可以调整。但核心思路是一致的生产级意味着你要假设一切都会出错然后确保出错时服务还能活着、你还能查到原因。从跑通到生产级本质上是从证明它能工作到证明它在各种情况下都能工作的转变。这个转变需要的工作量往往比写第一版还大。但只有走完这一步你的 MCP Server 才真正能承担起 LLM 应用背后的工具支撑角色。
1. 从能跑到敢上线MCP Server 的鸿沟到底在哪很多人第一次写 MCP Server 的经历都差不多照着官方 SDK 的示例定义一个 tool写个 handler本地用客户端连上看到工具被正确调用、返回了预期结果然后心里想成了。这个阶段我称之为跑通它证明你理解了 MCP 协议的基本交互模型——客户端发起请求服务端暴露工具、资源和提示词双方通过标准化的 JSON-RPC 消息通信。但跑通和生产级之间的距离远比大多数人想象的要大。我自己踩过这个坑一个内部用的 MCP Server本地测试一切正常接入到实际的 LLM 工作流之后问题一个接一个冒出来——工具描述写得含糊导致模型选错工具、参数校验缺失导致非法输入直接把进程搞崩、并发请求下状态互相污染、日志里什么都看不到出了问题完全没法排查。这些问题在 demo 阶段根本不会暴露因为 demo 的输入是你精心构造的、调用是串行的、出错了你就在旁边盯着。MCPModel Context Protocol本质上是一套让 LLM 与外部能力对接的协议层。它解决的核心问题是模型本身只有推理能力要让它真正干活就得给它工具。而 MCP Server 就是这些工具的提供方。关键词里提到的 TypeScript、Python、SDK、LLM基本覆盖了当前 MCP Server 开发的主流技术栈——官方和社区提供了 TypeScript SDK 和 Python SDK绝大多数人会用其中之一来搭建服务端。这篇文章面向的是已经写出过能跑的 MCP Server、但还没把它推到生产环境的开发者。我会把从跑通到生产级之间最关键的四个步骤拆开讲清楚工具契约的设计、输入输出的防御性处理、可观测性建设、以及部署与生命周期管理。每一步我都会说明为什么这么做、不这么做会出什么事、以及具体怎么落地。如果你正在用 TypeScript 或 Python 写 MCP Server准备把它接入真实的 LLM 应用这篇内容应该能帮你少走不少弯路。2. 第一步把工具契约当成 API 设计来做而不是随手写个 description2.1 工具描述是给模型看的不是给人看的这是最容易被忽视的一点。很多人写 tool 的 description 时心态是我自己知道这个工具干嘛的就行于是写出来的东西是这样的{ name: query, description: 查询数据, inputSchema: { type: object, properties: { q: { type: string } } } }问题在于MCP 的工具描述不是给你看的文档它是给 LLM 看的使用说明书。模型在决定调用哪个工具、传什么参数时唯一的依据就是你提供的 name、description 和 inputSchema。描述写得含糊模型就会选错工具或者传错参数而且这种错误非常隐蔽——它不会报错只会给你一个看起来合理但实际不对的结果。生产级的工具描述应该包含几个要素这个工具做什么、什么场景下应该用它、什么场景下不应该用它、每个参数的含义和格式要求、返回值的结构。我通常会这样写{ name: search_orders, description: 根据条件搜索订单记录。适用于用户询问订单状态、订单历史、订单详情等场景。不适用于创建或修改订单。返回匹配的订单列表每条包含订单号、状态、金额和创建时间。, inputSchema: { type: object, properties: { order_id: { type: string, description: 订单号格式为 ORD- 开头的 12 位字符串例如 ORD-202401011234 }, status: { type: string, enum: [pending, paid, shipped, completed, cancelled], description: 订单状态筛选不传则返回所有状态 }, limit: { type: number, description: 返回条数上限默认 20最大 100 } }, required: [order_id] } }对比一下就能看出差别。后者明确告诉了模型什么时候用、什么时候不用、参数长什么样、返回什么。这些信息直接决定了模型调用的准确率。2.2 参数 schema 要严格别用 any 糊弄TypeScript SDK 里 inputSchema 用的是 JSON SchemaPython SDK 也类似。我见过太多人为了省事把所有参数都定义成{ type: string }然后在 handler 里自己解析。这种做法在 demo 里没问题但生产环境里模型传过来的东西千奇百怪你不约束它它就会给你惊喜。几个实操要点能用 enum 就用 enum。状态、类型、模式这类有限取值的参数一定要用 enum 约束。模型看到 enum 会自然地从中选择而不是自己编一个。数字参数标明范围。minimum和maximum不只是校验也是给模型的提示。你写maximum: 100模型就知道不该传 1000。必填和选填分清楚。required数组里只放真正必须的参数。把可选参数标成必填会逼着模型瞎编一个值填进去。嵌套结构要展开描述。如果参数是个对象或数组每一层的字段都要有 description。模型对嵌套结构的理解能力有限你不写清楚它就猜。2.3 工具粒度太粗和太细都是坑工具设计有个经典的粒度问题。一个工具干太多事模型很难用对一个工具干太少事模型要调很多次才能完成一个任务既慢又容易出错。我的经验法则是一个工具对应一个明确的意图。比如搜索订单和取消订单应该是两个工具而不是一个订单操作工具加一个 action 参数。因为模型在决定要不要取消订单和怎么搜索订单时用的是完全不同的推理路径混在一起会让它困惑。但也不要细到获取订单号、获取订单状态、获取订单金额这种程度。这些信息应该在一个查询订单工具里一次性返回。判断标准很简单如果两个操作在业务上总是同时发生就合并如果它们的触发场景完全不同就分开。一个实用的检验方法把你的工具列表和描述拿给一个不了解你系统的同事看让他判断用户说 X 的时候该用哪个工具。如果他犹豫了说明你的描述或粒度有问题模型也会犹豫。3. 第二步防御性处理别让一个非法输入搞崩整个服务3.1 MCP Server 的输入是不可信的这一点必须刻在脑子里模型传给你的参数等同于用户输入完全不可信。模型可能会传错类型、传超长字符串、传不存在的 ID、传格式不对的日期。你的 handler 不能假设输入是合法的。我见过最典型的翻车场景handler 里直接JSON.parse(params.data)结果模型传了个不是 JSON 的字符串整个进程抛异常挂掉。如果这个 Server 是单进程处理多个客户端请求的一个请求的崩溃会影响所有连接。防御性处理分三层第一层是 schema 校验。前面说的 inputSchema 不只是给模型看的也应该在服务端做实际校验。TypeScript SDK 和 Python SDK 通常会在调用 handler 前做基础校验但不要完全依赖它尤其是嵌套结构。第二层是 handler 内的边界检查。拿到参数后先检查关键字段是否存在、类型是否正确、值是否在合理范围内。比如def handle_search_orders(params): order_id params.get(order_id) if not order_id or not isinstance(order_id, str): return error_response(order_id 必须是非空字符串) if not order_id.startswith(ORD-) or len(order_id) ! 16: return error_response(forder_id 格式不正确: {order_id}) limit params.get(limit, 20) if not isinstance(limit, int) or limit 1 or limit 100: limit 20 # 或者返回错误看你的策略 # 到这里才真正开始业务逻辑第三层是全局异常兜底。handler 里所有可能抛异常的地方都要包在 try-catch 里确保任何意外都不会让进程崩溃。返回给模型的应该是一个结构化的错误信息而不是一个堆栈。3.2 错误返回要结构化别只给一句话模型拿到错误信息后会尝试理解并决定下一步怎么做。如果你只返回出错了模型完全不知道该怎么办。生产级的错误返回应该包含错误类型、错误原因、可能的修复建议。function errorResponse(code: string, message: string, suggestion?: string) { return { content: [{ type: text, text: JSON.stringify({ error: true, code, message, suggestion: suggestion || 请检查输入参数后重试 }) }], isError: true }; }这样模型看到code: INVALID_ORDER_ID和suggestion: 订单号应以 ORD- 开头就有机会自己纠正参数重新调用。这比直接失败要好得多。3.3 超时和资源限制必须有生产环境里你的工具可能会调用外部 API、查数据库、读文件。这些操作都可能慢或者卡住。如果没有超时控制一个慢请求会占着连接不放积累多了整个服务就废了。我的做法是给每个工具设置一个合理的超时时间在 handler 里用Promise.raceTypeScript或asyncio.wait_forPython来强制超时async function withTimeoutT(promise: PromiseT, ms: number, label: string): PromiseT { const timeout new Promisenever((_, reject) setTimeout(() reject(new Error(${label} 超时 (${ms}ms))), ms) ); return Promise.race([promise, timeout]); }超时时间设多少看你的工具类型。纯内存计算 1-2 秒够了调外部 API 给 10-30 秒涉及批量数据处理可以放宽到 60 秒。关键是要有而不是设多少。资源限制还包括单次返回的数据量上限别把整个数据库返回给模型、并发请求数上限、内存使用上限。这些在 demo 里都不需要考虑但生产环境里任何一个失控都会导致服务不可用。4. 第三步可观测性出问题时你得知道发生了什么4.1 日志不是可选项是必需品MCP Server 有个特殊之处它的调用方是 LLM不是人。这意味着当出现问题时你没法问你刚才点了什么只能靠日志还原现场。没有日志的 MCP Server 在生产环境里就是个黑盒出了问题只能靠猜。生产级日志至少要记录这几类信息请求进入谁调的、调了哪个工具、参数是什么注意脱敏处理过程关键步骤、耗时、中间状态请求返回返回了什么、是否成功、总耗时异常错误类型、堆栈、上下文用结构化日志JSON 格式而不是纯文本方便后续检索和分析import logging import json import time logger logging.getLogger(mcp_server) def log_tool_call(tool_name, params, result, duration_ms, errorNone): entry { event: tool_call, tool: tool_name, params: sanitize(params), duration_ms: duration_ms, success: error is None, error: str(error) if error else None, timestamp: time.time() } logger.info(json.dumps(entry, ensure_asciiFalse))4.2 关键指标要能观测光有日志还不够你还需要能回答我的服务现在健康吗这个问题。几个核心指标指标含义关注点调用次数每个工具被调用的频率突增突降都可能是问题成功率成功调用 / 总调用低于 95% 要警惕P95 延迟95% 请求的耗时上限反映用户体验错误分布各类错误的比例定位主要问题并发数同时处理的请求数接近上限要扩容这些指标不需要多复杂的监控系统一个简单的内存计数器加定期输出就够了。关键是你要有意识地去采集和观察。4.3 追踪把一次调用串起来当你的 MCP Server 调用链变长比如工具内部又调了其他服务单条日志就不够用了。你需要一个 trace ID 把一次完整调用串起来。做法很简单请求进入时生成一个唯一 ID在后续所有日志里都带上这个 ID。这样出问题时你用这个 ID 一搜就能看到完整的调用链路。import { randomUUID } from crypto; function handleRequest(toolName: string, params: any) { const traceId randomUUID(); const startTime Date.now(); logger.info({ traceId, tool: toolName, event: start, params }); try { const result doWork(params); logger.info({ traceId, tool: toolName, event: end, duration: Date.now() - startTime }); return result; } catch (err) { logger.error({ traceId, tool: toolName, event: error, error: err.message }); throw err; } }这个 traceId 最好也能返回给调用方放在返回结果的 metadata 里这样当用户反馈刚才那个操作有问题时你能快速定位到具体是哪次调用。一个容易忽略的点日志里不要记录敏感信息。用户的订单号、手机号、地址这些要么脱敏要么只记录哈希值。日志泄露导致的数据安全问题比服务本身出问题更严重。5. 第四步部署与生命周期让服务能稳定地活着5.1 传输方式的选择stdio 还是 HTTPMCP 支持多种传输方式最常见的是 stdio 和 HTTP包括 SSE。这个选择直接决定了你的部署方式。stdio适合本地运行、单客户端的场景。客户端启动你的 Server 进程通过标准输入输出通信。优点是简单、无需网络配置、天然隔离。缺点是每个客户端一个进程无法共享状态也不适合远程访问。HTTP/SSE适合远程部署、多客户端共享的场景。你的 Server 作为一个独立服务运行客户端通过网络连接。优点是能集中管理、共享资源、方便扩容。缺点是要处理网络、认证、并发这些额外问题。我的建议是如果只是本地个人使用stdio 就够了如果要给团队或产品用直接上 HTTP。不要等到 stdio 撑不住了再迁移那时候改造成本更高。5.2 优雅启动和关闭生产级服务必须能优雅地处理启动和关闭。启动时要做的加载配置、初始化连接池、预热缓存、注册信号处理器。关闭时要做的停止接受新请求、等待进行中的请求完成、释放资源、退出进程。import signal import sys class MCPServer: def __init__(self): self.running True self.active_requests 0 def handle_signal(self, signum, frame): logger.info(f收到信号 {signum}开始优雅关闭) self.running False def run(self): signal.signal(signal.SIGTERM, self.handle_signal) signal.signal(signal.SIGINT, self.handle_signal) while self.running: # 主循环 pass # 等待进行中的请求完成 while self.active_requests 0: time.sleep(0.1) self.cleanup() logger.info(服务已关闭)为什么要这么麻烦因为粗暴地 kill 进程会导致正在处理的请求丢失、数据库连接没释放、临时文件残留、客户端收到莫名其妙的错误。这些问题在开发时看不出来在生产环境里会变成偶发的、难以复现的故障。5.3 配置管理别把配置写死在代码里生产环境的配置和开发环境不一样数据库地址、API 密钥、超时时间、日志级别这些都应该通过环境变量或配置文件注入而不是硬编码。const config { dbUrl: process.env.MCP_DB_URL || localhost:5432, apiKey: process.env.MCP_API_KEY, timeoutMs: parseInt(process.env.MCP_TIMEOUT_MS || 30000), logLevel: process.env.MCP_LOG_LEVEL || info, maxConcurrency: parseInt(process.env.MCP_MAX_CONCURRENCY || 10), }; // 启动时校验必填配置 if (!config.apiKey) { throw new Error(MCP_API_KEY 未配置服务无法启动); }启动时校验配置这个动作很重要。宁可启动失败也不要带着错误配置跑起来然后在运行时出问题。启动失败你能立刻发现运行时出问题可能要等到用户投诉。5.4 版本管理和向后兼容MCP Server 的工具定义会随着业务变化而调整。但你的客户端可能是别人的 LLM 应用不一定能同步更新。所以工具定义的变更要考虑向后兼容。几个原则不要删除已有的工具除非确认没有客户端在用。要下线就标记为 deprecated保留一段时间。不要修改已有参数的含义。要改就加新参数旧参数保留兼容逻辑。新增必填参数是破坏性变更。如果非要加给个默认值让它变成可选。返回结构只增不减。模型可能依赖某个字段你删了它就会出错。这些原则和设计 REST API 是一样的道理。MCP 工具本质上就是 API只是调用方从人变成了模型。6. 那些只有踩过才知道的细节6.1 工具返回的内容格式很讲究MCP 工具的返回不是随便一个字符串就行。返回内容的结构直接影响模型的理解。我踩过的坑返回一大段自然语言描述模型提取信息时经常漏掉关键字段。后来改成结构化返回准确率明显提升。推荐的做法是返回 JSON 字符串字段名清晰层级不要太深{ orders: [ { order_id: ORD-202401011234, status: shipped, amount: 299.00, created_at: 2024-01-01T12:34:00Z } ], total: 1, has_more: false }如果返回内容很长考虑在 text 之外用 MCP 支持的 resource 类型让模型按需读取。但大多数场景下控制返回长度比换类型更实际。6.2 并发下的状态污染如果你的 handler 里用了模块级的变量来存状态并发请求下会互相污染。这是我在一个 Python MCP Server 上真实踩过的坑用一个全局 dict 缓存查询结果结果两个并发请求的缓存键撞了返回了错误的数据。解决办法要么用请求级别的局部变量要么用线程安全的数据结构要么干脆无状态。MCP Server 最好设计成无状态的所有需要持久化的东西都放外部存储。6.3 模型会创造性地使用你的工具即使你的工具描述写得很清楚模型有时还是会用出你意想不到的方式。比如你定义了一个查询订单工具模型可能会用它来验证订单是否存在然后根据返回结果决定下一步。这本身不是问题但你要确保你的工具在这种非预期用法下也不会出问题。一个实用的做法是在测试阶段故意用各种奇怪的参数调用你的工具看看会不会崩。我通常会写一组恶意测试用例空字符串、超长字符串、特殊字符、错误类型、边界值。能扛过这些基本就稳了。6.4 别忽视冷启动如果你的 MCP Server 需要加载模型、建立连接池、预热缓存冷启动可能需要几秒甚至几十秒。这期间客户端发来的请求会失败或超时。解决办法是在启动完成前不对外提供服务或者提供一个健康检查接口让客户端知道什么时候可以开始调用。7. 上线前的自查清单把上面四步走完你的 MCP Server 基本就具备生产级的底子了。最后给一份我自己的上线前自查清单你可以对照着过一遍检查项合格标准工具描述每个工具都有明确的用途、场景、参数说明参数校验所有输入都经过类型和范围检查异常处理任何异常都不会导致进程崩溃超时控制每个外部调用都有超时日志关键路径都有结构化日志含 trace ID指标能观测调用量、成功率、延迟优雅关闭收到信号能完成进行中的请求再退出配置管理配置通过环境变量注入启动时校验并发安全无共享可变状态或已做同步向后兼容工具变更不破坏已有客户端这份清单不是教条不同场景可以调整。但核心思路是一致的生产级意味着你要假设一切都会出错然后确保出错时服务还能活着、你还能查到原因。从跑通到生产级本质上是从证明它能工作到证明它在各种情况下都能工作的转变。这个转变需要的工作量往往比写第一版还大。但只有走完这一步你的 MCP Server 才真正能承担起 LLM 应用背后的工具支撑角色。
