企业官网建设流程全解析

1. 为什么我会盯上 FastMCP 这个库

如果你最近在折腾智能体，大概率听过 MCP（Model 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(transport="http", port=8080)

这里有几个点值得展开。@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(transport="http", port=8090)，客户端连接地址同步改。别用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(transport="http", port=8000)

客户端只需要连网关一个地址，就能发现所有子服务的能力。这对多智能体编排场景很实用——每个业务线维护自己的 MCP 服务，网关统一对外。

模型侧接入这块，如果你只是验证对话效果，用模型对话页面快速试；要长期跑编码类或 Agent 类任务，Coding Plan 更合适；API Key 的创建和管理在控制台，接入参数看接入文档。把模型入口和 MCP 服务端都配好，你的智能体通信链路就从「能跑」进入「能用」了。