1. 从一次本地联调翻车说起FastMCP 服务到底难在哪FastMCP 是一个用 Python 快速构建 MCP 服务的框架你可以把它理解成「MCP 版的 FastAPI」——用装饰器把普通函数注册成工具、资源和提示模板几行代码就能跑起一个符合 MCP 规范的服务端。它适合谁适合想把内部脚本、数据库查询、文件读取能力暴露给 AI 客户端的后端开发者也适合正在做 Agent 工具链、需要统一管理模型调用通道的团队。但真正动手时卡人的往往不是mcp.tool()怎么写而是三件事第一服务跑起来了客户端却连不上SSE 端点握手失败第二工具函数里要调模型Key 散落在环境变量、配置文件、代码里换一个模型就要改一遍第三本地调试和线上部署的配置不一致config.toml和settings.json各写一套改到怀疑人生。这篇就按「项目初始化 → 统一 Key 通道 → 可复制配置 → 启动验证 → 排障」的顺序走一遍重点演示怎么用 TaoToken 把模型调用的 Key 和 API 通道统一管起来让 FastMCP 服务里的工具函数不再关心「这次调的是哪个模型、走哪条通道」。全程可复制跟着敲就能跑通。2. 前置准备TaoToken 统一 Key 与 API 通道在写 MCP 服务之前先把模型调用的「出口」定下来。MCP 服务里的工具函数经常需要调用大模型比如代码审查工具、摘要工具、翻译工具。如果每个工具各自读环境变量、各自拼 base_url后期维护会很痛苦。TaoToken 在这里扮演的角色是统一的 API 通道你只需要在控制台创建一个 Key拿到一个统一的 base_url之后所有模型调用都走这个入口。FastMCP 服务里不管有多少个工具要调模型都复用同一份配置。操作路径很直接进控制台创建 API Key然后确认接入文档里的 base_url 格式。Key 建议放在.env里不要硬编码进mcp_server.py。控制台创建 Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteAPI Key 管理页https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite接入文档确认 base_url 与请求格式https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite注意API 入口是https://taotoken.net/api不要在后面拼多余的路径具体端点以接入文档为准。Key 只存在服务端环境变量里别写进会提交到 Git 的文件。如果你后面要做长期编码类 Agent或者需要频繁切换模型做对比可以顺带了解 Coding Plan它更适合持续性的编码场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite3. 可复制配置config.toml 与 settings.json 骨架先把项目结构定下来避免后面文件乱放fastmcp-demo/ ├── mcp_server.py ├── config.toml ├── settings.json ├── .env └── data/ └── test.txt3.1 config.toml服务与模型通道配置config.toml放服务本身的参数和模型通道参数。模型部分统一指向 TaoToken 的 API 入口Key 从环境变量注入不写死在文件里。[server] title FastMCP 统一通道服务 description 基于 FastMCP 构建模型调用走统一 API 通道 version 1.0.0 host 127.0.0.1 port 8000 reload true [model] # 统一 API 入口具体端点以接入文档为准 base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY default_model claude-sonnet timeout 60 max_retries 2 [logging] level INFO file mcp_server.log3.2 settings.json客户端侧连接配置settings.json给 MCP 客户端用声明要连哪个服务、走什么传输方式。FastMCP 默认通过 SSE 暴露路径是/sse。{ mcpServers: { fastmcp-demo: { url: http://127.0.0.1:8000/sse, transport: sse, timeout: 30000, env: { TAOTOKEN_API_KEY: ${TAOTOKEN_API_KEY} } } } }3.3 .env只放 KeyTAOTOKEN_API_KEY你的Key.env必须进.gitignore。这一步别偷懒Key 泄露的代价比多写一行忽略规则大得多。3.4 CC Switch 切换步骤如果你本地同时维护多个 MCP 服务或模型通道用 CC Switch 做配置切换比手动改文件稳。步骤是先把上面的settings.json存成一个 profile命名比如fastmcp-demo再为其他通道各存一个 profile切换时选中目标 profile 生效客户端重连即可。切换后建议重启一次 MCP 客户端避免旧连接缓存了上一个服务的 SSE 会话。4. 服务代码把统一 Key 接进 FastMCP 工具下面这份mcp_server.py把配置读取、模型调用、工具注册串起来。模型调用部分统一从config.toml读 base_url从环境变量读 Key工具函数本身不关心通道细节。import os import tomllib from pathlib import Path import httpx from dotenv import load_dotenv from fastmcp import FastMCP load_dotenv() # 读取配置 cfg tomllib.loads(Path(config.toml).read_text(encodingutf-8)) BASE_URL cfg[model][base_url] API_KEY os.environ.get(cfg[model][api_key_env], ) DEFAULT_MODEL cfg[model][default_model] mcp FastMCP( titlecfg[server][title], descriptioncfg[server][description], versioncfg[server][version], ) def call_model(prompt: str, model: str DEFAULT_MODEL) - str: 统一模型调用入口所有工具复用这一条通道 if not API_KEY: raise RuntimeError(未读取到 API Key请检查 .env) headers { Authorization: fBearer {API_KEY}, Content-Type: application/json, } payload { model: model, messages: [{role: user, content: prompt}], } with httpx.Client(timeoutcfg[model][timeout]) as client: resp client.post(f{BASE_URL}/v1/chat/completions, headersheaders, jsonpayload) resp.raise_for_status() data resp.json() return data[choices][0][message][content] mcp.tool() def summarize(text: str) - str: 对输入文本做摘要模型调用走统一通道 return call_model(f请用三句话总结以下内容\n{text}) mcp.tool() def review_code(code: str, language: str python) - str: 代码审查工具复用同一个模型通道 prompt f你是{language}代码审查专家指出问题并给优化建议\n{code} return call_model(prompt) mcp.resource(data://{filename}) def read_data(filename: str) - str: 暴露 data 目录下的文件给 AI 读取 path Path(data) / filename if not path.exists(): raise FileNotFoundError(f{filename} 不存在) return path.read_text(encodingutf-8) if __name__ __main__: mcp.run(hostcfg[server][host], portcfg[server][port], reloadcfg[server][reload])这里的关键设计是call_model只写一次。以后要换模型改config.toml里的default_model就行要换通道改base_url要换 Key改.env。工具函数完全不用动。5. 启动与请求验证一次完整闭环先装依赖pip install fastmcp httpx python-dotenv启动服务python mcp_server.py控制台出现MCP server running on http://127.0.0.1:8000就说明起来了。接着验证 SSE 端点是否可达curl -N http://127.0.0.1:8000/sse-N关闭缓冲能持续看到事件流。如果只想确认握手看到event: endpoint之类的输出即可按 CtrlC 退出。再用客户端调一次工具验证模型通道是否真的通了pip install mcp-client mcp-client call --server http://127.0.0.1:8000 \ --tool summarize \ {text: FastMCP 让 MCP 服务开发像写 FastAPI 一样简单。}成功时返回的是模型生成的摘要文本。如果这一步返回了内容说明「FastMCP 服务 → 统一 Key → 模型通道」整条链路是通的。你也可以在模型对话页手动发一条同样的 prompt 做对照确认通道行为一致https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite6. 本篇常见错排查报错一ModuleNotFoundError: No module named tomllibtomllib是 Python 3.11 才进标准库的。低于这个版本要么升级 Python要么pip install tomli然后把导入改成import tomli as tomllib。报错二RuntimeError: 未读取到 API Key说明.env没被读到。检查三点.env是否和mcp_server.py同目录load_dotenv()是否在读取环境变量之前调用变量名是否和config.toml里的api_key_env完全一致大小写敏感。报错三httpx.ConnectError或连接超时先确认base_url没写错API 入口是https://taotoken.net/api不要自己拼多余路径。再确认本机网络能正常访问该地址。如果服务本身能启动但工具调用超时把config.toml里的timeout调大试试。报错四客户端连不上/sse常见原因是端口被占用或 host 写成了0.0.0.0但客户端用127.0.0.1连。本地开发统一用127.0.0.1。另外确认settings.json里的 url 结尾是/sse少写这段路径会 404。报错五改了配置但行为没变reloadTrue只监听 Python 文件变化不会监听config.toml。改完配置文件要手动重启服务。CC Switch 切换 profile 后也要重启客户端否则旧 SSE 会话还在。报错六工具返回 401Key 失效或复制时带了空格。重新在控制台生成一个 Key粘贴时注意首尾不要有空白字符。7. 把通道固定下来再谈扩展跑通上面这套之后你会发现 FastMCP 的扩展成本很低加一个工具就是加一个mcp.tool()函数模型调用继续复用call_model。真正需要提前定死的是通道和配置结构——config.toml管服务与模型参数settings.json管客户端连接.env只管 Key。这三者分离之后本地调试、切换通道、部署上线都不会互相打架。下一步可以做的把call_model抽成独立模块供多个 MCP 服务复用给工具加统一的异常处理和日志用 systemd 把服务做成开机自启。但在此之前先用一次完整的summarize调用确认链路通了比什么都重要。