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

FastMCP 的吸引力很直接：你写一个普通 Python 函数，加上 mcp tool decorator，它就可以变成 MCP 客户端能发现和调用的工具。对正在给 Claude Code、Codex、Cursor 或 Aider 接工具的人来说，这条路径比从协议细节开始手写要轻很多。

但这也是 FastMCP 的第一个边界。MCP server 一旦接到真实宿主，就不是“写了一个方便的函数”这么简单了。你暴露的是模型可以调用的行动入口，可能会碰到文件、网络、数据库、内部 API、OAuth token 或团队里的半成品脚本。

Doramagic 项目页：

https://doramagic.ai/zh/projects/fastmcp/

Doramagic 项目说明书：

https://doramagic.ai/zh/projects/fastmcp/manual/

上游项目：

https://github.com/PrefectHQ/fastmcp

FastMCP 解决的不是“怎么聊天”，而是“怎么把工具接进 MCP”。

FastMCP 上游 README 里的最小例子很清楚：一个普通 Python 函数，通过 mcp tool decorator 被注册成 MCP 工具。这个例子真正重要的地方不是 add，而是它把 Python 函数、参数类型、说明文档和 MCP 工具注册串起来了。FastMCP 还覆盖 server、client、apps 三个面：server 暴露 tools/resources/prompts，client 连接本地或远程 MCP server，apps 让工具在对话里呈现交互 UI。

所以它适合的任务不是“让 agent 更会说话”，而是：把一组内部 Python 能力整理成 MCP 工具；给已有 MCP server 写客户端或代理；用更少样板代码验证 tool schema、transport、auth 和生命周期；让 AI 宿主可以通过 MCP 使用明确命名的能力。

最容易犯的错，是把快速注册当成低风险。

安装 FastMCP 只是安装步骤，不是上线证明。真正要先问的是：这个工具是否只读？工具参数会不会让模型传入路径、SQL、shell 命令或 URL？函数里有没有默认读取环境变量、配置文件或用户目录？MCP client 能看到哪些 tool/resource/prompt 名称？失败时返回的是可诊断错误，还是把内部异常原样暴露给模型？这个 server 是本地 标准输入输出 运行，还是远程 HTTP 运行？如果接了 OAuth/JWT，未认证请求会不会绕过你以为存在的中间件日志？

FastMCP 的好处是让接入很快。正因为快，第一轮验证更要慢一点。

一个更稳的第一次接入方式：第一步，只注册一个无副作用工具。比如 add(a, b) 或读取固定 fixture 的函数。目的不是展示能力，而是确认 MCP host 能看到工具名、参数 schema 和返回值。第二步，把工具分成只读、会写入、会外联、触碰凭据、执行用户输入几类。不要一开始就把所有类型都挂上去。第三步，写清楚运行方式：标准输入输出、本地 HTTP、远程 HTTP，还是代理。第四步，检查错误形态。第五步，再接真实工具，并记录工具清单、参数范围、凭据来源、回滚方式和验证命令。

把 FastMCP 上下文交给 Claude Code、Codex、Cursor 或 Aider 时，不要只给“FastMCP 是一个 MCP 框架”的摘要。更有用的是一份执行合约：上游文档负责 API 细节；Doramagic pack 负责边界、pitfall、smoke check 和 failure check；第一次运行必须在临时目录或临时配置里完成；先列出工具清单，再调用工具；涉及文件写入、网络、shell、浏览器、密钥、远程 API 时先请求授权；任何“已接入成功”的说法都要附带工具列表、host 配置位置、运行命令和验证输出。

如果你的目标是让一组 Python 能力以 MCP 工具形式稳定暴露，FastMCP 很适合。尤其是你需要 schema、client、transport、auth 或 app surface 一起进入考虑时，它能省掉大量底层样板。如果你的目标只是让模型写一段一次性脚本，FastMCP 可能太早。先把函数本身、输入输出和权限边界定清楚，再接 MCP。