FastMCP 配 TaoToken：Python 构建 MCP 服务的 config.toml 骨架与连通验证

1. 为什么 FastMCP 服务总在“模型接入”这一步卡住FastMCP 是一个用 Python 构建 MCP 服务的框架它把协议细节、内容类型处理、错误管理都封装好了你只需要用装饰器定义工具函数就能跑起一个支持 Stdio、SSE、内存等多种传输模式的 MCP 服务端。它适合谁适合正在做本地 AI 工具链、想让自己的 Python 函数被大模型调用的开发者尤其是那些不想在协议层反复造轮子的人。但实际开发中很多人把 FastMCP 的服务端骨架搭起来之后会卡在同一个地方工具函数里需要调用大模型能力时API Key 怎么管、base_url 怎么配、环境变量怎么注入、服务启动后怎么确认模型通道真的通了。我见过不少项目把 Key 硬编码在server.py里或者每个工具函数各自读一遍环境变量调试时改一处漏一处。这篇就聚焦这个场景用 FastMCP 搭 MCP 服务时通过统一的 Key/API 通道接入模型能力给出一份可复制的config.toml配置骨架、环境变量写法以及启动后验证 MCP 服务连通性的具体命令和预期返回。目标很明确——让你在本地开发环境里从零跑通第一个带模型调用的 FastMCP 服务并且知道每一步“通了”长什么样。2. TaoToken 前置统一 Key 与 API 通道的定位在 FastMCP 服务里调用模型最直接的方式是用 OpenAI 兼容的 SDK把base_url指向一个统一的 API 通道。TaoToken 在这里的角色就是提供这个通道你拿到一个 Key配好 base_url就能在 FastMCP 的工具函数里通过标准 OpenAI 客户端发起请求不需要为每个模型单独维护一套鉴权逻辑。具体来说你需要先准备好两样东西一个可用的 API Key在控制台里创建https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite确认你要调用的模型名称可以在模型对话页面先试一下https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewriteAPI 的基础地址是https://taotoken.net/api这个地址在后面的config.toml和 Python 代码里都会用到。注意它和官网首页不是同一个路径配置时别写错。提示Key 的管理和创建都在控制台完成建议为本地开发单独建一个 Key方便后续轮换和排查。如果你后续要做长期编码或 Agent 类项目可以了解一下 Coding Plan 的额度方式https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite3. 可复制配置config.toml 骨架与环境变量FastMCP 本身不强制你用config.toml但把模型接入相关的参数集中到一个配置文件里能让服务端代码保持干净。下面这份骨架可以直接复制放到项目根目录。# config.toml [llm] base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY model gpt-4o-mini timeout 30 max_retries 2 [mcp] name fastmcp-demo transport sse host 127.0.0.1 port 8001这里有几个设计点值得说明。api_key_env存的是环境变量的名字而不是 Key 本身这样配置文件可以进版本库而不会泄露密钥。base_url固定指向 TaoToken 的 API 地址。model先填一个你确认可用的模型名后面验证阶段会实际调用它。环境变量的写法Linux/macOS 下export TAOTOKEN_API_KEY你的KeyWindows PowerShell$env:TAOTOKEN_API_KEY你的Key如果你用.env文件配合python-dotenv在项目根目录建一个.envTAOTOKEN_API_KEY你的Key然后在服务端入口文件顶部加载from dotenv import load_dotenv load_dotenv()接下来是读取配置的辅助模块我把它放在settings.py里import os import tomllib from pathlib import Path def load_config(path: str config.toml) - dict: with open(Path(path), rb) as f: config tomllib.load(f) api_key os.getenv(config[llm][api_key_env]) if not api_key: raise RuntimeError( f环境变量 {config[llm][api_key_env]} 未设置 ) config[llm][api_key] api_key return config这样服务端代码只需要config load_config()就能同时拿到 base_url、model 和解析后的 api_key不用在每个工具函数里重复读环境变量。4. 服务端与客户端从工具定义到连通验证先写服务端server.py定义一个会调用模型的工具函数import json from fastmcp import FastMCP from openai import OpenAI from settings import load_config config load_config() mcp FastMCP(nameconfig[mcp][name]) client OpenAI( api_keyconfig[llm][api_key], base_urlconfig[llm][base_url], timeoutconfig[llm][timeout], max_retriesconfig[llm][max_retries], ) mcp.tool() def ask_model(question: str) - str: 向模型提问并返回文本回答。 参数: question: 用户的问题 返回: 模型生成的回答文本 resp client.chat.completions.create( modelconfig[llm][model], messages[{role: user, content: question}], streamFalse, ) return resp.choices[0].message.content mcp.tool() def add(a: float, b: float) - float: 加法运算用于验证工具注册是否正常。 return a b if __name__ __main__: mcp.run( transportconfig[mcp][transport], hostconfig[mcp][host], portconfig[mcp][port], )启动服务python server.py预期输出类似INFO: Uvicorn running on http://127.0.0.1:8001 (Press CTRLC to quit) INFO: Application startup complete.看到Application startup complete说明 MCP 服务端已经起来了。接下来写客户端client.py做连通验证import asyncio from fastmcp import Client async def main(): async with Client(http://127.0.0.1:8001/sse) as mcp_client: tools await mcp_client.list_tools() print(已注册工具:, [t.name for t in tools]) result await mcp_client.call_tool(add, {a: 5, b: 3}) print(add 返回:, result[0].text) answer await mcp_client.call_tool( ask_model, {question: 用一句话说明 MCP 是什么} ) print(ask_model 返回:, answer[0].text) if __name__ __main__: asyncio.run(main())运行python client.py预期返回已注册工具: [ask_model, add] add 返回: 8.0 ask_model 返回: MCP 是一种让模型与外部工具、数据源标准化交互的协议。到这里add返回 8.0 说明 MCP 工具调用链路通了ask_model返回了模型生成的文本说明通过 TaoToken 的 API 通道调用模型也通了。两个都通才算真正完成了“FastMCP 配 TaoToken”的连通验证。5. 本篇常见错排查5.1 启动时报环境变量未设置报错信息类似RuntimeError: 环境变量 TAOTOKEN_API_KEY 未设置。原因通常是当前终端会话没有 export或者.env文件没被加载。检查方式echo $TAOTOKEN_API_KEY如果输出为空重新 export 或确认load_dotenv()在load_config()之前执行。5.2 客户端连接被拒绝报错ConnectionRefusedError或httpx.ConnectError。先确认服务端是否还在运行再确认端口一致。服务端config.toml里写的是 8001客户端连接串也必须是http://127.0.0.1:8001/sse。如果服务端启动时端口被占用换一个端口后记得同步改客户端。5.3 ask_model 返回鉴权错误如果ask_model调用抛出 401 或 403说明 Key 无效或 base_url 写错。重点检查config.toml里的base_url是否为https://taotoken.net/api以及环境变量里的 Key 是否和控制台里创建的一致。可以在模型对话页面先用同一个 Key 手动发一条消息确认 Key 本身可用。5.4 工具列表为空list_tools()返回空列表通常是mcp.tool()装饰器没生效或者服务端启动时导入的模块不是你以为的那个。检查server.py里工具函数是否在mcp.run()之前定义以及启动命令的工作目录是否正确。5.5 模型名不存在报错里出现model not found或类似提示说明config.toml里的model字段填了一个当前通道不支持的名称。换一个你确认可用的模型名或者先在模型对话页面确认可用模型列表。6. 接入文档与后续操作入口配置骨架和连通验证跑通之后下一步通常是把这个 FastMCP 服务接入到实际的客户端或 Agent 流程里。API 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如果你用的是 Claude Code 这类编码工具想把它和 FastMCP 服务串起来可以看 ClaudeCodeAnthropic 的配置说明https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite我自己的习惯是每次改完config.toml或环境变量后先跑一遍client.py里的add调用确认 MCP 链路没断再跑ask_model确认模型通道没断。两步都过再继续写新的工具函数。这样排障时能快速定位是 MCP 层的问题还是模型接入层的问题不用在一堆日志里翻。