1. 为什么我要用 FastMCP 搭第一个 MCP 服务如果你最近在折腾 AI Agent、Claude Desktop 或者 Cursor 这类工具大概率听过 MCPModel Context Protocol这个词。简单说MCP 就是一套让大模型能调用外部工具的协议标准——模型本身不会查数据库、不会读文件、不会调你的内部接口但通过 MCP 服务它就能像插了 USB 一样把这些能力接进来。FastMCP 则是 Python 生态里把这件事做得最省心的库几行代码就能把一个普通 Python 函数注册成 MCP 工具还自带 Streamable HTTP、stdio 等多种传输方式。这篇面向的是第一次上手 FastMCP 的 Python 开发者。我会带你从零跑通一个最小可用的 MCP 服务先写服务端再写客户端调用最后把 TaoToken 的统一 Key/API 通道接进config.toml骨架里让整个链路从本地调试到模型调用形成闭环。全程 Python 3.10 验证过代码可以直接复制。场景很具体你本地有个小工具函数比如查天气、算汇率、读配置想让它被 AI 客户端调用。以前你得写一堆 HTTP 路由、参数校验、错误处理现在用 FastMCP 一个装饰器搞定。下面按装环境 → 写服务 → 写客户端 → 接 TaoToken → 排错的顺序走一遍。2. 环境准备与 TaoToken 前置配置2.1 安装 FastMCP 与依赖先建个干净的虚拟环境避免和系统里的包打架python -m venv venv source venv/bin/activate # Windows 用 venv\Scripts\activate pip install fastmcpFastMCP 会自动带上httpx、pydantic这些依赖。装完可以验证一下版本python -c import fastmcp; print(fastmcp.__version__)我实测下来0.4.x 之后的版本对 Streamable HTTP 支持比较稳如果你装到的是更老的版本建议pip install -U fastmcp升一下。2.2 TaoToken 是什么为什么这里要接它MCP 服务本身只是工具提供方真正调用它的是模型。而模型调用需要一个统一的 API 通道——TaoToken 就是干这个的它把不同模型的调用收敛成一套 Key 和一套 API 地址你在config.toml里配一次后面换模型、加模型都不用改业务代码。官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。对 MCP 场景来说TaoToken 的价值在于你的 MCP 服务负责提供工具TaoToken 负责让模型能调这些工具两边解耦。下面先把 Key 拿到手。2.3 获取 API Key登录后进控制台在 API Keys 页面创建一个新 Key。建议按用途命名比如mcp-local-dev方便后面区分。创建后立刻复制保存——多数平台只显示一次。拿到 Key 后先别急着写代码用一条 curl 验证通道是否通curl https://taotoken.net/api/v1/models \ -H Authorization: Bearer sk-你的Key返回一个模型列表的 JSON 就说明 Key 和网络都没问题。这一步很关键很多人后面 MCP 调不通其实是 Key 或网络的问题提前排掉能省不少时间。3. 可复制的 FastMCP 服务端与客户端配置3.1 服务端最小示例server.py先写一个打招呼 算加法的双工具服务覆盖字符串和数值两种参数类型# server.py from fastmcp import FastMCP mcp FastMCP(nameMyFirstServer) mcp.tool def greet(name: str) - str: Greet a user by name. return fHello, {name}! mcp.tool def add(a: int, b: int) - int: Add two integers. return a b if __name__ __main__: mcp.run( transportstreamable-http, host127.0.0.1, port9000, )几个要点FastMCP(name...)里的名字会出现在客户端日志里起个能认出来的mcp.tool装饰器会把函数签名自动转成 MCP 的 JSON Schema所以类型注解必须写全name: str不能省成namemcp.run()里transportstreamable-http是重点这是目前推荐的 HTTP 传输方式比老的 SSE 更省连接。启动服务python server.py看到类似Uvicorn running on http://127.0.0.1:9000的日志就说明起来了。注意 MCP 的 HTTP 端点在/mcp路径下不是根路径。3.2 客户端调用脚本client.py# client.py import asyncio from fastmcp import Client config { mcpServers: { local: { url: http://127.0.0.1:9000/mcp, transport: streamable-http, } } } client Client(config) async def main(): async with client: tools await client.list_tools() print(available tools:, [t.name for t in tools]) greet_result await client.call_tool(greet, {name: world}) print(greet:, greet_result) add_result await client.call_tool(add, {a: 3, b: 4}) print(add:, add_result) if __name__ __main__: asyncio.run(main())async with client:会自动管理连接生命周期退出时释放资源别手动去 close。call_tool的第一个参数是工具名第二个是参数字典键名必须和服务端函数参数名一致。3.3 TaoToken 的 config.toml 配置骨架MCP 客户端比如 Claude Desktop、Cursor通常读一个config.toml或mcp.json来知道有哪些服务。把 TaoToken 作为模型通道接进来时骨架长这样# config.toml [model] provider taotoken base_url https://taotoken.net/api api_key sk-你的Key default_model 你的默认模型名 [mcp_servers.local] url http://127.0.0.1:9000/mcp transport streamable-http [mcp_servers.local.env] TAOTOKEN_BASE_URL https://taotoken.net/api TAOTOKEN_API_KEY sk-你的Key这里把模型通道和 MCP 服务分开配[model]段管模型调用[mcp_servers.*]段管工具服务。env段是给 MCP 服务进程注入环境变量用的如果你的 MCP 工具内部也要调模型就从这里读 Key别硬编码在代码里。注意api_key不要提交到 Git。本地开发用.env或系统环境变量config.toml加进.gitignore。4. 验证请求与成功结果4.1 先验证 MCP 服务本身服务端跑起来后用 curl 探一下端点是否活着curl -i http://127.0.0.1:9000/mcpStreamable HTTP 端点对 GET 的响应可能不是 200但只要不是Connection refused就说明端口通了。更靠谱的验证是直接跑客户端python client.py预期输出available tools: [greet, add] greet: Hello, world! add: 7看到available tools列出两个工具名说明服务端注册成功greet和add都返回正确结果说明调用链路通了。4.2 再验证 TaoToken 通道单独测一下模型通道确认 Key 有效curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的Key \ -H Content-Type: application/json \ -d { model: 你的模型名, messages: [{role: user, content: ping}] }返回带choices的 JSON 就说明通道正常。这一步和 MCP 服务是独立的——MCP 管工具TaoToken 管模型两边都通整个闭环才算成立。4.3 端到端串起来把 MCP 服务地址填进你的 AI 客户端Claude Desktop 的claude_desktop_config.json或 Cursor 的 MCP 设置模型通道指向 TaoToken。然后在对话里让模型调用greet工具比如输入用 greet 工具跟 alice 打个招呼。模型会通过 TaoToken 通道发起请求TaoToken 转发给模型模型决定调用 MCP 的greet工具MCP 服务返回结果整条链路跑通。5. 本篇常见错误排查5.1 Connection refused最常见。按顺序查服务端是否真的在跑看终端有没有 Uvicorn 日志端口是不是 9000被占用就换 9001URL 有没有带/mcp路径——很多人写成http://127.0.0.1:9000就报这个错。防火墙一般本地回环不拦但如果用了容器要确认端口映射。5.2 工具列表为空list_tools()返回空数组通常是装饰器没生效。检查两点mcp.tool有没有写在函数正上方中间不能隔空行或注释函数有没有类型注解。FastMCP 靠类型注解生成 Schemadef greet(name):这种没注解的会被跳过。5.3 参数校验失败调用时报ValidationError多半是参数名或类型对不上。服务端是def add(a: int, b: int)客户端就得传{a: 3, b: 4}传{x: 3}会直接报错。类型也要匹配传字符串3给int参数Pydantic 有时能转有时不能别赌老老实实传对类型。5.4 TaoToken 返回 401Key 错了或没带。检查Authorization: Bearer sk-xxx格式Bearer 后面有个空格别漏。Key 前后有没有多余空格或换行复制时容易带上。如果 Key 是在别的环境生成的确认它没被删除或过期。5.5 Streamable HTTP 握手超时客户端连上了但一直卡住可能是传输方式配错。服务端用streamable-http客户端也必须写streamable-http两边不一致会握手失败。另外确认 FastMCP 版本够新老版本可能不支持这个 transport。6. 下一步把 MCP 服务接进你的工作流跑通最小示例后你可以往几个方向扩给工具加更复杂的参数列表、嵌套对象FastMCP 会自动生成 Schema用mcp.resource注册资源而不只是工具把服务部署到内网让团队共用。模型通道这边TaoToken 的 Coding Plan 适合长期编码和 Agent 场景接入文档在 https://taotoken.net/api-keys 和 https://taotoken.net/doc 可以查到更细的配置项。我踩过的一个坑是一开始把 Key 硬编码在server.py里后来换环境忘了改调了半天才发现。现在统一走config.toml的env段注入代码里只读环境变量清爽很多。你如果只是本地玩先跑通greet和add这两个工具再往上加复杂度别一上来就搞多服务编排。