FastMCP虽快但第一步不是把所有函数都暴露成工具

先给出几个核心判断：FastMCP 的吸引力非常直观——你只需编写一个普通的 Python 函数，并添加 mcp tool 装饰器，它就能自动变成 MCP 客户端可发现并调用的工具。对于正在为 Claude Code、Codex、Cursor 或 Aider 对接工具的开发人员来说，这条路径显然比从协议细节开始手动实现要轻量得多。

但这也恰好是 FastMCP 的第一个局限。一旦 MCP Server 被部署到真实的生产环境，它就不再只是“写了一个方便的函数”那么简单了。你暴露的是模型可以调用的行动入口，这些入口可能触及文件系统、网络、数据库、内部 API、OAuth Token，甚至是团队中那些尚未完善的脚本。

实际上，FastMCP 要解决的核心问题并非“如何让 AI 聊天”，而是“如何让工具能够通过 MCP 协议被调用”。

上游 README 中的最小示例已经阐述得非常清晰：一个普通的 Python 函数，通过 mcp tool 装饰器被注册为 MCP 工具。这个例子的关键并不在于 add 函数本身，而在于它将 Python 函数、参数类型、文档说明以及 MCP 工具注册的整个链路串联了起来。此外，FastMCP 还覆盖了 Server、Client、Apps 三个层级：Server 负责暴露 Tools / Resources / Prompts，Client 负责连接本地或远程的 MCP Server，而 Apps 则让工具在对话中呈现交互式 UI。

因此，它的适用场景非常明确：将一组内部 Python 能力封装成 MCP 工具；为现有 MCP Server 编写客户端或封装层；用更少的样板代码验证 Tool Schema、传输协议、认证方式和生命周期；让 AI 宿主能够通过 MCP 协议调用那些经过明确定义的能力。

最容易犯的错误，就是把“快速注册”等同于“低风险”。

安装 FastMCP 只是安装步骤，远非上线证明。真正需要优先明确的是：这个工具是否只读？工具的参数是否允许模型传入路径、SQL、Shell 命令或 URL？函数内部是否默认读取环境变量、配置文件或用户目录？MCP Client 能看到哪些 Tool / Resource / Prompt 的名称？失败时返回的是可诊断的错误信息，还是直接将内部异常暴露给模型？这个 Server 是通过本地 stdin/stdout 运行，还是通过远程 HTTP 运行？如果配置了 OAuth 或 JWT，未认证的请求是否会绕过你以为存在的中间件日志？

FastMCP 的优势在于让接入变得极为迅速。但正因为快，第一轮的验证反而需要放慢脚步。

一个更稳妥的初次接入方式，大致可以分为五个步骤：

第一步，只注册一个没有任何副作用的工具，比如 add(a, b) 或者读取固定 fixture 的函数。目的不是展示能力，而是确认 MCP Host 能看到工具名称、参数 Schema 和返回值。第二步，按只读、会写入、会外联、触碰凭据、执行用户输入等维度对工具进行分类，不要一开始就挂载所有类型。第三步，明确写明运行方式：是通过 stdin/stdout、本地 HTTP、远程 HTTP，还是作为封装层运行。第四步，仔细检查错误形态。第五步，再接入真实工具，同时记录好工具清单、参数范围、凭据来源、回滚方式和验证命令。

当你准备把 FastMCP 的上下文交给 Claude Code、Codex、Cursor 或 Aider 时，不要只提供一句“FastMCP 是一个 MCP 框架”的摘要。更有价值的是一份可执行的合约：上游文档负责 API 细节；Doramagic Pack 负责边界条件、常见陷阱、冒烟检查和故障排查；第一次运行必须在临时目录或临时配置中完成；先列出工具清单，再调用工具；涉及文件写入、网络请求、Shell 执行、浏览器操作、密钥读取、远程 API 调用时，先请求授权；任何“已接入成功”的结论，都必须附带工具列表、Host 配置位置、运行命令和验证输出。

总的来说，如果你的目标是让一组 Python 能力以 MCP 工具的形式稳定暴露出来，FastMCP 确实非常合适——特别是当你需要同时考虑 Schema、Client、Transport、Auth 或 App Surface 时，它能帮你省去大量底层样板代码。但如果你的目标仅仅是让模型编写一次性脚本，FastMCP 可能显得过于超前。先明确函数本身、输入输出和权限边界，再考虑接入 MCP。