GitHub项目推荐--FastMCP：用Pythonic方式构建下一代智能体通信协议

1. 为什么我会盯上 FastMCP 这个库如果你最近在折腾智能体大概率听过 MCPModel Context Protocol这个词。简单说它是一套让大模型和外部工具、数据源对话的通信协议你可以把它理解成「AI 世界的 USB-C 接口」——只要设备支持这个口插上就能用。但真去手写协议层光是消息序列化、传输通道、生命周期管理就够劝退一批人。FastMCP 就是来解决这个问题的它把 MCP 的协议细节封装成 Python 装饰器你写业务逻辑它管通信。FastMCP 适合谁三类人最该看一是想给自己项目加个「能被大模型调用」的工具层但不想啃协议文档的后端开发二是做智能体编排需要把多个小服务挂到一个网关下的架构同学三是想快速验证 MCP 链路能不能跑通、本地起个服务测连通性的折腾党。它用起来的感觉很像 FastAPI——定义函数、加装饰器、run()启动剩下的交给框架。我实测下来一个带工具、资源、提示词模板的 MCP 服务端核心代码不到 20 行就能跑起来。这篇就按「最小可跑通链路」来写先讲清楚 FastMCP 的核心抽象再给可复制的服务端骨架和客户端调用最后把本地启动和连通性验证的动作拆开顺带把几个容易踩的坑列出来。2. TaoToken 前置给智能体链路准备一个模型入口MCP 服务端本身不产生智能它只是把能力暴露出去。真正让链路「活」起来的是背后那个能理解意图、决定调哪个工具的模型。所以在你跑通 FastMCP 之前得先有一个稳定的模型调用入口。我这边用的是 TaoToken 的 API 来做模型侧接入。它的定位是给开发者和智能体应用提供统一的模型调用通道支持对话、代码补全这类常见能力接口风格和主流 SDK 兼容改个base_url和api_key就能接上。对 FastMCP 场景来说它的价值在于当你的 MCP 客户端需要ctx.sample()去请求模型补全时背后得有个能扛住并发、响应稳定的端点。操作路径很直接进控制台创建 API Key然后在你的客户端或智能体代码里把模型请求指向 TaoToken 的 API 地址。如果你后面要做长期编码类智能体或者 Agent 编排可以看下 Coding Plan它更适合持续性的开发任务只是临时验证模型对话效果用模型对话页面就够了。接入细节和参数说明在接入文档里写得很清楚照着填即可。注意API Key 属于敏感凭证别硬编码进提交到 Git 的脚本里用环境变量或本地配置文件管理。3. 可复制的 FastMCP 服务端配置骨架先把环境弄干净。FastMCP 要求 Python ≥ 3.10推荐用 uv 管理依赖装起来快、隔离也干净。# 用 uv 安装 fastmcp uv pip install fastmcp # 验证安装是否成功 fastmcp --version装完之后新建一个weather_agent.py这就是我们的最小服务端。它暴露一个工具查询天气、一个资源按主题取新闻、一个提示词模板生成摘要指令覆盖 MCP 的三种核心抽象。# weather_agent.py from fastmcp import FastMCP, Context # 创建 MCP 服务实例名字会出现在客户端发现列表里 mcp FastMCP(天气与新闻助手) mcp.tool def weather_search(city: str, ctx: Context) - str: 获取指定城市的天气信息 # ctx.info 会向客户端实时推送日志方便调试 ctx.info(f正在查询 {city} 的天气...) # 这里用假数据演示实际可替换为真实天气 API 调用 return f{city} 今天 25°C晴适合出门 mcp.resource(news://{topic}) def get_news(topic: str) - str: 按主题返回新闻摘要资源是只读端点 return f{topic} 领域最新进展某团队发布了新的推理优化方案... mcp.prompt def summarize_prompt(text: str) - str: 生成一段用于摘要的提示词模板 return f请用中文简洁总结以下内容\n{text[:1000]} if __name__ __main__: # 用 http 传输启动端口 8080方便本地客户端连接 mcp.run(transporthttp, port8080)这里有几个点值得展开。mcp.tool装饰的函数会被注册成可执行操作客户端通过call_tool调用mcp.resource注册的是只读数据端点用 URI 模板匹配客户端用read_resource读取mcp.prompt则是可复用的对话模板。Context对象是 FastMCP 的上下文管理入口ctx.info()推日志ctx.read_resource()能链式访问其他 MCP 服务ctx.sample()可以请求客户端侧的模型补全——这三个能力是它区别于裸写协议的地方。传输方式上STDIO 适合命令行工具集成HTTP/SSE 适合 Web 应用交互内存通道适合单元测试。本地验证用 HTTP 最直观因为你能用浏览器或 curl 直接探。4. 客户端调用与连通性验证服务端起在 8080 之后先别急着写复杂客户端用最直接的方式确认链路是通的。开另一个终端# 确认服务端口在监听 curl -s http://127.0.0.1:8080/mcp | head -c 200如果返回了协议相关的响应不同版本可能返回 JSON-RPC 结构或能力描述说明服务端已经起来了。接下来写一个 Python 客户端把工具调用和资源读取都跑一遍。# client_demo.py import asyncio from fastmcp import Client async def main(): # 连接到本地 HTTP 服务端 async with Client(http://127.0.0.1:8080/mcp) as client: # 1. 列出服务端暴露的工具 tools await client.list_tools() print(可用工具:, [t.name for t in tools]) # 2. 调用天气工具 result await client.call_tool( weather_search, {city: 杭州} ) print(工具返回:, result) # 3. 读取新闻资源 news await client.read_resource(news://AI) print(资源内容:, news) # 4. 获取提示词模板 prompt await client.get_prompt( summarize_prompt, {text: FastMCP 让 MCP 服务开发变得像写 FastAPI 一样简单} ) print(提示词:, prompt) if __name__ __main__: asyncio.run(main())跑python client_demo.py你应该能看到四段输出工具列表里有weather_search工具返回杭州的天气字符串资源返回 AI 领域新闻提示词返回拼接好的摘要指令。到这一步一个最小的智能体通信链路就算跑通了——服务端暴露能力客户端发现并调用中间走的是标准 MCP 协议。如果你想把模型也接进来让客户端在拿到工具结果后请求模型做二次加工就把模型请求指向 TaoToken 的 API 端点用ctx.sample()或直接在客户端侧调用模型接口。这样链路就变成用户提问 → 模型决定调工具 → MCP 服务端执行 → 结果回传模型 → 模型生成最终回答。5. 本篇常见错排查启动报端口占用。8080 被别的服务占了换端口即可mcp.run(transporthttp, port8090)客户端连接地址同步改。别用kill -9硬杀先lsof -i :8080看清楚是谁。客户端连不上报连接拒绝。先确认服务端进程还活着再看地址写对没有。HTTP 传输的路径通常是/mcp少写这段会 404。如果你在容器里跑服务端注意端口映射-p 8080:8080别漏。call_tool报参数不匹配。FastMCP 会根据函数签名做参数校验city是必填的字符串传{city: 123}会失败。参数名要和函数定义完全一致别用驼峰。资源 URI 读不到。mcp.resource(news://{topic})里的模板变量必须和函数参数名对应读的时候 URI 要完整匹配news://AI对news://ai/多斜杠就不对。ctx.info()没输出。日志是推给客户端的如果你用 curl 直接探看不到这些推送。用 Python 客户端跑或者在服务端加标准 logging 输出到控制台。Python 版本低于 3.10。FastMCP 用了较新的类型语法3.9 及以下会直接报语法错。python --version确认一下不够就升级或用 uv 建个 3.11 的虚拟环境。6. 把链路接进你的真实项目跑通最小链路之后下一步通常是两件事一是把假数据换成真实 API二是把多个小服务挂到一个网关下。FastMCP 的mount方法就是干这个的gateway FastMCP(企业网关) gateway.mount(weather_mcp) # 挂载天气服务 gateway.mount(news_mcp) # 挂载新闻服务 gateway.run(transporthttp, port8000)客户端只需要连网关一个地址就能发现所有子服务的能力。这对多智能体编排场景很实用——每个业务线维护自己的 MCP 服务网关统一对外。模型侧接入这块如果你只是验证对话效果用模型对话页面快速试要长期跑编码类或 Agent 类任务Coding Plan 更合适API Key 的创建和管理在控制台接入参数看接入文档。把模型入口和 MCP 服务端都配好你的智能体通信链路就从「能跑」进入「能用」了。