三个内部 MCP Server 的工程复盘
AI 总结
据掘金·人工智能的一线工程复盘,某团队将工单查询、发布记录和配置数据封装为三个 MCP Server,上线两周后日均调用约 200 次。文章建议为 JSON-RPC 消息独占 stdout、将日志写入 stderr,并裁剪工具返回内容、分页列表结果、设置低于 30 秒的超时,以及返回带操作提示的结构化错误。部署规模与前后效果数据均为作者单方自述,未获独立验证。
深度见解
这篇复盘给出了 MCP 落地的具体工程做法,涵盖进程管理、输出裁剪、超时和错误契约,直接影响 AI 客户端能否可靠调用内部工具。
上个月我们组接了个需求:让 AI 客户端能直接查工单、看发布记录、读配置中心。听起来像是写几个 HTTP 客户端就完事,实际做下来,真正花时间的部分是"进程被谁启动、在什么环境下启动、失败了怎么告诉模型"这三件事。三个 Server 上线两周,日均调用 200 次左右,我把踩坑和最终的设计取舍整理成这篇复盘,重点放在工程侧而不是协议介绍。
一、MCP 的进程模型决定了大部分设计约束
MCP 是基于 JSON-RPC 2.0 的通信协议,客户端以子进程方式拉起 Server,通过 stdin/stdout 交换消息。这个模型有三个直接后果,每个都影响架构决策。
第一,stdout 被协议独占。任何 print 都会污染消息流,导致客户端解析失败。我们统一在项目模板里加了一条 lint 规则,禁止在 server.py 及其依赖模块里出现裸 print,日志一律走 stderr:
import sys
def log(level: str, msg: str) -> None:
print(f"[{level}] {msg}", file=sys.stderr, flush=True)