FastMCP 开发 MCP Server 完全实战指南：用装饰器与 config.toml 接入 TaoToken

1. 为什么 FastMCP 值得你花一个下午跑通如果你写过原生 MCP Python SDK 的 Server大概记得那种感觉注册一个工具要手写 JSON Schema、手动分发tools/list和tools/call、参数校验和错误处理全靠自己兜。一个能用的 Server 动辄三四十行样板代码改一个参数类型要同步改三处。FastMCP 把这件事压成了装饰器函数签名即 Schemadocstring 即工具描述mcp.tool一贴就注册完成。它现在是 Python 圈构建 MCP Server 最主流的框架绝大多数公开的 MCP Server 都用它写。这篇面向已经会写 Python、想快速把本地能力暴露给 AI 客户端的开发者。我会带你从零搭一个可运行的 Server重点讲清楚三件事装饰器怎么注册工具与资源、参数校验怎么靠类型注解自动完成、以及怎么用一份config.toml把模型调用统一走 TaoToken 的 Key 和 API 通道。全程可复制跑完你能得到一个本地能调、客户端能连、模型能用的完整链路。适合谁想给自己项目加 MCP 能力的后端、想把内部工具接进 Cursor/Claude 的工程师、以及第一次接触 MCP 协议想找条最短路径的人。2. 前置准备环境、依赖与 TaoToken 通道2.1 Python 环境与 FastMCP 安装要求 Python 3.10 以上推荐 3.12。包管理我建议用 uvFastMCP 的命令行工具依赖它速度也比 pip 快很多。# 安装 uvmacOS / Linux curl -LsSf https://astral.sh/uv/install.sh | sh # Windows PowerShell powershell -c irm https://astral.sh/up/install.ps1 | iex # 验证 uv --version建项目并装依赖mkdir fastmcp-demo cd fastmcp-demo uv init uv add fastmcp httpx如果你习惯 pippip install fastmcp httpx同样可以只是后面fastmcp dev这类命令需要 uv 在 PATH 里。2.2 为什么要在 MCP Server 里接 TaoTokenMCP Server 本身只负责暴露工具但很多工具内部要调模型——比如一个「代码审查」工具、一个「文本摘要」工具。如果每个工具各自去配 Key、各自处理不同厂商的 base_url配置会散得到处都是。TaoToken 提供统一的 Key 和 API 通道你只需要在config.toml里写一份所有工具共享。这样换模型、换通道只改一个文件不用动业务代码。先去控制台拿 Key访问 https://taotoken.net/console 在 API Keys 页面创建一个。接入文档在 https://taotoken.net/doc 里面有各语言的调用示例。API 基址是https://taotoken.net/api注意这个地址不带任何查询参数。注意Key 只显示一次创建后立刻复制保存。不要把它硬编码进提交到 Git 的代码里用环境变量或本地配置文件。3. 可复制配置config.toml 骨架与 Server 代码3.1 config.toml 完整骨架在项目根目录建config.toml# config.toml —— MCP Server 统一配置 [server] name FastMCP Demo transport stdio # 本地开发用 stdio远程部署改 streamable-http host 0.0.0.0 port 8000 [taotoken] # 统一模型通道所有工具共享这一份配置 base_url https://taotoken.net/api api_key sk-你的Key # 生产环境请改用环境变量注入 default_model claude-sonnet-4-20250514 timeout 60 [tools] # 工具级开关方便按环境裁剪 enable_summarize true enable_code_review true max_input_chars 8000读取配置用一个轻量函数避免引入额外依赖# config_loader.py import tomllib from pathlib import Path def load_config(path: str config.toml) - dict: with open(Path(path), rb) as f: return tomllib.load(f) CONFIG load_config()tomllib是 Python 3.11 起的内置库3.10 用户装tomli并把 import 换成import tomli as tomllib即可。3.2 用装饰器注册工具与资源核心文件server.py。这里演示三种注册方式普通工具、带校验的工具、以及只读资源。# server.py import httpx from typing import Literal, Optional from fastmcp import FastMCP from fastmcp.exceptions import ToolError from config_loader import CONFIG mcp FastMCP( nameCONFIG[server][name], instructions演示用 MCP Server提供文本摘要与代码审查工具。, ) TAO CONFIG[taotoken] async def call_model(prompt: str, model: Optional[str] None) - str: 统一走 TaoToken 通道调用模型 payload { model: model or TAO[default_model], messages: [{role: user, content: prompt}], } headers { Authorization: fBearer {TAO[api_key]}, Content-Type: application/json, } async with httpx.AsyncClient(timeoutTAO[timeout]) as client: resp await client.post( f{TAO[base_url]}/v1/chat/completions, jsonpayload, headersheaders, ) resp.raise_for_status() data resp.json() return data[choices][0][message][content] mcp.tool async def summarize(text: str, style: Literal[brief, detailed] brief) - str: 对输入文本做摘要。 Args: text: 待摘要的原文长度不超过配置上限 style: 摘要风格brief 为要点式detailed 为段落式 Returns: 摘要结果字符串 limit CONFIG[tools][max_input_chars] if len(text) limit: raise ToolError(f输入长度 {len(text)} 超过上限 {limit}请先截断) if not text.strip(): raise ToolError(text 不能为空) instruction 用三到五条要点总结 if style brief else 用一段话详细总结 return await call_model(f{instruction}以下内容\n\n{text}) mcp.tool async def code_review(code: str, language: str python) - str: 对代码片段做审查返回问题清单与改进建议。 if not CONFIG[tools][enable_code_review]: raise ToolError(code_review 工具在当前环境已禁用) prompt ( f你是资深 {language} 工程师请审查以下代码 f指出潜在 bug、性能问题与可读性问题\n\n{language}\n{code}\n ) return await call_model(prompt) mcp.resource(config://runtime) def runtime_config() - dict: 暴露当前运行配置脱敏供客户端查看。 return { server_name: CONFIG[server][name], default_model: TAO[default_model], max_input_chars: CONFIG[tools][max_input_chars], } if __name__ __main__: transport CONFIG[server][transport] if transport streamable-http: mcp.run( transportstreamable-http, hostCONFIG[server][host], portCONFIG[server][port], ) else: mcp.run()几个关键点值得展开。mcp.tool会自动把函数名当工具名、docstring 当描述、类型注解转成 JSON Schema所以style: Literal[brief, detailed]会被约束成枚举客户端传别的值直接报错不用你写校验。ToolError抛出的消息会原样返回给 AI写清楚「哪里错了、该怎么改」比抛通用异常有用得多。资源用mcp.resource(scheme://path)注册只读、无副作用适合放配置、文档、统计这类上下文。3.3 参数校验的边界FastMCP 基于 Pydantic 做校验常见类型都支持int/float/str/bool、List[T]、Dict[K,V]、Optional[T]、Literal[...]、Union、以及 Pydantic 的BaseModel。不支持的包括裸Tuple和自定义非 Pydantic 类。如果你要传复杂结构定义一个BaseModel子类当参数类型最省事from pydantic import BaseModel class ReviewRequest(BaseModel): code: str language: str python max_issues: int 10 mcp.tool async def review_structured(req: ReviewRequest) - str: 结构化入参的代码审查。 return await call_model(f审查 {req.language} 代码最多列 {req.max_issues} 个问题\n{req.code})4. 启动验证与调用测试4.1 用 Inspector 做可视化调试最快的方式是fastmcp dev它会启动你的 Server 并自动打开 MCP Inspectoruv run fastmcp dev server.py浏览器打开http://127.0.0.1:6274在 Tools 标签页能看到summarize和code_review填参数点 Run Tool 就能看到返回。Resources 标签页里config://runtime会显示脱敏后的运行配置。这一步能确认工具注册成功、Schema 生成正确。4.2 用内置 Client 写程序化测试Inspector 适合手动点回归测试用 Client 更靠谱# test_server.py import asyncio from fastmcp import Client async def main(): async with Client(server.py) as client: await client.ping() print(Server 在线) tools await client.list_tools() print(工具列表:, [t.name for t in tools]) result await client.call_tool( summarize, {text: FastMCP 用装饰器简化了 MCP Server 开发。, style: brief}, ) print(摘要结果:, result.content[0].text) cfg await client.read_resource(config://runtime) print(运行配置:, cfg) asyncio.run(main())运行uv run python test_server.py。如果模型通道配置正确你会看到摘要文本返回如果 Key 或 base_url 有问题这里会直接抛 HTTP 错误方便定位。4.3 接入客户端以 Cursor 为例在.cursor/mcp.json里加{ mcpServers: { fastmcp-demo: { command: uv, args: [--directory, /绝对路径/fastmcp-demo, run, python, server.py] } } }路径必须用绝对路径这是最常见的连不上的原因。Claude Desktop 的配置在~/Library/Application Support/Claude/claude_desktop_config.jsonmacOS结构相同。改完重启客户端在工具列表里就能看到你的 Server。5. 本篇常见错排查工具不出现九成是忘了贴mcp.tool或者函数定义在if __name__块里没被执行到。检查装饰器是否紧贴函数。客户端连不上先看路径是不是绝对路径再看 JSON 有没有多余逗号。用uv run python server.py手动跑一遍能正常等待输入说明 Server 本身没问题。参数校验失败报错信息里会写清楚哪个字段、期望什么类型。常见是客户端传了字符串10而注解是int或者Literal传了不在枚举里的值。模型调用 401Key 错了或没带Bearer前缀。检查config.toml里的api_key和base_urlbase_url 结尾不要多加斜杠。模型调用超时把timeout调大或者检查网络。长文本摘要建议在工具里先截断别把几万字直接塞进去。改了代码不生效fastmcp dev有热重载但客户端连接的是独立进程改完要重启客户端。6. 把链路固定下来跑通之后建议把 Key 从config.toml挪到环境变量用os.environ[TAOTOKEN_API_KEY]读取配置文件里只留占位。这样提交代码不会泄露凭证。工具粒度上一个 Server 专注一类能力别把摘要、审查、数据库查询全塞一起客户端选择工具时会更准。docstring 写详细点AI 靠它判断什么时候调用你的工具写得含糊它就不敢用。需要长期跑编码类 Agent、把 MCP 工具接进日常开发流的可以看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。想先在网页里验证模型通道是否通用模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。Key 管理和接入细节分别在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 和 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。