1. FastMCP 状态管理到底解决什么问题从工具函数拿不到请求上下文说起FastMCP 是 MCPModel Context Protocol生态里一个用 Python 写服务器比较顺手的框架它把工具注册、资源读取、会话管理这些事都封装好了。但只要你写过几个真实工具就会撞上一个很具体的麻烦工具函数被调用的时候怎么知道当前是哪个客户端、哪个请求、哪个会话如果每个工具都手动把 request 对象一层层往下传代码会迅速变成一团乱麻。这就是 FastMCP 的 Context 上下文注入要解决的事。简单说你只要在工具函数的参数里声明一个Context类型的参数框架会在调用时自动把当前请求的上下文塞进去你不用自己传。这个机制在context_injection.py里由find_context_parameter和inject_context两个函数配合完成前者负责从函数签名里找出哪个参数该收 Context后者负责把对象真正注入进去。它适合谁适合正在用 FastMCP 搭 MCP 服务器、并且工具数量开始变多、需要统一管理会话状态和模型凭证的开发者。尤其是当你打算让多个工具共用同一套大模型 API 通道时Context 就成了天然的凭证传递载体——你可以在上下文里挂一个统一的 Key 通道工具函数按需取用而不是每个工具各自读环境变量。我试过在一个有十几个工具的服务器里手动传参改一个字段要动七八个文件换成 Context 注入之后新增工具只需要声明参数其余交给框架。这篇文章就围绕这套状态管理机制展开同时给出把 TaoToken 统一 Key 通道接进 Context 的可复制配置以及怎么验证注入真的生效。2. TaoToken 统一 Key 通道前置准备为什么要在 Context 里管多模型凭证在讲配置之前先把「为什么」说清楚。MCP 服务器经常要调用多个模型有的工具做代码补全有的做文本摘要有的做意图识别。如果每个工具各自维护一份 API Key 和 Base URL会出现三个问题一是密钥散落各处轮换时容易漏改二是不同工具可能指向不同通道排查问题时对不上三是没法在请求级别做统一的日志和限流。把凭证收敛到 Context 里本质上是把「凭证获取」变成一个请求级的能力而不是工具级的硬编码。工具函数只管声明ctx: Context需要模型通道时从上下文里取取不到就走默认。这样密钥只在一个地方配置工具代码保持干净。TaoToken 在这里扮演的是统一 API 通道的角色。它提供兼容 OpenAI 风格的接口Base URL 是https://taotoken.net/api你拿一个 Key 就能访问多种模型不用为每个模型单独申请和配置。对 MCP 服务器来说这意味着 Context 里挂一个通道配置所有工具都能复用。前置准备分三步。第一步去官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册并拿到 API Key这个 Key 后面会写进配置。第二步确认你的 FastMCP 版本支持 Context 注入一般近一年的版本都带这个能力可以用pip show fastmcp看版本号。第三步想清楚你的凭证是走环境变量还是走配置文件——生产环境建议环境变量本地调试可以先用.env。这里有个容易忽略的点Context 注入的是请求上下文不是全局单例。也就是说如果你把 Key 直接写死在 Context 的某个属性上它仍然是请求级的不会跨请求泄漏。但如果你在 lifespan 里初始化了一个共享的客户端实例那它才是跨请求复用的。两种方式各有用途凭证建议放 lifespan 共享请求相关的用户信息放 Context 请求级。注意不要把生产库连接、真实密钥硬编码进工具函数。Context 的价值之一就是让这些依赖从代码里剥离出来集中管理。3. 可复制配置把 TaoToken 通道写进 FastMCP 的 lifespan 与 Context这一节是全文最需要你动手的部分。目标是把 TaoToken 的 Base URL、Key、默认 Model ID 三件套配置好并让 Context 能取到它。先给一份可以直接抄的settings片段我用的是 TOML 格式放在项目根目录的config.toml# config.toml [taotoken] base_url https://taotoken.net/api api_key sk-你的TaoToken密钥 default_model gpt-4o-mini timeout 60 [mcp] server_name fastmcp-state-demo log_level INFO对应的 Python 读取和 lifespan 初始化长这样# server.py import os import tomllib from contextlib import asynccontextmanager from openai import AsyncOpenAI from fastmcp import FastMCP, Context with open(config.toml, rb) as f: cfg tomllib.load(f) taotoken_cfg cfg[taotoken] asynccontextmanager async def lifespan(server: FastMCP): # 共享的模型通道客户端跨请求复用 client AsyncOpenAI( base_urltaotoken_cfg[base_url], api_keyos.environ.get(TAOTOKEN_API_KEY, taotoken_cfg[api_key]), timeouttaotoken_cfg[timeout], ) yield {model_client: client, default_model: taotoken_cfg[default_model]} mcp FastMCP(fastmcp-state-demo, lifespanlifespan)注意这里 Key 优先从环境变量TAOTOKEN_API_KEY读读不到才用配置文件里的值。生产环境请务必用环境变量配置文件里的明文只用于本地调试。接下来是工具函数怎么通过 Context 拿到这个客户端。FastMCP 的 Context 提供了request_context.lifespan_context来访问 lifespan 里 yield 出来的字典mcp.tool() async def summarize(text: str, ctx: Context) - str: lifespan_ctx ctx.request_context.lifespan_context client lifespan_ctx[model_client] model lifespan_ctx[default_model] await ctx.info(f使用模型 {model} 处理请求 {ctx.request_id}) resp await client.chat.completions.create( modelmodel, messages[{role: user, content: f请总结{text}}], ) return resp.choices[0].message.content这段代码里有三个关键点。第一ctx: Context参数是自动注入的你不用在调用时传。第二ctx.request_id和ctx.client_id是请求级信息可以用来做日志关联。第三模型客户端来自 lifespan是跨请求共享的避免每个请求都新建连接。如果你用的是 Claude Code 或 Cline 这类客户端来连这个 MCP 服务器配置里同样要写全三件套。以 Claude Code 的 MCP 配置为例Base URL、Key、Model ID 一个都不能少{ mcpServers: { fastmcp-state-demo: { command: python, args: [server.py], env: { TAOTOKEN_API_KEY: sk-你的TaoToken密钥, TAOTOKEN_BASE_URL: https://taotoken.net/api, TAOTOKEN_MODEL: gpt-4o-mini } } } }这样配置之后服务器进程启动时就能从环境变量拿到 Key工具函数通过 Context 取到共享客户端整条链路就通了。4. 验证上下文注入生效日志观察点与成功结果对照配置写完不代表注入就生效了。这一节给你一套可执行的验证动作以及每一步该看什么日志。第一步启动服务器观察 lifespan 是否正常执行。运行python server.py如果配置正确你会看到类似INFO: MCP server fastmcp-state-demo started的输出。如果这里就报错多半是config.toml路径不对或 TOML 语法有问题。第二步调用一个带 Context 的工具观察注入是否发生。在工具函数里加一行await ctx.debug(fcontext injected, request_id{ctx.request_id})然后通过客户端触发调用。成功时日志里会出现 request_id说明 Context 对象确实被注入进来了。如果这行日志没出现说明find_context_parameter没识别到你的参数——最常见的原因是参数类型注解写成了字符串Context而没导入或者用了Optional[Context]但没正确解析泛型。第三步验证凭证通道可用。调用summarize工具观察返回内容。成功时你会拿到模型生成的摘要同时日志里有使用模型 gpt-4o-mini 处理请求 xxx。这一步同时验证了三件事Context 注入生效、lifespan 客户端可用、TaoToken 通道连通。第四步验证请求隔离。连续发两个请求对比日志里的 request_id 是否不同。如果相同说明上下文被错误地跨请求复用了这通常是因为你把请求级数据挂在了全局变量上而不是通过 Context 传递。一个典型的成功日志长这样INFO: 使用模型 gpt-4o-mini 处理请求 req-8f3a2b DEBUG: context injected, request_idreq-8f3a2b INFO: 使用模型 gpt-4o-mini 处理请求 req-9c1d4e DEBUG: context injected, request_idreq-9c1d4e两个 request_id 不同说明隔离正常。如果模型调用返回了内容说明通道正常。到这里上下文注入和统一 Key 通道就算验证通过了。5. 本篇常见错误排查401、local proxy failed、reading choices 与 OAuth这一节按真实报错来对照都是我在接 MCP 服务器时踩过的。401 Unauthorized。这个最直接Key 不对或没传进去。先检查环境变量TAOTOKEN_API_KEY是否在启动进程的环境里再检查代码里读取顺序是不是被配置文件里的空值覆盖了。还有一种情况是 Key 前后带了空格或换行从网页复制时容易带上用strip()处理一下。local proxy failed。这个报错通常出现在客户端侧意思是客户端连不上你配置的 Base URL。检查base_url是不是写成了https://taotoken.net/api注意结尾不要多加斜杠也不要写成别的路径。如果你在容器里跑确认容器能访问外网。reading choices 相关报错比如KeyError: choices或reading choices of undefined。这说明请求发出去了但返回结构不是预期的 OpenAI 格式。常见原因是 Base URL 指错了或者 Model ID 写了一个通道不支持的模型。把default_model换成通道文档里明确支持的模型再试。OAuth 相关报错。如果你用的是 Claude Code 或类似客户端它可能默认走 OAuth 流程去连 MCP 服务器。但我们的服务器是本地进程不需要 OAuth。检查客户端配置里是不是误开了远程连接模式把command和args配成本地启动方式即可。Context 参数没被注入。表现是工具函数里ctx是 None或者调用时报参数缺失。原因通常是类型注解没写对。正确写法是ctx: Context并且从fastmcp导入Context。如果你写的是ctx: Context字符串注解确保from __future__ import annotations没有干扰类型解析。异步调用链里上下文丢失。如果你在工具函数里又起了后台任务后台任务里访问ctx可能拿到的是过期上下文。解决办法是把需要的数据在进入后台任务前从 Context 里取出来作为普通变量传进去而不是在后台任务里直接引用 Context。排障时建议把日志级别调到 DEBUGFastMCP 会打印上下文注入的细节。如果还是定位不到可以去接入文档对照配置项或者直接在模型对话里贴报错问。6. 把统一 Key 通道用起来从单工具到多工具的演进路径配置跑通之后真正的价值在于扩展。你可以在 lifespan 里挂多个客户端比如一个走 TaoToken 统一通道一个走本地模型然后在 Context 里按工具需求选择。也可以把用户身份、权限信息挂进 Context让工具函数在调用模型前先做一次鉴权。对于长期做编码类 Agent 的场景建议把 Coding Plan 用起来它更适合持续性的代码生成和工具调用配合 Context 注入能让每个请求都带上正确的模型通道和会话信息。如果你只是想先验证模型通道是否通可以直接在模型对话里发一条消息试试确认返回正常再往 MCP 服务器里接。演进路径大致是先用单个工具验证 Context 注入和通道连通再把凭证收敛到 lifespan接着把请求级信息挂到 Context最后按工具类型拆分多个通道。每一步都保持可验证不要一次性改太多。最后留一个实用技巧在 Context 里加一个ctx.info调用把当前使用的 Model ID 和 request_id 打出来。这样每次排查问题时你一眼就能看出是哪个请求、走的哪个模型、用的哪个通道。日志是 MCP 服务器最可靠的调试手段比断点还管用。