上个月给内部 Agent 接 MCP 工具，想着不就是个协议嘛，照着文档抄就行。结果一晚上踩了 3 个坑，工具要么注册不上，要么 Agent 调了没反应，要么返回结果把上下文撑爆。下面挨个说。
MCP（Model Context Protocol）本质上就是让 Agent 能发现和调用外部工具的标准协议，分 Host（Agent 端）、Client（连接层）、Server（工具提供方）三层。听起来简单，真接起来全是细节。
坑 1：MCP Server 启动了，Agent 就是看不到工具
最开始用 stdio 模式起了个 MCP Server，日志里显示服务正常启动，工具也注册了。结果 Agent 端列工具的时候空空如也，一个都看不到。
排查了半天才发现：stdio 模式下，MCP Server 的 stdout 是协议通道，任何 print 到 stdout 的调试信息都会污染协议流，导致 Host 端解析失败，工具列表为空。我在 Server 代码里写了几个 print("工具已注册") 调试语句，就是这几行把协议搞崩了。
解决方式：
- 调试信息一律走 stderr，stdout 只留给 MCP 协议
- 或者直接用 logging 模块，配置输出到 stderr
- 排查时先抓 Server 的 stderr 日志，看有没有协议解析错误
改完之后，Agent 端 list_tools 终于能列出工具了。
坑 2：FastMCP 版本升级，代码直接跑不起来
第二个坑更坑。一开始图省事用了 FastMCP（一个 MCP 的高级封装库），照着 3.x 的文档写了个 Server。结果一跑就报 AttributeError: 'Server' object has no attribute 'tool'，方法全变了。
查了下才知道，FastMCP 3.4 做了 breaking change：装饰器从 @mcp.tool() 改成了新的注册方式，参数名也全换了。网上大部分教程还是 2.x 的写法，直接抄过来全报错。
两条路解决：
- 省事的：锁定 FastMCP 版本，
pip install fastmcp==3.3.0，用稳定版不追新 - 长期的：直接用官方原生
mcpSDK（mcp.server.Server+stdio_server），虽然代码多写几行，但 API 稳定、文档跟得上，不会隔个版本就崩
我后来直接换成了原生 mcp SDK，虽然多写了点样板代码，但再也没遇到版本兼容问题。生产环境别图省事用封装库，原生 SDK 最稳。
坑 3：工具返回结果太大，Agent 上下文直接爆炸
第三个坑是上线后才发现的。有个工具是查数据库的，一次返回几百条记录，Agent 拿到结果后直接开始胡言乱语——上下文被撑爆了，模型根本处理不了这么多 token。
一开始以为是模型不行，后来才搞明白：MCP 工具返回的内容会全部塞进 Agent 的上下文，一条工具返回 5000 token，调几次就把 32k 上下文吃满了。
解决方式：
- 工具端做分页和截断，默认只返回前 20 条，需要更多再翻页
- 返回结果做结构化摘要，别把原始数据全丢给 Agent，让 Agent 看摘要就行
- 大结果走文件输出，工具返回文件路径，Agent 需要时再读文件
改完之后，Agent 上下文占用降了 80%，回答也正常了。
踩完的结论
MCP 协议本身设计得不错，标准化了 Agent 和工具之间的通信，但工程落地全是细节。几个直接能用的结论：
- stdio 模式下 stdout 是协议通道，调试信息走 stderr，别污染协议流
- 生产环境用原生 mcp SDK，别图省事用 FastMCP 这类封装库，版本升级就崩
- 工具返回必须做截断和摘要，几百条原始数据直接丢给 Agent，上下文必爆
- 先跑通单工具再扩展，别一上来接十几个工具，出问题都不知道是哪个
MCP 2026 年已经升级成生产级协议了，认证、流式传输、企业治理都补上了，后面 Agent 接工具基本都会走 MCP。这几个坑我踩过了，你直接跳过。
📌 更多 AI 实战干货、踩坑记录，欢迎关注公众号 「你的应急食品」
📌 更多 AI 实战干货、踩坑记录，欢迎关注公众号 「你的应急食品」
