Python开发者拥抱MCP最快路径：FastMCP 3.x实战，30行代码给AI Agent装上新工具

Anthropic在2024年11月开源的MCP协议，如今已是AI Agent连接外部系统的事实标准。Claude、ChatGPT、Gemini、Cursor全部原生支持，GitHub上modelcontextprotocol/servers仓库聚集了Filesystem、GitHub、Slack、Postgres等一长串官方实现。对Python开发者来说，问题只有一个：怎么用最少的代码，把自家业务接口挂到AI上。

答案藏在PrefectHQ团队维护的FastMCP里。

一个装饰器，搞定一个工具

安装只需一条命令：

“`bash

uv pip install fastmcp

“`

写一个能被大模型调用的工具，代码量比写一个Flask路由还少：

“`python

from fastmcp import FastMCP

mcp = FastMCP(“订单查询服务”)

@mcp.tool()

def get_order(order_id: str) -> str:

“””根据订单号查询物流状态”””

return query_logistics(order_id)

if __name__ == “__main__”:

mcp.run()

“`

`@mcp.tool()`装饰器自动读取函数签名和docstring，生成符合MCP规范的工具定义。参数校验交给Pydantic处理，类型标注写清楚，模型端就能正确传参。30行之内，一个可用的MCP服务器就跑起来了。资源、提示词模板同样用装饰器暴露，写法一致。

SDK v2落地，底层协议全部重写

2026年8月2日，官方MCP Python SDK v2结束测试期，`mcp==2.0.0`正式发布，对应2026-07-28版协议规范。这次升级动作很大：协议类型拆进独立的mcp_types包，模型字段统一为snake_case，服务器请求处理模型整个换掉，旧的`mcp.server.fastmcp`导入路径直接移除，核心类更名为MCPServer。

好消息是FastMCP 3.x几乎吸收了全部改动。官方文档的说法很明确：大多数FastMCP 3服务器升级到新SDK时一行代码都不用改。会话握手被取消，多轮请求成为原生能力，OpenTelemetry默认开启，生产环境观测从可选项变成标配。

三个进阶能力，决定你能不能上生产

工具错误可返回。 旧版本里工具出错只能抛异常，模型拿到的是一坨 traceback。FastMCP 3.x提供`ToolResult(…, is_error=True)`，错误信息结构化地交还给模型，它能自己判断该重试还是换路走，Agent的自主性立刻上一个台阶。

远程服务本地化。 `uvx fastmcp-remote https://example.com/mcp`可以把远程服务器桥接回只支持stdio的宿主。代理层做了加固，上游缺失或URL配置错误会在握手阶段报错，杜绝假连接。FastMCP签发的token还能活得比上游短时token更久，长时间空闲的会话不会被误杀。

OAuth代理。 接GitHub这类需要OAuth 2.1认证的上游，FastMCP提供现成代理方案，令牌管理不需要自己造轮子。

调试环节：一条命令看穿一切

本地调试用官方Inspector：

“`bash

npx @modelcontextprotocol/inspector

“`

浏览器里打开图形界面，工具列表、参数校验、调用结果、协议报文全部可视。接入Claude Desktop更简单，配置文件里加一行服务器路径即可联调。

选型建议

写Python，直接上FastMCP 3.x，别碰裸SDK，省下的时间足够多写五个工具。写TypeScript，同一团队维护的FastMCP for TypeScript是对应选择。追求极致控制、需要自定义传输层的团队，再看官方SDK。

MCP生态的窗口期就在眼前。Python开发者手里有成千上万的内部接口和数据源，用FastMCP包一层，这些资产立刻变成AI Agent可以调用的工具。一个下午的投入，换来自动化办公、智能客服、数据问答这些场景的入场券，这笔账怎么算都划算。