1. FastMCP 2.0 到底是什么为什么值得你花时间如果你已经写过 FastAPI第一次看到 FastMCP 2.0 的代码时大概率会愣一下这不就是把app.get换成了mcp.tool吗没错它想解决的就是同一类问题——把「函数」变成「可被外部调用的接口」只不过这次调用方从浏览器/前端换成了 LLM 应用和 Agent Runtime。FastMCP 2.0 是一个用 Python 构建 MCPModel Context Protocol服务器与客户端的框架。MCP 本身是给 LLM 设计的统一工具/数据接入标准你可以粗暴理解成「AI 世界的 USB-C」以前每个模型客户端都要为每个工具写一套适配现在只要工具方按 MCP 暴露能力Claude Desktop、你自己的 Agent、IDE 插件都能直接连。FastMCP 2.0 把协议里的传输、schema 生成、错误处理、认证这些脏活全包了你只负责写业务函数。它适合谁有 Python/FastAPI 基础、想把内部脚本/数据库/HTTP 服务快速变成 LLM 可调用工具的开发者。2.0 相比 1.0 最大的变化是1.0 已经并入官方 MCP Python SDK而 2.0 在它之上长成了一个完整生态——除了 Server还提供 Client、多 Server 组合与代理、从 OpenAPI/FastAPI 一键生成 MCP、内存级测试、认证等偏生产的能力。这意味着你不用再自己拼传输层也不用为了单测去起进程。这篇我会从零搭一个可跑的 MCP 服务端项目定义工具和资源本地用 STDIO 和 HTTP 两种方式调试最后把模型调用端点切到 TaoToken 的统一 Key/API 通道并用一次真实工具调用验证整条链路。全程命令可复制踩坑点我会单独拎出来讲。2. 环境准备与 TaoToken 统一通道前置配置动手前先把两件事理清Python 环境以及模型调用的出口。MCP Server 本身不绑定任何模型厂商它只负责暴露工具真正去调模型的是你的客户端或 Agent。所以我们要把「模型调用端点」统一到一个 Key 上避免后面在多个 SDK 之间来回换配置。我实测下来用 TaoToken 做统一通道的好处是Base URL 和 Key 一套配置Claude Code、Cline、Codex 这类工具都能复用不用每个客户端单独申请。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 根地址是 https://taotoken.net/api 注意这个不带 UTM 参数配置里填这个。先建项目目录结构如下后面所有文件都往里放fastmcp-demo/ ├── server.py # MCP 服务端定义工具/资源/提示 ├── client.py # 用 FastMCP Client 本地验证 ├── .env # 放 TAOTOKEN_API_KEY 等 └── requirements.txt依赖清单很轻requirements.txt内容fastmcp2.0.0 python-dotenv1.0.0 httpx0.27.0安装并确认版本python -m venv .venv source .venv/bin/activate # Windows 用 .venv\Scripts\activate pip install -r requirements.txt python -c import fastmcp; print(fastmcp.__version__)能打印出 2.x 的版本号就说明装好了。接着在.env里放统一通道的凭证注意 Key 从控制台生成不要硬编码进代码TAOTOKEN_API_KEYsk-你的key TAOTOKEN_BASE_URLhttps://taotoken.net/api这里有个容易忽略的点MCP Server 自己不需要 KeyKey 是给「调用模型的客户端」用的。但我们在项目里预留这套配置是为了后面把 Agent 的模型端点指过来时不用改结构。如果你要生成 Key去控制台页面 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 创建接入细节看文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。注意Base URL 填https://taotoken.net/api不要带末尾斜杠也不要混入 UTM 参数否则部分 SDK 会拼出错误路径导致 404。3. 可复制的 FastMCP 服务端配置与工具定义现在写server.py。FastMCP 2.0 的核心就是三个装饰器mcp.tool暴露可执行函数mcp.resource暴露只读数据mcp.prompt暴露提示模板。类型标注和 docstring 会被自动转成 JSON Schema所以标注写清楚LLM 才知道怎么传参。import os import httpx from dotenv import load_dotenv from fastmcp import FastMCP, Context load_dotenv() mcp FastMCP(demo-server) mcp.tool def add(a: int, b: int) - int: 两数相加返回整数结果。 return a b mcp.tool async def fetch_status(url: str) - str: 请求一个 URL 并返回 HTTP 状态码用于连通性检查。 async with httpx.AsyncClient(timeout10) as client: resp await client.get(url) return f{url} - {resp.status_code} mcp.resource(config://version) def version() - str: 返回当前服务版本号。 return 2.0.0-demo mcp.resource(config://endpoint) def endpoint() - str: 返回统一模型通道的 Base URL。 return os.getenv(TAOTOKEN_BASE_URL, https://taotoken.net/api) mcp.prompt def summarize(text: str) - str: 生成一个“请总结”的提示模板。 return f请用要点总结以下内容\n\n{text} if __name__ __main__: mcp.run()mcp.run()默认走 STDIO 传输适合被 Claude Desktop 这类客户端以子进程方式拉起。如果你想用 HTTP 调试改成mcp.run(transporthttp, host127.0.0.1, port8000, path/mcp)如果你已经有现成的 FastAPI 服务不想重写一遍工具FastMCP 2.0 支持直接生成。假设你有个app.py里定义了 FastAPI 的app对象from fastapi import FastAPI from fastmcp import FastMCP app FastAPI() app.get(/items/{item_id}) def read_item(item_id: int): return {item_id: item_id} mcp FastMCP.from_fastapi(app)这样每个路由会自动变成一个 MCP 工具省掉重复劳动。同理FastMCP.from_openapi()可以吃一份 OpenAPI 规范生成 MCP 服务。对于多服务场景用mcp.mount()把「搜索」「数据库」「知识库」几个子 Server 拼成一个大服务或者用as_proxy()把远端 SSE/HTTP 的 Server 桥接到本地再加一层鉴权。提示工具函数的 docstring 不是装饰它直接进 schema 的 description 字段LLM 靠它判断何时调用。写「两数相加」比写「add function」有用得多。4. 本地启动调试与真实工具调用验证先验证 STDIO 模式。写client.py用 FastMCP 自带的 Client 直连本地脚本这种方式不需要起网络进程import asyncio from fastmcp import Client async def main(): async with Client(server.py) as c: tools await c.list_tools() print(tools:, [t.name for t in tools]) res await c.call_tool(add, {a: 5, b: 7}) print(add , res.text) ver await c.read_resource(config://version) print(version , ver) asyncio.run(main())运行python client.py预期输出tools: [add, fetch_status] add 12 version 2.0.0-demo看到add 12就说明工具调用链路通了。接着验证 HTTP 传输先起服务python server.py # 或者用 CLIfastmcp run server.py --transport http --port 8000服务起来后把 client 里的连接方式换成 URLasync with Client(http://127.0.0.1:8000/mcp) as c: res await c.call_tool(fetch_status, {url: https://taotoken.net/api}) print(res.text)这一步会真实发起一次 HTTP 请求返回类似https://taotoken.net/api - 404或200的状态码——404 也正常因为根路径本来就没挂业务路由重点是证明工具能联网执行。到这里一个可被 LLM 调用的 MCP 服务就活了。接下来把模型端点切到统一通道。如果你用 Claude Code 这类编码 Agent配置里需要三件套Base URL、Key、Model ID。以环境变量方式注入export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的key export ANTHROPIC_MODELclaude-sonnet-4-20250514如果你用的是 Cline 或 Codex 这类工具配置项名称不同但三件套一致。Codex 的auth.json里对应字段是base_url和api_keyCline 的 MCP 配置里则是command/args加环境变量。核心原则Base URL 指向https://taotoken.net/apiKey 用控制台生成的Model ID 按你实际要用的模型填。想先确认模型通道是否通可以直接在模型对话页 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 发一条消息测试。5. 常见报错排查401、local proxy failed 与 reading choices这一节按真实报错来对。MCP 项目跑不起来八成卡在下面几个。401 UnauthorizedKey 没生效。先确认.env被load_dotenv()读到了再确认 Key 没有多余空格或换行。如果你把 Key 写进了客户端配置检查是不是复制时带了引号。统一通道的 Key 在控制台 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 重新生成一个对比测试最快。local proxy failed / connection refusedHTTP 模式下客户端连不上。检查mcp.run(transporthttp, ...)里的 host 和 port 是否和 client 里的 URL 一致path默认是/mcp漏了就会 404。另外确认服务进程真的在跑curl http://127.0.0.1:8000/mcp能返回内容说明端口通。reading choices / KeyError: choices这是模型返回体结构不符合预期通常发生在 Base URL 配错、请求打到了非兼容端点。确认你填的是https://taotoken.net/api而不是带 UTM 的官网地址后者是网页不是 API。如果用的是 OpenAI 兼容 SDK确认路径拼接后是/api/v1/chat/completions这类标准路径。OAuth / authentication failed多见于 Claude Code 首次接入。它默认可能走 OAuth 流程你需要显式用 API Key 模式设置ANTHROPIC_API_KEY并确保ANTHROPIC_BASE_URL指向统一通道。如果之前登录过旧账号清掉本地凭证缓存再试。工具 schema 报错 / 参数校验失败FastMCP 从类型标注生成 schema如果你写了def add(a, b)没标注类型schema 里就是空的LLM 不知道传什么。所有工具参数都要标类型复杂结构用 Pydantic 模型。排查顺序建议先list_tools确认工具注册成功再call_tool确认执行逻辑最后才接模型。分层验证能快速定位是 MCP 层的问题还是模型通道的问题。6. 把 MCP 项目接到长期编码与 Agent 工作流单次验证通过后下一步是让它进入日常。如果你只是偶尔调一下模型用模型对话页就够但如果你要把这个 MCP 服务挂到编码 Agent 上长期跑建议走 Coding Plan配置一次Base URL、Key、Model ID 三件套固定下来后面新增工具只要改server.py重新挂载即可。具体做法把server.py注册到你的 Agent 客户端配置里STDIO 模式填command: python、args: [server.py]HTTP 模式填 URL。然后在 Agent 的模型配置里把端点指向统一通道。这样 Agent 既能调用你定义的add、fetch_status又能通过统一 Key 访问模型不用维护两套凭证。我踩过的一个坑一开始把 MCP Server 和模型调用混在一个进程里结果 Server 重启会连带模型连接断掉。后来拆成两个进程——Server 只管暴露工具模型调用由客户端负责——稳定性好很多。另外工具函数尽量保持无状态和幂等LLM 可能重复调用同一个工具有副作用的操作要加确认机制。想系统看接入细节文档页 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 有各客户端的配置示例长期编码场景直接看 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。最后留一个实用技巧在server.py里加一个mcp.tool叫health_check返回服务启动时间和已注册工具数Agent 每次会话开始时调一次能快速判断服务是否正常比翻日志快得多。