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

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

FastMCP 的吸引力很直接：你写一个普通 Python 函数，加上 @mcp.tool，它就可以变成 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 里的最小例子很清楚：

from fastmcp import FastMCP

mcp = FastMCP("Demo")

@mcp.tool
def add(a: int, b: int) -> int:
    """Add two numbers"""
    return a + b

if __name__ == "__main__":
    mcp.run()

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

所以它适合的任务不是“让 agent 更会说话”，而是：

• 把一组内部 Python 能力整理成 MCP 工具；
• 给已有 MCP server 写客户端或代理；
• 用更少样板代码验证工具 schema、transport、auth 和生命周期；
• 让 AI 宿主可以通过 MCP 使用明确命名的能力。

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

uv pip install fastmcp 或 pip install fastmcp 只是安装步骤，不是上线证明。

真正要先问的是这些问题：

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

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

一个更稳的第一次接入方式

第一步，只注册一个无副作用工具。比如 add(a, b) 或读取固定 fixture 的函数。目的不是展示能力，而是确认 MCP host 能看到工具名、参数 schema 和返回值。

第二步，把工具分成三类：只读、会写入、会外联。不要一开始就把三类都挂上去。先让 AI 宿主只看到只读工具，确认它不会自己要求扩大权限。

第三步，写清楚运行方式。FastMCP 可以服务 server/client/app 场景，但你的第一轮应该说明是 stdio、本地 HTTP、远程 HTTP，还是通过代理接入。不同 transport 的认证、日志和网络边界不一样。

第四步，检查错误形态。给工具传一个错误参数，看模型看到的错误是否足够具体，又不会泄露内部路径、token、数据库连接串或堆栈细节。

第五步，再接真实工具。接之前先记录工具清单、参数范围、凭据来源、回滚方式和验证命令。没有这些记录，就不要让 AI 宿主把这个 server 当成“可用工具箱”。

装进 AI 宿主时，给它一份合约，不是简介

把 FastMCP 上下文交给 Claude Code、Codex、Cursor 或 Aider 时，不要只给“FastMCP 是一个 MCP 框架”的摘要。更有用的是一份执行合约：

• 上游文档负责 API 细节。
• Doramagic pack 负责边界、pitfall、smoke check 和 failure check。
• 第一次运行必须在临时目录或临时配置里完成。
• 先列出工具清单，再调用工具。
• 涉及文件写入、网络、shell、浏览器、密钥、远程 API 时先请求授权。
• 任何“已接入成功”的说法都要附带工具列表、host 配置位置、运行命令和验证输出。

这样做的价值很实际：你不会把一个快速 demo 误当成团队级 MCP 入口。

什么时候 FastMCP 值得上

如果你的目标是让一组 Python 能力以 MCP 工具形式稳定暴露，FastMCP 很适合。尤其是你需要 schema、client、transport、auth 或 app surface 一起进入考虑时，它能省掉大量底层样板。

如果你的目标只是让模型写一段一次性脚本，FastMCP 可能太早。先把函数本身、输入输出和权限边界定清楚，再接 MCP。

判断标准很简单：当你能回答“这个工具能做什么、不能做什么、谁能调用、失败怎么证明、如何撤回”时，再让 FastMCP 帮你加速。否则，加速的只是混乱。