04.7.18.3 传输、鉴权、生命周期与部署测试
所属:全栈开发面试题库 / 04 后端语言与运行时 / 04.7 Python / 04.7.18 FastMCP 服务端框架
覆盖范围
- stdio 输出纪律:stdout 纯协议流、stderr 日志、print 污染与进程模型
- SSE 与 Streamable HTTP 端点形态、会话标识、有状态/无状态模式与事件存储
- 会话隔离、挂载前缀、root_path、CORS 与 TLS 终止
- Bearer token、OAuth 2.1 资源服务器、token 校验器、scope 控制与发现端点
- 容器镜像、启动参数、多副本粘性与会话扩展限制
- 结构化日志、指标、trace id 贯穿与工具调用耗时
- 内存内 client 测试、call_tool 断言、错误路径与契约测试、ASGI 链路测试
- 入参校验、命令注入、路径穿越、资源 URI 校验、限流超时与脱敏
- 同进程共存、健康检查、优雅停机与常见故障排查
04.7.18.3-001 stdio 传输下 stdout 为什么是纯协议流?
一句话结论
stdio 传输把 stdout 作为协议消息的唯一通道:每行一条 JSON-RPC 消息,客户端逐行解析。stdout 上任何非协议文本都会破坏帧格式,导致客户端 JSON 解析失败或消息错位。因此服务端所有调试、日志、打印都不能写入 stdout,协议响应与通知之外不得有其他输出。
概念解释
- 通道分工:stdin 收请求,stdout 发响应与通知,stderr 走日志。
- 帧格式:每条 JSON-RPC 消息一行,换行分隔,UTF-8 编码。
- 污染后果:解析报错、请求响应错位、会话建立失败。
原理流程
- 客户端拉起服务端子进程,接管三条标准流。
- 服务端从 stdin 读消息,处理后只把协议报文写入 stdout。
- 客户端按行解析 stdout;混入的普通文本成为非法 JSON 帧。
代码或图示
stdin <- client JSON-RPC lines
stdout -> client JSON-RPC lines (only protocol messages)
stderr -> log lines (not parsed as protocol)
常见误区
- 用
print()调试服务端代码:默认写到 stdout,直接污染协议流。 - 框架日志配置默认输出到 stdout:需重定向到 stderr 或本地日志文件。
追问
- stdout 能输出空行吗?答:空白帧可能被解析为空消息,应避免在协议报文外产生多余行。
- 协议消息之间需要分隔符吗?答:stdio 按换行分帧,一行一条消息。
- 如何检查 stdout 是否干净?答:本地用 stdio 客户端连接观察报文,或检查日志配置输出去向。
04.7.18.3-002 为什么日志、调试输出必须走 stderr 而不是 stdout?
一句话结论
stderr 不承载协议消息,客户端通常把它作为日志流读取展示,因此日志、警告、调试信息应写入 stderr;写入 stdout 会被当成协议帧解析。stdio 服务端应把应用日志、框架日志都配置到 stderr 或文件,避免任何标准输出混入协议通道。
概念解释
- stderr 独立通道:不参与 JSON-RPC 分帧,日志内容可自由换行。
- 客户端用途:展示服务端运行日志,辅助本地接入排查。
- 本地落盘:生产排障仍应写结构化日志文件,stderr 只作对接输出。
原理流程
- 配置日志处理器输出到 stderr(或本地文件)。
- 运行期日志写入 stderr,不触碰 stdout。
- 客户端从 stderr 读取日志展示,stdout 保持纯协议。
代码或图示
import logging
import sys
logging.basicConfig(stream=sys.stderr, level=logging.INFO)
常见误区
- 混用标准库 print:
print()默认 stdout,调试应写 stderr 或日志框架。 - 第三方库默认往 stdout 打日志:需在初始化时调整日志处理器去向。
追问
- stderr 日志会阻塞协议响应吗?答:stderr 写入是独立通道,正常日志量不影响 stdout 协议流;海量日志需评估 IO。
- 生产环境 stderr 有用吗?答:容器环境 stderr 会被采集为日志流,可同时结构化落盘。
- 错误信息也走 stderr 吗?答:日志级别都走 stderr;协议执行错误仍通过 stdout 的 error 响应返回。
04.7.18.3-003 误把 print 打到 stdout 会造成什么客户端故障?
一句话结论
stdout 混入普通文本后,客户端按行解析 JSON 会遇到非法帧:轻则某条消息解析失败、对应请求无响应,重则后续帧全部错位,握手或工具调用反复失败。故障表象像“服务端偶发不响应”,根因是协议流被日志污染,必须把打印全部改到 stderr。
概念解释
- 单帧污染:一行普通文本解析失败,该请求丢失响应。
- 错位污染:多行文本破坏按行分帧,后续消息边界错乱。
- 典型来源:调试 print、第三方库启动横幅、进度条、依赖库日志。
原理流程
- 服务端向 stdout 写入非协议文本。
- 客户端逐行读取,遇到非法 JSON 帧报错。
- 帧边界错乱后请求响应无法关联,表现为超时、缺响应或会话失败。
代码或图示
# 错误:污染 stdout
print("connected to db")
# 正确:走 stderr
print("connected to db", file=sys.stderr)
常见误区
- 只删除报错行不检查其他库:依赖库启动横幅、版本提示同样可能写 stdout。
- 认为控制台能看到输出就正常:本地终端混在一起看不出通道区别,需按标准流区分。
追问
- 如何定位哪段代码写了 stdout?答:检查所有 print 与日志配置,必要时重定向 stdout 捕获非协议输出。
- 污染后客户端有什么报错特征?答:JSON 解析异常、请求挂起无响应、会话握手失败。
- 修复后需要验证什么?答:stdio 客户端完整走完握手与一次工具调用,stdout 无额外文本。
04.7.18.3-004 stdio 下服务端进程由谁启动、生命周期如何管理?
一句话结论
stdio 服务端进程由客户端按配置拉起,客户端负责进程启动、标准流接管与退出回收;服务端不是常驻监听端口的守护进程。进程随会话开始而启动,随连接关闭或客户端退出而终止,进程内状态不跨进程保留。
概念解释
- 启动方:客户端按 MCP 配置(命令、参数、环境变量)spawn 子进程。
- 生命周期:进程退出即会话结束,stdin 关闭也触发服务端退出。
- 隔离性:每个子进程独立环境与状态,凭据随进程环境隔离。
原理流程
- 客户端读取服务端启动配置,拉起子进程。
- 标准流建立,服务端进入消息读取循环。
- 连接关闭/客户端退出时,子进程被终止回收,内存状态释放。
代码或图示
client process
└─ spawn: server subprocess (command + args + env)
stdin/stdout/stderr 由 client 接管
常见误区
- 把 stdio 服务端当后台服务长期运行:它按需启动,不自行监听端口。
- 在进程内保留跨会话状态:进程退出即销毁,重启后不恢复。
追问
- 子进程崩溃客户端如何感知?答:监听进程退出码与流关闭,重建会话。
- stdio 服务端能常驻吗?答:可由外部守护进程托管,但默认模型是客户端按需拉起。
- 进程环境变量由谁注入?答:客户端按启动配置传入,敏感配置不写死在脚本里。
04.7.18.3-005 stdio 消息的换行分隔与编码约定是什么?
一句话结论
stdio 消息以文本帧在标准流上传输:每条 JSON-RPC 消息一行,换行分隔,编码为 UTF-8。服务端不应在报文内插入额外换行或非 UTF-8 字节,避免破坏分帧。
概念解释
- 编码:JSON 文本按 UTF-8 编码,与项目文档编码约定一致。
- 分帧:换行作为消息边界,一行一条消息。
- 稳健性:协议实现负责读写帧,业务代码不直接操作标准流分帧。
原理流程
- 消息序列化为 JSON 字符串。
- 按传输分帧规则写入 stdout(换行分隔)。
- 客户端按帧边界读取并解析 JSON。
代码或图示
{"jsonrpc":"2.0","id":1,"method":"ping"}\n
{"jsonrpc":"2.0","id":1,"result":{}}\n
常见误区
- 在 JSON 字符串值里嵌入控制换行破坏帧边界:字符串内转义由 JSON 序列化器处理。
- 假设分帧规则可随意改:跨端互通依赖双方遵循同一传输实现约定。
追问
- 消息有大小上限吗?答:通道缓冲区与序列化层限制报文大小,超大响应需分页或改资源引用。
- 非 ASCII 字符如何编码?答:按 UTF-8 序列化,不在标准流上做转义层处理。
- 如何核对分帧细节?答:对照 MCP 规范 stdio 传输章节与本地 SDK 读写实现。
04.7.18.3-006 stdio 服务端如何避免阻塞 stdin 读取循环?
一句话结论
服务端主循环应持续从 stdin 读取消息并派发处理,避免在循环内做长时间同步阻塞;异步框架由事件循环调度请求,同步阻塞调用会卡住读取与响应。长任务应异步化或放到执行器,并在检查点让出控制权,保持通道可响应。
概念解释
- 读取循环:等待 stdin 数据 → 解码消息 → 派发执行 → 写回响应。
- 阻塞风险:同步长 IO、CPU 密集计算占住事件循环,后续请求无法读取处理。
- 调度:异步工具直接 await;同步阻塞操作走执行器或异步驱动。
原理流程
- 事件循环等待标准流可读事件。
- 消息到达后派发对应工具/资源/提示执行。
- 处理中让出控制权,循环继续读取后续消息。
代码或图示
# 异步服务端主循环由框架驱动;工具内避免长时间同步阻塞
@mcp.tool
async def fetch(url: str) -> dict:
async with httpx.AsyncClient() as client:
resp = await client.get(url)
return {"status": resp.status_code}
常见误区
- 在工具里调用阻塞型同步库且不放手:事件循环被占住,stdin 后续消息积压。
- 主循环里做重计算预热:应放到启动生命周期阶段,不占用服务期读取循环。
追问
- 阻塞库怎么接入?答:用异步驱动替代,或把阻塞操作放到线程执行器并设超时。
- 读取循环卡死有什么现象?答:ping 无响应、后续调用挂起、客户端判定通道失效。
- stdio 下能并发处理多个请求吗?答:FastMCP 2.x 事件循环可协程并发派发;同步函数经线程池卸载,阻塞调用会占住循环导致串行化。
04.7.18.3-007 stderr 日志级别配置在 stdio 下的去向是什么?
一句话结论
stderr 上的日志按级别输出到客户端读取的错误流;级别由日志配置控制,低级别调试信息可过滤。stdio 场景没有独立日志服务进程,stderr 是运行期可见日志的主要通道;生产容器部署中 stderr 会被日志采集系统收集。
概念解释
- 级别:debug/info/warning/error,配置阈值以下不输出。
- 去向:本地客户端展示;容器环境随标准错误流被采集。
- 与协议日志通知区别:Context 日志通知走 stdout 协议消息,本地日志走 stderr。
原理流程
- 初始化日志配置,设置级别与 stderr 处理器。
- 运行期按级别写入 stderr。
- 客户端/采集系统读取 stderr 展示或归集。
代码或图示
import logging, sys
logging.basicConfig(stream=sys.stderr, level=logging.INFO)
常见误区
- 协议日志通知与本地日志混用:前者是 stdout 通知消息,后者是 stderr 日志流。
- 日志级别生产环境开 debug:stderr 输出量大,影响 IO 与对接排查。
追问
- 日志能写本地文件吗?答:可以,按需增加文件处理器;stdio 场景 stderr 是默认可见通道。
- 级别能被客户端调整吗?答:协议
logging/setLevel调整的是协议日志通知,不等同本地日志配置。 - stderr 日志需要脱敏吗?答:需要,不记录密钥、令牌与完整敏感参数。
04.7.18.3-008 stdio 场景下多客户端与并发会话有什么限制?
一句话结论
stdio 模型下每个客户端通常拉起独立子进程,进程内会话与状态隔离;单进程内多会话并发支持取决于框架实现。stdio 不适合集中式多客户端共享服务,需要多会话并发、网络访问与鉴权时应选择 HTTP 类传输。
概念解释
- 进程隔离:独立进程天然隔离,但资源按进程复制,并发规模受进程数约束。
- 单进程多会话:stdio 通道模型以单连接单会话为主,多会话并发应改用 HTTP 传输。
- 扩展瓶颈:进程创建开销、内存占用、下游连接池按进程拆分。
原理流程
- 每个客户端启动各自服务端子进程。
- 进程内处理本会话消息,状态不跨进程共享。
- 客户端数量增长时进程数同步增长,资源消耗线性放大。
代码或图示
client A -> process A
client B -> process B
client C -> process C
常见误区
- 用 stdio 承载网络多租户服务:进程模型无法集中治理,鉴权与限流也缺乏网络层入口。
- 在模块级单例里期待跨客户端共享状态:不同进程互不可见。
追问
- stdio 服务端能被多个进程同时调用吗?答:每个调用方拉起独立进程,不共享同一进程实例。
- 什么场景转 HTTP 传输?答:多客户端集中接入、统一鉴权、负载均衡与可观测性要求时。
- 进程内并发请求怎么判断?答:看事件循环派发模型与同步函数的线程池卸载方式。
04.7.18.3-009 Streamable HTTP 默认端点路径 /mcp 是怎么来的?
一句话结论
Streamable HTTP 传输把协议消息挂在单一 HTTP 端点上,默认路径为 /mcp,可在创建 ASGI 应用或运行配置时修改。客户端向该路径 POST 请求,握手后通过会话标识头关联后续请求;挂载到子路径时,最终 URL 由挂载前缀加端点路径拼成。
概念解释
- 单端点:请求与响应都走同一 URL,不再有独立服务端推送连接。
- 路径配置:
http_app(path="/mcp")或运行参数决定端点位置。 - 拼接规则:父应用挂载前缀 + 子应用内路径,测试与代理配置按完整 URL 对齐。
原理流程
- 生成 MCP ASGI 应用时配置端点路径。
- 挂载到父应用前缀下,形成完整访问 URL。
- 客户端 POST 到完整 URL 发起 initialize 与后续调用。
代码或图示
mcp_app = mcp.http_app(path="/mcp")
api.mount("/analytics", mcp_app)
# 最终端点: /analytics/mcp
常见误区
- 路径只记
/mcp忽略挂载前缀:经父应用挂载后实际 URL 带前缀,客户端连接地址算错。 - 把 SSE 旧端点
/sse套到 Streamable HTTP:两套传输路径模型不同。
追问
- 端点路径能改到根路径吗?答:可以,子应用 path 设为
/,挂载前缀即完整路径。 - 路径区分大小写吗?答:Starlette/FastAPI 路由默认大小写敏感,路径匹配按 ASGI 路由规则。
- 多实例挂载如何区分路径?答:每个子应用独立路径前缀,避免路由冲突。
04.7.18.3-010 SSE legacy 传输的 /sse 与消息端点结构是什么?
一句话结论
旧 SSE 传输是双端点结构:GET 到 /sse 建立服务端到客户端的事件流,POST 到消息端点把请求发回服务端,两端点通过会话标识关联。该传输已被 Streamable HTTP 取代,保留仅为兼容旧客户端,新项目不应选用。
概念解释
- 服务端推送:SSE 长连接持续推送事件。
- 客户端请求:独立 POST 端点携带会话标识回写请求。
- 脆弱点:两条 HTTP 连接拼合双向通道,代理与空闲超时更易中断。
原理流程
- 客户端 GET
/sse建立长连接,获得会话通道标识。 - 客户端 POST 请求到消息端点并带回标识。
- 服务端响应通过已建立的 SSE 流推回客户端。
代码或图示
client --GET /sse----------> server (SSE long link)
client --POST /messages----> server (request post)
server --SSE events--------> client
常见误区
- 把 SSE 传输与 Streamable HTTP 混为一谈:前者双端点旧方案,后者单端点新方案。
- 新部署沿用 SSE:代理兼容性、可恢复性与双向流式体验均不如 Streamable HTTP。
追问
- SSE 默认消息端点路径是什么?答:legacy SSE 传输 GET
/sse建流,POST/messages回传请求(SDK 旧版默认)。 - SSE 支持多客户端吗?答:支持,每连接独立会话,但水平扩展受会话内存限制。
- 何时必须保留 SSE?答:接入尚未升级 Streamable HTTP 的旧客户端时。
04.7.18.3-011 Streamable HTTP 响应的 JSON 与 SSE 两种形态如何选择?
一句话结论
短结果可用一次性 JSON 响应返回;需要持续推送进度、后续消息或长任务流式输出时,响应采用 SSE 事件流,由框架按是否需要流式推送选择。服务端按任务时长与推送需求设计,代理链路需同时兼容两种响应。
概念解释
- JSON 响应:单次请求单次返回,适合快速工具调用。
- SSE 流:响应保持打开,事件逐条推送,适合进度上报与流式结果。
- 兼容要求:反向代理不能缓冲 SSE 流,否则事件被攒批延迟推送。
原理流程
- 工具执行前判断结果形态:短结果或长任务流式。
- 框架按模式返回 JSON 响应或 SSE 事件流。
- 客户端按响应格式解析:一次性 JSON 或事件流逐条读取。
代码或图示
short result -> HTTP JSON response
long task -> HTTP SSE stream: progress ... result
常见误区
- 代理按普通 JSON 接口缓冲 SSE:事件积压到响应结束才发出,进度失去意义。
- 所有调用都开 SSE 流:短结果增加连接与流管理开销,应按场景选择。
追问
- 纯 JSON 响应能关闭 SSE 流吗?答:短结果框架直接返回 JSON;需要流式事件时才升级 SSE 流,代理按两种形态兼容。
- SSE 流里能混 JSON 事件吗?答:事件按 SSE 帧格式承载 JSON-RPC 消息。
- 客户端如何区分响应形态?答:按响应 Content-Type 与是否为事件流判断。
04.7.18.3-012 Mcp-Session-Id 会话标识头如何生成与携带?
一句话结论
握手成功后服务端在 initialize 响应中下发会话标识,客户端后续请求通过 Mcp-Session-Id 头携带;服务端按标识查找会话上下文。未携带或标识失效时请求无法路由到原会话。
概念解释
- 生成:首次握手由服务端创建会话并返回标识。
- 携带:后续每个请求在请求头带回,不用写进工具 arguments。
- 失效:会话空闲超时或关闭后标识失效,需重新握手。
原理流程
- 客户端首次 POST initialize,无会话标识。
- 服务端创建会话,响应返回标识。
- 后续请求头携带标识,服务端匹配会话处理。
代码或图示
POST /mcp
Mcp-Session-Id: <握手响应返回值>
常见误区
- 把会话标识放进工具参数:它是传输层关联信息,不属于业务入参。
- 多副本下假定标识全局有效:状态在某实例内存中,其他实例查不到。
追问
- 会话标识会过期吗?答:按空闲超时与生命周期回收,过期后重新握手。
- 标识头在无状态模式还需要吗?答:无状态模式不保留会话状态,请求自包含。
- 标识泄露有风险吗?答:会话标识可被用于复用会话,网络层应配合 TLS 与访问控制。
04.7.18.3-013 无状态 HTTP 模式 stateless_http 与 json_response 有什么区别?
一句话结论
stateless_http 控制服务端是否保存会话上下文:无状态模式每个请求自包含,不依赖服务端内存会话,可在构造实例或 run 时传 stateless_http=True,也可用环境变量 FASTMCP_STATELESS_HTTP=true。响应是否流式由框架按推送需求选择,与会话模式是两个不同维度。
概念解释
- 无状态:便于多副本水平扩展,会话内推送与持久订阅受限。
- JSON 响应:弱化 SSE 流依赖,配合无状态模式简化链路。
- 有状态:保留会话上下文,支持进度推送、订阅与跨请求关联。
原理流程
- 部署侧决定会话模型:需要会话记忆选有状态,追求扩展选无状态。
- 按模式配置响应格式开关。
- 请求处理按所选模式路由与返回。
代码或图示
import os
os.environ["FASTMCP_STATELESS_HTTP"] = "true"
mcp = FastMCP("stateless", stateless_http=True)
常见误区
- 无状态模式仍依赖服务端记住上次参数:需要的数据必须每次请求带上。
- 把响应格式开关当成会话开关:两者独立,需分别配置。
追问
- 无状态模式支持资源订阅吗?答:订阅与推送依赖会话上下文,无状态模式下受限,客户端通常降级为主动读取。
- 无状态模式下进度怎么上报?答:流式推送受限,长任务结果需在响应或重连后获取。
- 混合模式存在吗?答:按框架实现判断,有状态/无状态通常二选一配置。
04.7.18.3-014 EventStore 事件存储与断线重连续传如何工作?
一句话结论
配置事件存储后,服务端把会话事件(进度、结果等)按标识保存;连接断开重连时,客户端带 Last-Event-ID 头补收缺失事件,避免长任务进度丢失。FastMCP 2.x 默认使用内存 EventStore;持久化后端需按安装版本核实(待确认:验证点:当前版本 EventStore 支持的外部存储后端与配置参数)。
概念解释
- 事件标识:每个事件带序号或标识,重连后据此补收。
- 存储生命周期:与会话或任务绑定,过期后清理。
- 适用场景:代理中断、空闲超时、客户端短暂掉线后的任务恢复。
原理流程
- 服务端配置事件存储,任务过程事件逐条写入。
- 连接断开后客户端重连,带回会话标识与断点位置。
- 存储补发缺失事件,客户端续收进度与最终结果。
代码或图示
from fastmcp.server.event_store import EventStore
event_store = EventStore(max_events_per_stream=1000, ttl=3600)
app = mcp.http_app(event_store=event_store, retry_interval=2000)
常见误区
- 以为重连天然能恢复任务:无事件存储时任务状态与事件不保留,只能重新发起。
- 事件存储无限期保留:需配置过期清理,避免内存与磁盘膨胀。
追问
- 事件存储存哪些事件?答:进度通知、工具结果与后续消息。
- 重连续传需要会话粘性吗?答:事件存在内存实例时需要粘到同一实例;共享存储才可跨实例补收。
- 存储能持久化到外部系统吗?答:EventStore 支持注入外部存储后端;外部后端可用性见 037 题的未核实项。
04.7.18.3-015 反向代理为什么必须关闭响应缓冲?
一句话结论
Streamable HTTP/SSE 响应是持续事件流,代理若开启响应缓冲,会把事件攒到响应结束或缓冲区满才转发,进度通知延迟甚至丢失。代理必须关闭对 MCP 端点的响应缓冲,让事件实时透传;这是 HTTP 部署最关键的代理设置之一。
概念解释
- 缓冲行为:代理默认聚合响应体,适合普通 JSON 接口,不适合事件流。
- 事件时效:进度、日志等事件需要即时到达客户端。
- 配置位置:反向代理站点配置中针对 MCP 路径关闭缓冲。
原理流程
- 客户端经代理请求 MCP 端点。
- 服务端写入 SSE 事件流。
- 代理关闭缓冲后逐事件转发;缓冲开启则事件被攒批延迟。
代码或图示
location /mcp {
proxy_buffering off;
proxy_pass http://127.0.0.1:8000;
}
常见误区
- 只在全局关闭缓冲:其他普通接口可能受影响,应针对 MCP 路径配置。
- 忽略 Web 服务器自身缓冲:应用服务器与代理两层缓冲都需确认关闭。
追问
- 不关闭缓冲有什么现象?答:进度长时间不更新,任务结束后事件一次性涌出,客户端误判卡死。
- 缓冲关闭影响普通 API 吗?答:按路径分别配置,MCP 路径关缓冲,其他接口保留默认。
- 云托管网关也支持关缓冲吗?答:取决于网关能力,需确认其 SSE/流式透传配置。
04.7.18.3-016 代理读超时、空闲超时与长任务的关系是什么?
一句话结论
代理与网关的读超时、空闲超时决定长连接能存活多久:长任务期间若没有事件输出,空闲超时会切断连接;应放宽 MCP 端点超时,并通过进度上报保持链路活跃。超时预算需与客户端超时、工具执行超时逐层对齐,避免中间层先断开。
概念解释
- 读超时:等待响应数据的最大间隔;空闲超时:连接无活动的最大时长。
- 长任务风险:阻塞期间无事件,触发代理空闲断开。
- 活跃信号:进度通知、周期日志或心跳维持链路活性。
原理流程
- 梳理各层超时:代理、网关、应用服务器、客户端、工具下游。
- 按最长任务预算放宽代理空闲超时。
- 任务中定期上报进度保持活跃,超时不可控时配合事件存储重连续传。
代码或图示
proxy_read_timeout 300s;
proxy_send_timeout 300s;
常见误区
- 只调应用服务器超时,代理默认 60 秒仍断开:中间层超时先触发。
- 长任务不打进度:无活跃事件,空闲超时误判连接死亡。
追问
- 超时设置多长合适?答:按任务最长执行时间加余量压测确定,不套用默认值。
- 超时断开后任务还在跑吗?答:服务端任务可能继续,客户端需靠事件存储或重新发起恢复结果。
- 客户端超时如何配合?答:客户端等待时间应大于代理与任务预算,避免先放弃。
04.7.18.3-017 会话状态在内存中如何存放与隔离?
一句话结论
有状态 HTTP 模式下,会话上下文保存在服务端进程内存:协商版本、能力、认证结果、订阅关系与任务状态按会话标识区分。不同会话条目独立存放,工具函数经 Context 访问当前会话,不使用模块级全局变量保存身份与状态。
概念解释
- 存储结构:会话表按标识索引会话上下文对象。
- 隔离边界:会话间数据互不可见,认证结果按会话隔离。
- 生命周期:连接关闭或超时后条目清理,内存释放。
原理流程
- 握手创建会话条目,写入版本、能力与身份信息。
- 请求进入时按标识取出会话上下文,注入工具调用。
- 会话结束清理条目,避免内存残留。
代码或图示
session_id -> {protocolVersion, capabilities, auth, subscriptions, taskState}
常见误区
- 用全局 dict 按参数名存用户身份:并发会话互相覆盖,身份串扰。
- 会话状态长期驻留不清理:内存随连接数增长,需过期回收。
追问
- 会话内存能跨进程共享吗?答:默认保存在进程内存,跨进程共享需接入外部会话/事件存储后端。
- 认证结果存在会话哪里?答:鉴权通过后写入会话上下文,工具经 Context 读取。
- 会话并发上限受什么约束?答:内存、下游连接池与事件循环并发能力。
04.7.18.3-018 不同客户端调用如何互不污染会话上下文?
一句话结论
会话隔离按连接与会话标识实现:每个客户端连接对应独立上下文,工具执行时注入当前会话的 Context,读取的身份、日志与资源读取都只作用于本会话。避免污染的关键是不在模块作用域保存请求级数据,共享资源放生命周期层。
概念解释
- 注入隔离:框架按调用会话构造 Context,函数内不跨会话共享。
- 共享与隔离分层:连接池、配置等共享资源放 lifespan;身份、临时状态放会话。
- 并发安全:异步协程间靠 ContextVar/会话上下文隔离,不靠全局变量。
原理流程
- 每个连接握手后建立独立会话上下文。
- 工具调用时框架注入对应 Context。
- 会话数据只在本会话读写,共享资源跨会话复用。
代码或图示
@mcp.tool
def current(ctx: Context) -> dict:
return {"client": ctx.client_id}
常见误区
- 在工具内把用户信息存到全局变量:下一并发会话读到错误身份。
- 复用 Context 对象给多个会话:框架按调用注入,不应手工跨会话传递。
追问
- 异步协程间上下文如何隔离?答:框架按会话构造 Context,经上下文变量在协程间隔离,不使用模块级全局变量。
- 会话级缓存放哪里?答:放会话上下文,不放模块级缓存。
- 如何测试隔离性?答:内存内并发两个会话调用同一工具,断言身份与状态互不干扰。
04.7.18.3-019 客户端重连后会话丢失的典型场景是什么?
一句话结论
会话丢失常见于:有状态会话只存内存且重连落到另一实例、空闲超时会话已回收、无状态模式本就不保留上下文、事件存储未配置导致任务事件不补收。重连后拿不到原会话时,客户端需重新握手;需要恢复任务结果时依赖共享会话存储或事件存储。
概念解释
- 实例漂移:多副本无粘性,重连到未持有会话的实例。
- 过期回收:空闲超时后会话条目被清理。
- 无状态限制:请求自包含,无跨请求记忆可恢复。
原理流程
- 连接断开后客户端重连,带回会话标识。
- 服务端查找会话:存在则续接;不存在则标识失效。
- 客户端重新握手,必要时重新发起任务或从事件存储补收。
代码或图示
reconnect -> 查 session_id -> 命中: 续接
-> 未命中: 重新握手 / 重新发起任务
常见误区
- 多副本部署不做粘性也不共享存储:会话必然漂移丢失。
- 长任务结果依赖会话保留:无存储支撑时断线即结果不可恢复。
追问
- 如何避免重连丢会话?答:会话粘性或共享会话/事件存储;无状态设计则让请求自包含。
- 会话超时在哪里配置?答:由传输层空闲超时与框架会话回收策略控制;具体超时参数名与默认值需按安装版本核实(待确认:验证点:会话空闲超时配置参数)。
- 重连后旧任务还能拿到结果吗?答:事件可补收时可以,否则需重新发起。
04.7.18.3-020 挂载前缀与 root_path 对端点 URL 有什么影响?
一句话结论
MCP 子应用挂载到父应用前缀下后,最终端点 URL = 挂载前缀 + 子应用内路径;代理或网关再外层映射时需考虑 root_path 与路径重写。客户端连接地址、OAuth 发现 URL 与内部路由都要按完整路径对齐,路径错位会导致握手 404 或回调失败。
概念解释
- 挂载前缀:父应用
mount的路径段。 - root_path:代理后部署时告知应用的外部路径前缀,影响内部生成的 URL。
- 路径一致性:端点、发现文档、回调地址使用同一套路径基准。
原理流程
- 父应用挂载 MCP 子应用,确定前缀。
- 子应用内配置端点路径,拼成完整内部 URL。
- 代理/网关映射外部路径,必要时配置 root_path,客户端按外部完整地址连接。
代码或图示
mcp_app = mcp.http_app(path="/mcp")
api.mount("/analytics", mcp_app)
# 内部: /analytics/mcp
# 代理外层若加 /api 前缀, 需对齐 root_path 与重写规则
常见误区
- 只按子应用路径配置客户端地址:漏掉挂载前缀导致 404。
- 代理重写路径后应用内部生成 URL 不一致:OAuth 回调与发现文档路径错乱。
追问
- root_path 在哪里设置?答:由父 ASGI 应用按代理外部前缀配置
root_path,作为应用内部生成 URL 的路径基准。 - 路径错位怎么排查?答:对比客户端请求 URL、代理转发路径、父应用挂载路由与子应用路径。
- 多实例挂载如何避免前缀冲突?答:每个实例分配独立挂载前缀。
04.7.18.3-021 CORS 配置与 OAuth 路由中间件如何避免冲突?
一句话结论
跨域访问需要在父应用或传输层配置 CORS 中间件,放行来源、方法与凭据头;OAuth 发现、回调与鉴权中间件按路由顺序挂载,避免 CORS 预检被鉴权拦截。中间件顺序错误会导致预检失败或凭据头被剥离,需在挂载 MCP 子应用前统一规划。
概念解释
- CORS 预检:OPTIONS 请求由 CORS 中间件先处理,不应被鉴权拦截。
- 凭据头:Authorization、会话标识头需在允许列表内。
- 顺序原则:CORS 包装在最外层,鉴权与业务路由在内层。
原理流程
- 父应用先挂 CORS 中间件,配置允许来源与凭据头。
- 再挂鉴权/OAuth 路由与 MCP 子应用。
- 浏览器预检 OPTIONS 由 CORS 应答,实际请求再走鉴权。
代码或图示
from fastapi.middleware.cors import CORSMiddleware
api.add_middleware(
CORSMiddleware,
allow_origins=["https://example.com"],
allow_credentials=True,
allow_methods=["*"],
allow_headers=["Authorization", "Mcp-Session-Id"],
)
常见误区
- 鉴权中间件先于 CORS:预检请求无凭据被 401 拦截,浏览器拿不到 CORS 头。
- 允许所有来源又携带凭据:浏览器安全模型禁止通配来源与凭据组合,应显式列出来源。
追问
- 服务端到服务端调用需要 CORS 吗?答:不需要,CORS 是浏览器跨域限制,后端直连不涉及。
- 会话标识头需要加入允许头吗?答:需要,浏览器跨域时自定义头必须在 CORS 允许列表。
- 中间件顺序怎么验证?答:浏览器开发者工具看预检响应头与状态码。
04.7.18.3-022 TLS 终止位置与内网 HTTP 部署如何取舍?
一句话结论
TLS 可在客户端到代理之间终止,代理到内网服务走 HTTP;也可在应用层直接终止。终止位置决定证书管理、内网明文风险与配置复杂度。公网入口应在代理或网关层终止 TLS,内网链路按安全等级决定是否再加密;凭据与会话标识在链路上必须受保护。
概念解释
- 代理终止:代理持有证书,后端内网 HTTP,证书集中管理。
- 应用终止:应用直接持有证书,链路端到端加密,证书分散到实例。
- 内网风险:内网 HTTP 链路可被监听,敏感部署需评估内网隔离等级。
原理流程
- 确定部署拓扑:公网入口、代理层、应用实例。
- 选择 TLS 终止位置,配置证书与转发协议。
- 内网链路按安全要求决定 HTTP 或 HTTPS,凭据不通过明文公网传输。
代码或图示
client --TLS--> reverse proxy --HTTP--> app (内网隔离)
client --TLS--> reverse proxy --HTTPS--> app (内网再加密)
常见误区
- 公网直连应用却用 HTTP:令牌与会话标识明文暴露。
- 代理终止 TLS 后内网完全不设防:内网仍需网络隔离与访问控制。
追问
- 证书在哪里更新?答:终止 TLS 的一层持有证书并负责续期。
- 代理转发如何保留原始协议信息?答:按代理头传递,应用据此生成正确的外部 URL。
- 本地开发可以 HTTP 吗?答:本地回环调试可走 HTTP,公网与跨机部署必须加密。
04.7.18.3-023 Bearer token 请求头校验流程是什么?
一句话结论
客户端在 Authorization: Bearer <token> 头携带令牌,服务端在请求进入协议处理前校验令牌:格式解析、签名/有效性/过期时间校验,通过后把身份与 scope 写入会话;失败返回鉴权错误。校验在传输层中间件完成,工具内不再重复解析原始令牌。
概念解释
- 令牌来源:请求头 Authorization,按 Bearer 方案提取。
- 校验项:签名、过期时间、签发方、受众、scope 等(按令牌类型)。
- 结果落位:校验通过的身份信息写入会话上下文,供工具与鉴权判断使用。
原理流程
- 请求到达,鉴权中间件提取 Bearer 令牌。
- 调用校验器验证签名、有效期与声明。
- 通过则写入会话身份并放行;失败返回 401/鉴权错误,不进入工具执行。
代码或图示
Authorization: Bearer eyJhbGciOi...
常见误区
- 工具内再从头解析令牌:身份应在中间层校验后注入会话,避免重复解析与绕过。
- 只检查令牌存在不验签名:伪造令牌可通过,必须验签与有效期。
追问
- 令牌过期返回什么?答:401 鉴权失败,客户端按刷新流程重新获取。
- 令牌能放在查询参数吗?答:不推荐,查询参数易进日志与代理记录,优先请求头。
- 校验失败是否记录详细错误?答:只记通用失败与必要标识,不泄露校验细节。
04.7.18.3-024 OAuth 2.1 中服务端作为资源服务器(RS)承担什么角色?
一句话结论
MCP 服务端在 OAuth 2.1 模型中通常作为资源服务器:接收并校验访问令牌,按令牌 scope 决定开放哪些工具/资源,不负责用户登录与令牌签发。授权服务器(AS)负责认证、发令牌与发现元数据;客户端持令牌访问 RS。角色边界决定了服务端实现只做令牌校验与授权判断。
概念解释
- 资源服务器 RS:保护受保护资源,校验令牌,执行 scope 授权。
- 授权服务器 AS:签发访问令牌,提供发现与令牌端点。
- 客户端:向 AS 取得令牌后访问 RS。
原理流程
- 客户端向 AS 完成授权流程取得访问令牌。
- 客户端带令牌请求 MCP 服务端(RS)。
- RS 校验令牌与 scope,放行对应能力;不通过则拒绝。
代码或图示
client --token--> MCP server (RS)
AS 签发 token; RS 校验 token + scope
常见误区
- 在 MCP 服务端实现登录页面与令牌签发:那是 AS 职责,RS 只做校验授权。
- 把所有 scope 检查放到工具内部散落判断:应集中在鉴权层按能力映射。
追问
- RS 需要访问 AS 数据库吗?答:不需要,靠令牌内声明或远程校验/ JWKS 验签。
- 令牌校验能离线完成吗?答:JWT 可凭公钥/JWKS 离线验签;不透明令牌需远程校验。
- 多服务端共享 AS 吗?答:可以,同一 AS 为多个 RS 签发带不同 scope 的令牌。
04.7.18.3-025 token 校验器与 JWT Verifier 的职责是什么?
一句话结论
FastMCP 2.x 通过 TokenVerifier 子类把原始令牌转换为可信任的身份与声明对象:JWTVerifier 验签名、查 JWKS、校验过期/签发方/受众;StaticTokenVerifier 比对预配置令牌并附带 client_id 与 scope;IntrospectionTokenVerifier 按 RFC 7662 远程校验不透明令牌。校验通过输出 AccessToken(含 client_id、scopes、expires_at、claims),鉴权层据此授权。
概念解释
- JWT Verifier:基于公钥或 JWKS 验证 JWT 签名与标准声明。
- 静态 token 校验器:开发/内部场景比对固定令牌,映射身份与 scope。
- 输出统一:无论令牌类型,校验结果结构一致,便于会话写入与授权判断。
原理流程
- 配置校验器:JWT 提供 issuer/audience/JWKS;静态提供令牌映射表。
- 请求令牌进入校验器,逐项校验。
- 通过返回身份声明;失败抛鉴权错误,中间件拒绝请求。
代码或图示
from fastmcp.server.auth.providers.jwt import StaticTokenVerifier
verifier = StaticTokenVerifier(
tokens={
"dev-token": {"client_id": "cli-1", "scopes": ["tools:read"]}
},
required_scopes=["tools:read"],
)
常见误区
- 静态令牌用于生产:固定令牌不可轮换、无过期与 scope 粒度,仅限内部/开发环境。
- 验签跳过 audience/issuer 校验:跨服务令牌可能被误用,标准声明必须校验。
追问
- JWKS 地址如何配置?答:
JWTVerifier传jwks_uri定期拉取公钥,或传public_key固定公钥;HMAC 时传对称密钥。 - 校验器缓存 JWKS 吗?答:
JWTVerifier定期拉取 JWKS 公钥,密钥轮换由 JWKS 端点保证。 - 校验失败异常如何映射?答:统一映射为 401/协议鉴权错误,不暴露内部校验细节。
04.7.18.3-026 scope 权限控制如何按能力收窄?
一句话结论
scope 是令牌携带的授权范围声明,服务端按 scope 决定暴露或允许调用哪些工具、资源与提示。能力到 scope 的映射集中配置:缺少对应 scope 时拒绝调用或在清单中隐藏对应组件。收窄原则是最小权限,每个能力只要求必要 scope,不按粗粒度角色一刀切。
概念解释
- scope 粒度:按能力划分(读、写、特定资源),而非整服务端放行。
- 映射位置:鉴权层或组件元数据标注所需 scope。
- 两种策略:调用前拒绝(返回权限错误)或清单隐藏(不列出无权限组件)。
原理流程
- 定义能力与 scope 映射表。
- 令牌校验后解析 scope 集合。
- 清单生成与调用检查时按映射放行;无 scope 拒绝或隐藏。
代码或图示
tools:read -> 只读工具可见可调用
tools:write -> 写工具额外要求该 scope
常见误区
- 一个大 scope 覆盖全部能力:权限无法细分,泄露后影响面过大。
- 只在清单隐藏不做调用校验:客户端可直接构造调用,服务端必须二次鉴权。
追问
- scope 检查放在哪一层?答:鉴权中间件统一拦截,工具内只做业务规则判断。
- 匿名访问能配 scope 吗?答:匿名按最小开放范围,仅暴露公开组件。
- 多 scope 是 AND 还是 OR?答:按映射规则定义,敏感能力通常要求全部命中。
04.7.18.3-027 认证结果如何写入会话并供工具读取身份?
一句话结论
鉴权通过后,身份声明(client_id、scope、过期时间等)写入当前会话上下文;工具函数经 Context 或会话对象读取身份,做数据归属与审计,不直接从请求头重新解析。会话随请求生命周期隔离,身份信息不跨会话共享。
概念解释
- 写入时机:令牌校验通过、会话建立后。
- 读取路径:Context 暴露身份字段;工具按字段做授权与归属判断。
- 审计价值:调用记录关联 client_id,便于追溯。
原理流程
- 鉴权中间件校验令牌,得到身份声明。
- 框架把声明挂到会话上下文。
- 工具执行时经 Context 读取身份,记录调用日志与权限判断。
代码或图示
@mcp.tool
def whoami(ctx: Context) -> dict:
return {"client_id": ctx.client_id}
常见误区
- 工具内再读 Authorization 头:跳过会话身份模型,易与鉴权层结论不一致。
- 身份信息放全局变量:并发会话身份串扰。
追问
- Context 暴露哪些身份字段?答:经
get_access_token()取得AccessToken,读取client_id、scopes、expires_at与claims。 - 令牌刷新后会话身份更新吗?答:按会话与令牌生命周期判断,过期后需重新鉴权。
- 无鉴权环境身份字段是什么?答:可能为空或默认标识,工具需处理匿名情况。
04.7.18.3-028 OAuth 发现端点与 RFC 8414/9728 元数据如何提供?
一句话结论
OAuth 资源服务器可提供元数据发现端点:/.well-known/oauth-authorization-server 描述授权服务器位置、令牌端点、JWKS 与支持的 scope,/.well-known/oauth-protected-resource/* 描述受保护资源;客户端据此动态配置授权流程。元数据标准涉及 RFC 8414(OAuth 2.0 授权服务器元数据)与 RFC 9728(OAuth 2.0 受保护资源元数据)。
概念解释
- 发现元数据:避免客户端硬编码授权服务器地址与端点。
- RS 暴露点:保护资源时引导客户端发现 AS 配置。
- 标准演进:MCP OAuth 配置随规范版本调整,按当前 MCP 规范与所装 SDK 版本核对。
原理流程
- 服务端配置授权服务器元数据或发现端点。
- 客户端访问发现端点获取 AS 地址、JWKS、scope 等信息。
- 按元数据完成授权与令牌交换,再带令牌访问 MCP 端点。
代码或图示
/.well-known/oauth-authorization-server -> AS metadata
/.well-known/oauth-protected-resource -> RS metadata
常见误区
- 硬编码授权服务器地址到所有客户端:AS 迁移后配置全量改动。
- 照抄旧规范端点路径:MCP OAuth 规范版本演进,路径与字段需核对当前实现。
追问
- 元数据由 RS 还是 AS 提供?答:AS 元数据在 AS;RS 保护资源描述在 RS 侧,两者配套。
- 如何核对支持的标准版本?答:对照当前 MCP 规范版本页与 FastMCP 迁移说明。
- 发现端点需要鉴权吗?答:元数据通常公开访问,敏感声明不放入公开元数据。
04.7.18.3-029 静态 token 如何通过环境变量注入与轮换?
一句话结论
开发或内部场景可用静态令牌映射,但令牌必须从环境变量或配置注入,不写进源码与文档;轮换时更新环境变量并重启/重载实例。静态令牌无过期与细粒度授权,生产环境应切换到 OAuth/JWT 方案。
概念解释
- 注入方式:进程启动环境变量读取令牌与映射,配置与代码分离。
- 轮换:更换环境变量值后重启服务端实例,旧令牌随之失效。
- 适用边界:本地联调、内网工具,不作为生产鉴权主方案。
原理流程
- 环境变量配置令牌、client_id 与 scope。
- 启动时读取并构造静态校验器。
- 轮换时更新环境变量、重启实例,旧令牌失效。
代码或图示
import os
token = os.environ["MCP_STATIC_TOKEN"]
# 校验器用环境变量构造,源码中不出现令牌字面量
常见误区
- 把示例令牌提交进仓库:令牌泄露后需全部轮换。
- 多实例环境变量不一致:部分实例旧令牌仍生效,轮换不彻底。
追问
- 静态令牌支持多客户端吗?答:映射表可配多组令牌与身份,按条目区分。
- 环境变量里令牌会出现在进程列表吗?答:环境变量对同主机进程可见,主机需控制访问边界。
- 生产能长期用静态令牌吗?答:不推荐,缺过期、吊销与审计粒度,应使用 OAuth 方案。
04.7.18.3-030 鉴权失败时 HTTP 状态码与协议错误如何区分?
一句话结论
传输层鉴权失败(缺少/无效令牌)通常返回 HTTP 401,未授权访问返回 403;协议层业务错误在已握手会话内以 JSON-RPC error 返回。两层错误不要混同:连接建立前的访问控制走 HTTP 状态,握手后的工具权限与业务失败走协议错误。
概念解释
- 401:未认证,令牌缺失或无效,客户端需重新获取凭据。
- 403:已认证但无权限,scope 不足。
- 协议 error:会话内方法执行失败,带协议错误码与 data。
原理流程
- 请求进入先过鉴权层:失败返回 401/403。
- 鉴权通过后进入协议处理:业务/校验失败返回 JSON-RPC error。
- 客户端按 HTTP 状态处理重认证,按协议错误处理业务失败。
代码或图示
no/invalid token -> HTTP 401
authenticated, no scope -> HTTP 403
session tool failure -> JSON-RPC error {code, message, data}
常见误区
- 把鉴权失败包装成协议 error:握手前没有会话上下文,无法形成协议响应。
- 业务权限不足返回 403:会话内鉴权失败应走协议错误,HTTP 403 留给传输层授权。
追问
- 401 响应需要带 WWW-Authenticate 吗?答:按 OAuth/HTTP 鉴权规范建议提供,便于客户端识别方案。
- 错误响应能返回内部细节吗?答:不能,只给通用提示,细节落服务端日志。
- 客户端如何重试 401?答:重新走授权流程获取新令牌后重试原请求。
04.7.18.3-031 代理链路中头信息透传与客户端自带凭据如何处理?
一句话结论
代理转发时需保留 Authorization、会话标识与必要的追踪头,同时避免把内部头暴露给不可信客户端;客户端凭据由客户端按授权方案自带,服务端不替客户端保存或注入下游凭据。头透传规则在代理与中间件层统一配置,敏感头不进入业务日志。
概念解释
- 透传头:授权、会话、追踪标识在链路各层传递。
- 防伪造:内部信任头(原始 IP、内部标识)只由代理写入,客户端伪造需被覆盖。
- 凭据归属:下游调用凭据在服务端侧管理,不依赖客户端头传递密钥。
原理流程
- 代理配置转发允许头列表,剥离或覆盖不可信内部头。
- 服务端中间件读取透传的授权与追踪信息。
- 业务处理按会话身份与追踪标识记录日志,不回显敏感头。
代码或图示
client -> proxy: Authorization, Mcp-Session-Id, X-Trace-Id
proxy -> app: 透传必要头, 覆盖伪造的内部头
常见误区
- 信任客户端直传的内部头:攻击者可伪造身份头,必须由代理重写。
- 把 Authorization 头写进访问日志:令牌泄露到日志系统。
追问
- 原始客户端 IP 怎么获取?答:由代理按可信头写入,应用只信任代理来源。
- 头名大小写敏感吗?答:HTTP 头不区分大小写,读取按框架归一化处理。
- 多余头会被转发吗?答:按代理配置的头白名单或默认转发策略,敏感部署应显式控制。
04.7.18.3-032 容器镜像如何选择基础镜像、依赖与启动命令?
一句话结论
镜像应锁定受维护的基础镜像与依赖版本,分层安装运行时与应用代码,启动命令明确传输方式、监听地址与端口。镜像内不打包密钥与本地路径,配置通过环境变量注入;多阶段构建可减小最终镜像体积。具体运行时版本与框架依赖以项目锁定文件为准。
概念解释
- 基础镜像:选择带安全更新的官方运行时镜像,避免宿主机无关工具。
- 依赖锁定:按锁文件安装,保证可复现构建。
- 启动命令:容器入口明确启动 MCP 服务端,参数由环境变量覆盖。
原理流程
- 构建阶段安装依赖与代码,最终阶段只保留运行所需。
- 镜像设置非 root 用户、工作目录与启动命令。
- 运行时通过环境变量注入配置,密钥从密钥管理获取。
代码或图示
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt ./
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["python", "-m", "mcp_server"]
常见误区
- 镜像内写死开发配置与令牌:构建产物可被导出,敏感信息必须外置。
- 用通用大镜像跑服务:体积大、攻击面广,应精简运行时镜像。
追问
- 容器内用什么用户运行?答:建议非 root 用户,限制文件与进程权限。
- 依赖版本怎么锁定?答:按项目锁文件安装,不在镜像构建时随意升级。
- stdio 服务端适合容器吗?答:stdio 由客户端拉起子进程,容器化通常用于 HTTP 传输服务端。
04.7.18.3-033 启动参数 host/port/path 与环境变量如何配置?
一句话结论
FastMCP 2.x 的 mcp.run(transport="http") 默认 host 127.0.0.1、port 8000、路径 /mcp,可在运行参数或 http_app(path=...) 中覆盖;host 绑定回环还是全网卡按部署拓扑决定。参数优先从环境变量读取并给安全默认值,不在代码各处硬编码。
概念解释
- host:监听地址,本地调试绑回环,容器内绑 0.0.0.0 由代理访问。
- port:监听端口,避免与同机其他服务冲突。
- path:MCP 端点路径,与代理路由和客户端地址对齐。
原理流程
- 启动入口读取环境变量,解析 host/port/path。
- 用解析值启动 HTTP 传输服务。
- 代理与客户端按同一组配置连接。
代码或图示
import os
host = os.environ.get("MCP_HOST", "0.0.0.0")
port = int(os.environ.get("MCP_PORT", "8000"))
path = os.environ.get("MCP_PATH", "/mcp")
常见误区
- 公网环境绑回环地址:外部无法访问;内网调试绑全网卡又缺访问控制。
- 端口写死在代码里:同机多实例冲突,应可配置。
追问
- 端口冲突怎么排查?答:检查监听端口占用与代理转发目标。
- 环境变量缺失用什么默认值?答:给开发安全默认值,生产环境显式配置。
- 启动参数命令行与环境变量谁优先?答:FastMCP 全局设置以
FASTMCP_前缀环境变量为基准,显式传入的运行参数覆盖环境变量值。
04.7.18.3-034 容器内进程模型与信号处理有什么注意点?
一句话结论
容器内服务端应以前台进程运行,正确处理终止信号:收到 SIGTERM 后停止接收新请求,等待进行中调用完成后释放资源退出。单容器单进程模型下不要在应用内 fork 后台进程;信号转发由容器运行时与启动命令共同保证。
概念解释
- 前台运行:容器主进程即服务进程,日志走标准流。
- 信号处理:SIGTERM 触发优雅停机,SIGINT 用于本地中断。
- 子进程:应用内派生的后台任务需在停机时一并清理。
原理流程
- 容器启动主进程,注册信号处理器。
- 收到终止信号后关闭监听,停止新请求。
- 等待在途调用与后台任务结束,释放连接池后退出。
代码或图示
SIGTERM -> stop accepting -> drain in-flight -> release resources -> exit
常见误区
- 启动命令用 shell 后台化进程:信号无法直达主进程,容器停机超时。
- 忽略在途任务直接退出:进行中工具调用被硬切断,结果丢失。
追问
- 停机等待多久?答:设优雅超时,超过后强制退出,与编排层终止期限对齐。
- 后台定时任务怎么处理?答:停机时取消或等待完成,避免任务悬挂。
- 多进程模型需要什么?答:按运行时并发模型评估,容器内避免手工 fork 工作进程。
04.7.18.3-035 多副本部署时为什么有状态会话需要粘性?
一句话结论
有状态会话与事件存在单实例内存中,客户端后续请求必须落到持有该会话的实例,否则会话标识查不到、上下文丢失。粘性(会话亲和)通过代理按会话标识路由到固定实例解决;但粘性会削弱负载均衡,实例故障时会话仍会丢失。
概念解释
- 状态位置:会话上下文、订阅关系、事件存储在实例内存。
- 粘性依据:会话标识或客户端标识作为路由键。
- 局限:实例重启/漂移导致会话失效;负载不均与扩缩容受影响。
原理流程
- 握手请求落到实例 A,会话保存在 A。
- 代理按会话标识把后续请求路由回 A。
- A 故障或扩缩容后会话丢失,客户端重新握手。
代码或图示
session-1 -> instance A (sticky)
session-2 -> instance B (sticky)
常见误区
- 无粘性多副本跑有状态服务:请求随机漂移,会话时有时无。
- 把粘性当高可用:实例故障会话不可恢复,需共享存储或无状态设计兜底。
追问
- 粘性按什么键路由?答:会话标识优先,其次客户端标识,按代理能力配置。
- 粘性会话能跨实例迁移吗?答:内存状态不能自动迁移,需外部共享存储。
- 健康检查会打断粘性吗?答:实例摘除后其会话需重建,客户端应能重连。
04.7.18.3-036 无状态服务水平扩展的前提与局限是什么?
一句话结论
无状态模式下请求自包含、不依赖实例内存会话,多副本可自由负载均衡,水平扩展简单;局限是跨请求的会话记忆、资源订阅与长任务进度推送受限,需要结果可重算或外部存储支撑。适合调用短、可重复、无会话推送需求的场景。
概念解释
- 扩展前提:身份与所需参数每次请求带上,共享资源外置(数据库、缓存、对象存储)。
- 局限:无会话上下文,订阅/进度推送降级;重复调用需保证幂等。
- 适用边界:读多写少、短事务、可水平扩容的工具服务。
原理流程
- 设计服务不保存请求间状态,所需数据来自请求与外部存储。
- 多副本前置于负载均衡,请求任意落到实例。
- 长任务与推送需求由外部队列/存储补偿。
代码或图示
client -> load balancer -> replica A / B / C (stateless, shared backend)
常见误区
- 宣称无状态却在模块级缓存会话数据:实例间缓存不一致,破坏扩展性。
- 无状态模式下保留会话内订阅预期:功能受限,需在接口文档说明。
追问
- 无状态下长任务怎么跟踪?答:任务状态与结果放外部存储,客户端按任务标识查询。
- 共享缓存算无状态吗?答:进程外共享存储支持水平扩展,本地内存缓存仍有状态限制。
- 混合部署可行吗?答:按能力拆分,有状态组件与无状态组件分别扩展。
04.7.18.3-037 当前版本对共享会话存储的支持情况如何?
一句话结论
跨副本共享会话/事件存储依赖框架提供的外部后端:FastMCP 2.x 默认内存存储,会话与事件只在本实例有效;接入 Redis 等共享后端后才可跨实例恢复。未核实后端可用性前,不要在架构上假设会话可跨实例恢复(待确认:验证点:当前版本外部会话/事件存储后端)。
概念解释
- 内存后端:默认实现,单机进程内有效。
- 外部后端:共享存储支撑多副本会话与事件续传。
- 核实路径:查框架文档与存储接口定义,跑跨实例重连用例验证。
原理流程
- 确认版本提供的会话/事件存储后端清单。
- 若有外部后端,按配置接入共享存储。
- 跨实例重连测试会话与事件是否可恢复;不支持则按粘性或无状态方案部署。
代码或图示
# 外部会话/事件存储后端、配置参数与数据结构需按安装版本核实
常见误区
- 凭其他框架经验假设 Redis 后端存在:版本未提供时多副本会话必然漂移。
- 共享存储未做过期清理:会话与事件长期堆积,存储膨胀。
追问
- 怎么核实是否支持?答:查当前版本文档与存储接口定义,实跑跨实例重连用例验证。
- 共享存储挂了影响什么?答:会话恢复与事件续传降级,需评估可用性与兜底。
- 会话存储需要持久化吗?答:按恢复需求决定,短期会话可内存,长任务结果需外部持久化。
04.7.18.3-038 结构化日志应包含哪些字段与级别?
一句话结论
运行日志应结构化输出:时间、级别、事件类型、会话标识、client_id、工具/资源名称、耗时与错误标识;敏感参数与令牌不进入日志。级别区分 debug/info/warning/error,生产默认 info 以上,关键调用与异常强制留痕。日志字段贯穿请求链路,便于按会话与工具检索。
概念解释
- 基础字段:时间、级别、事件、服务端名称。
- 关联字段:会话标识、client_id、trace id、组件名。
- 业务字段:入参摘要、耗时、错误码;敏感内容脱敏。
原理流程
- 日志初始化配置结构化格式与级别输出。
- 请求进入、组件调用、返回与异常各阶段记录字段。
- 日志采集按会话与 trace 检索,错误日志关联错误码。
代码或图示
{
"level": "info",
"event": "tool_call",
"session": "sess-1",
"client_id": "cli-1",
"tool": "get_order",
"duration_ms": 12
}
常见误区
- 日志只写自由文本:无法按会话/工具聚合检索。
- 完整记录入参与令牌:敏感信息泄露到日志系统。
追问
- 入参能记哪些?答:记标识与摘要,大对象与敏感字段脱敏或不记。
- 日志级别怎么选?答:启动与关键流程 info,排查细节 debug,异常 warning/error。
- Context 日志与本地日志关系?答:Context 日志通知发往客户端,本地结构化日志落服务端。
04.7.18.3-039 调用次数、耗时、错误率等指标如何采集?
一句话结论
围绕组件调用采集指标:调用次数、成功/失败计数、耗时分布、错误码分布与并发数;在框架边界埋点,不侵入每个工具函数。指标按工具/资源/提示与身份维度聚合,配合日志与追踪定位慢调用与错误上涨。具体指标导出接口按所选可观测性栈实现。
概念解释
- 计数器:调用总数、成功数、失败数,按错误码分类。
- 耗时指标:直方图或摘要记录延迟分布,不只记平均值。
- 维度:组件名、会话/客户端、错误类型,便于下钻定位。
原理流程
- 在请求进入与返回边界统一埋点。
- 记录组件名、结果状态、耗时与错误码。
- 指标导出到监控栈,配置阈值告警。
代码或图示
tool_calls_total{tool="get_order",status="ok|error"}
tool_call_duration_ms{tool="get_order"} histogram
常见误区
- 只记录总耗时不分类:慢工具与错误调用无法区分。
- 在工具内部散落打点:重复且口径不一致,应集中在边界层。
追问
- 指标需要记标签基数吗?答:高基数标签(如 user_id)需控制,避免指标爆炸。
- 慢调用阈值怎么定?答:按 SLA 与分布基线设定告警线。
- 框架自带指标吗?答:FastMCP 2.x 未在公开文档中承诺内置指标导出端点;调用计数、耗时与错误率通常在 ASGI/边界层自行埋点(待确认:验证点:当前版本是否提供内置指标导出接口)。
04.7.18.3-040 trace id 如何贯穿一次调用链路?
一句话结论
一次调用从请求入口生成或接收 trace id,写入会话上下文并随日志、指标与下游调用传递;同一会话的工具调用、资源读取与日志记录共享同一追踪标识,便于串起完整链路。客户端传入的追踪头需校验来源,不可信时重新生成。
概念解释
- 生成与继承:入口无标识则生成,有合法传入则沿用。
- 传递范围:日志字段、下游请求头、异步任务上下文。
- 关联粒度:trace id 串联整条链路,span 标识具体阶段。
原理流程
- 请求入口读取或生成 trace id,挂入上下文。
- 工具执行各阶段日志携带 trace id。
- 下游调用透传追踪头,链路在监控系统按 id 聚合。
代码或图示
incoming request -> trace_id = X-Trace-Id or new
log/metrics/downstream headers all carry trace_id
常见误区
- 异步任务丢失上下文:trace id 未传递到协程/后台任务,链路断裂。
- 信任任意客户端传入的内部追踪值:需限定来源与格式,避免注入伪造标识。
追问
- trace id 存在哪里?答:请求/会话上下文,随调用链路传递,不落全局变量。
- 多轮调用共享一个 trace 吗?答:按会话与链路约定,单次调用与跨请求关联分别设计。
- 日志与指标如何对齐?答:都带同一 trace id 与组件名,便于交叉检索。
04.7.18.3-041 工具调用耗时与下游超时预算如何划分?
一句话结论
一次调用的总耗时预算应分层分配:协议等待、工具执行、下游 API/数据库/文件 IO 各占一段,任一下游超时按预算取消并返回错误。工具不能无限等待下游,超时值与重试策略按下游 SLA 设定;长任务通过进度上报与异步结果衔接,不阻塞会话通道。
概念解释
- 总预算:客户端等待与服务端执行的总时限。
- 下游预算:外部依赖调用单独设超时,留出序列化与处理余量。
- 取消传播:超时后取消下游请求,释放连接与协程资源。
原理流程
- 确定调用总时限,拆分到工具与各下游依赖。
- 下游客户端按预算设超时,失败后映射为业务错误。
- 记录分段耗时指标,定位慢在协议、工具还是下游。
代码或图示
budget: 30s
tool execute: 25s
downstream API: 10s
DB: 5s
response serialize: remainder
常见误区
- 下游调用不设超时:连接悬挂占用并发,拖垮整体吞吐。
- 多层超时叠加不核算:外层已超时,内层仍在等待,资源不释放。
追问
- 下游超时重试几次?答:按幂等性与 SLA 设定,敏感写操作不盲目重试。
- 长任务如何不占住预算?答:转异步任务,进度/结果经事件或查询接口衔接。
- 耗时指标怎么分段?答:记录下游与工具内部分段耗时,边界层汇总。
04.7.18.3-042 如何搭建内存内 client 直连测试?
一句话结论
单元测试不启动网络端口:from fastmcp import Client, FastMCP,把 FastMCP 实例直接传给 Client,async with Client(mcp) as client: 即在内存内直连,完成握手并调用组件。这样测试快、无端口依赖,能覆盖工具逻辑、schema 与错误路径。
概念解释
- 内存内传输:不经过真实 socket/stdio,双方在同一进程内交换报文。
- 测试入口:框架测试辅助提供 client 或 transport 构造。
- 覆盖范围:注册清单、调用结果、参数校验、鉴权与会话隔离。
原理流程
- 测试中构造 FastMCP 实例并注册组件。
- 用内存内传输建立测试客户端连接,触发 initialize 握手。
- 调用工具/资源/提示并断言结果与错误。
代码或图示
from fastmcp import Client, FastMCP
async with Client(mcp) as client:
result = await client.call_tool("add", {"a": 1, "b": 2})
assert result.data == 3
常见误区
- 测试先起真实 HTTP 服务再连:测试慢且受端口与环境影响,应优先内存内。
- 只测成功路径:校验失败、鉴权拒绝、下游异常同样需要用例覆盖。
追问
- 内存内测试能覆盖传输层吗?答:覆盖协议报文与序列化,网络代理行为需另行集成测试。
- 测试需要生命周期启动吗?答:共享资源在 lifespan 初始化,测试按框架辅助触发启动/关闭。
- 并发会话隔离怎么测?答:内存内建立两个 client 会话并发调用,断言上下文互不干扰。
04.7.18.3-043 call_tool 断言如何校验结果内容块与结构化数据?
一句话结论
测试调用工具后,从返回结果中提取内容块或结构化输出,断言字段值、类型与内容块类型符合预期;不只断言“调用没报错”。结构化输出按模型/字典字段校验,文本内容块校验文本片段,媒体块校验编码与 MIME 类型。
概念解释
- 结果结构:成功结果含内容块列表,结构化输出可能单独提供数据字段。
- 断言层次:组件名存在、调用成功、字段值正确、类型匹配。
- 数据还原:必要时把内容块解析为对象再断言,避免只比对原始字符串。
原理流程
- 测试客户端调用工具,传入固定入参。
- 提取结果:内容块文本或结构化数据。
- 断言关键字段、类型与数量,边界值与空结果单独覆盖。
代码或图示
result = await client.call_tool("add", {"a": 1, "b": 2})
assert result.data == 3
assert result.content[0].type == "text"
常见误区
- 断言返回对象整体相等:内部字段演进导致测试脆弱,应断言关键契约字段。
- 忽略空结果与错误码分支:边界条件未覆盖,回归时易漏。
追问
- 文本块怎么取内容?答:
result.content为内容块列表,文本块读text字段;多块时按顺序定位。 - 模型返回怎么断言?答:用模型字段断言,必要时校验 model_dump 结构。
- 结果含二进制块怎么测?答:断言 MIME 类型、编码与长度,不直接比对大段字节。
04.7.18.3-044 错误路径断言应覆盖哪些场景?
一句话结论
测试必须覆盖失败路径:参数校验失败、鉴权/scope 不足、工具业务异常、下游超时与不存在的组件调用。断言错误类型、协议错误码或 HTTP 状态、安全 message,以及日志/指标中的失败记录;确保错误不外泄堆栈与敏感信息。
概念解释
- 校验错误:缺参、类型不符、约束越界。
- 鉴权错误:无令牌、令牌无效、scope 不足。
- 业务与依赖错误:未找到、冲突、下游超时、内部异常兜底。
原理流程
- 为每类错误构造触发用例(非法入参、伪造令牌、下游异常桩)。
- 调用后捕获协议 error 或 HTTP 状态。
- 断言错误码、message 不含堆栈与敏感信息,必要时核对日志记录。
代码或图示
import pytest
from fastmcp.exceptions import ToolError
with pytest.raises(ToolError):
await client.call_tool("get_order", {"order_id": "missing"})
常见误区
- 只测成功路径:失败分支无回归保护,线上错误处理易被改坏。
- 断言错误 message 完整长文本:文案调整会打断测试,应断言错误码与关键提示。
追问
- 校验失败错误码是哪类?答:协议层参数错误对应 JSON-RPC -32602(invalid params),业务错误由工具抛出并经业务错误码返回。
- 下游异常如何模拟?答:测试桩抛出超时/异常,验证服务端包装后的错误。
- 错误日志断言什么?答:记录失败事件与错误标识,不出现令牌与完整敏感入参。
04.7.18.3-045 契约测试如何校验工具清单与 schema 快照?
一句话结论
契约测试调用 list 方法获取工具/资源/提示清单,核对组件名、描述与 inputSchema 结构;可把 schema 快照保存为基准文件,变更时比对差异并人工确认。快照防止签名调整意外改变对外契约,schema 演进需走显式变更流程。
概念解释
- 清单契约:组件名称集合与描述是客户端依赖的接口面。
- Schema 快照:字段、类型、约束、必填项的结构基准。
- 变更管理:快照 diff 需确认是有意演进,而非误改类型或默认值。
原理流程
- 测试连接后拉取 tools/resources/prompts 清单。
- 提取名称集合与 schema 结构,与快照基准比对。
- 不一致时失败提示;有意变更则更新快照并记录说明。
代码或图示
tools = await client.list_tools()
names = {t.name for t in tools}
assert "add" in names
常见误区
- 快照包含易变字段(时间、版本号):diff 噪声大,应固定稳定契约字段。
- schema 变更不更新客户端:服务端契约演进需同步调用方适配。
追问
- 快照存什么格式?答:JSON 结构基准,纳入版本管理。
- 描述文案变更算契约变更吗?答:影响模型选择与使用,应在 diff 中确认。
- 快照测试能替代运行时校验吗?答:不能,还需成功/失败调用用例验证行为。
04.7.18.3-046 经 ASGI transport 测试挂载后的完整链路怎么做?
一句话结论
集成测试把 MCP 子应用挂载到父 ASGI 应用,用 ASGI 测试传输发起真实 HTTP 风格请求,覆盖路由前缀、中间件、鉴权与协议处理全链路。相比内存内直连,它验证挂载顺序、路径拼接与中间件协作;挂载 Starlette 子应用时必须把 mcp_app.lifespan 传给父应用 Mount 的 lifespan 参数。
概念解释
- 挂载验证:父应用前缀、子应用端点路径与中间件顺序。
- 全链路:请求进入 → 中间件 → 协议解析 → 工具执行 → 响应返回。
- 生命周期:测试需正确启动/关闭 ASGI lifespan,共享资源可用。
原理流程
- 构造父应用,挂载 MCP 子应用并配置中间件。
- 用 ASGI 测试传输发起 initialize 与工具调用。
- 断言路由可达、鉴权生效、结果正确,覆盖前缀与路径拼接。
代码或图示
from starlette.applications import Starlette
from starlette.routing import Mount
parent = Starlette(routes=[Mount("/mcp-server", app=mcp_app, lifespan=mcp_app.lifespan)])
常见误区
- 挂载后未传子应用 lifespan:共享资源未初始化,测试中连接池/配置为空。
- 只测子应用直连:漏掉父应用前缀与中间件,部署后才暴露路由问题。
追问
- ASGI 测试需要真实端口吗?答:不需要,测试传输在进程内模拟 ASGI 调用。
- 中间件顺序怎么在测试体现?答:构造不同顺序父应用,验证 CORS/鉴权行为。
- 集成测试覆盖哪些边界?答:404 路径、401 鉴权、挂载前缀拼接与 SSE 响应形态。
04.7.18.3-047 协议 schema 校验与业务校验如何分层?
一句话结论
入参先过协议 schema 校验:类型、必填、枚举、范围与格式;通过后再做业务校验:存在性、归属、权限与领域规则。两层职责分离,协议层拒绝格式非法请求,业务层拒绝规则不满足的请求,错误分别映射到协议参数错误与业务错误。
概念解释
- 协议层:由签名类型与 Field 约束生成 schema,框架自动校验。
- 业务层:领域规则无法用类型表达,在工具函数内判断。
- 错误映射:格式问题归参数错误,规则问题归业务错误,便于客户端区分处理。
原理流程
- 请求参数进入框架,按 inputSchema 校验类型与约束。
- 校验通过后执行工具,函数内做业务规则判断。
- 业务不满足抛领域异常,映射业务错误返回。
代码或图示
@mcp.tool
def get_order(order_id: str) -> dict:
if not order_id:
raise ValueError("order_id 不能为空") # 业务校验
order = repo.find(order_id)
if order is None:
raise NotFoundError("订单不存在")
return order
常见误区
- 把业务规则塞进 schema 枚举:规则动态变化,schema 无法表达存在性与归属。
- 业务校验在协议层之前手写重复判断:应利用框架 schema 自动校验,避免双份维护。
追问
- 严格校验模式影响哪层?答:影响协议 schema 校验严格程度,业务规则仍在工具内。
- 两层错误怎么区分?答:错误码与 message 分层,客户端按类型提示重试或修正参数。
- 校验失败信息暴露内部规则吗?答:对外给必要提示,敏感规则细节不泄露。
04.7.18.3-048 命令注入、路径穿越与资源 URI 校验如何防护?
一句话结论
工具执行外部命令时不拼接用户输入进 shell 字符串,使用参数数组并限制命令白名单;文件路径规范化后限制在允许根目录内,禁止 .. 逃逸;资源 URI 按 scheme 与模板白名单校验,不把输入直接拼成本地路径或 URI 访问。所有外部输入先校验再使用。
概念解释
- 命令注入:避免 shell 解释元字符,参数化调用,最小权限执行。
- 路径穿越:规范化路径后检查前缀是否在允许目录内。
- URI 校验:限定 scheme、主机/模板段,拒绝非法字符与未登记 scheme。
原理流程
- 接收外部输入,先做格式与白名单校验。
- 命令调用走参数数组;路径规范化并做根目录前缀检查;URI 按模板匹配。
- 校验通过才访问下游资源,失败返回安全错误。
代码或图示
from pathlib import Path
BASE = Path("/data/files").resolve()
def safe_path(name: str) -> Path:
p = (BASE / name).resolve()
if not str(p).startswith(str(BASE)):
raise ValueError("路径越界")
return p
常见误区
- 用字符串拼接 shell 命令:输入含分号/管道符即可注入。
- 只过滤
..字符串:编码、符号链接与规范化绕过,应解析后做前缀检查。 - 资源 URI 直接转本地文件路径:未限定 scheme 可访问敏感本地资源。
追问
- 外部命令用什么执行方式?答:参数数组形式调用,不经 shell 解释(按运行时 API 选择)。
- 路径校验要防符号链接吗?答:需要,解析真实路径后再比对根目录。
- URI 白名单在哪里维护?答:资源注册模板与 scheme 清单集中配置。
04.7.18.3-049 速率限制与整体超时防护放在哪一层?
一句话结论
速率限制在传输/中间件层按客户端或会话维度限流,保护服务端不被突发调用打垮;整体超时在框架边界与下游调用双层控制。限流规则按身份、组件与时段配置,超限返回限流错误;工具内部不再各自实现全局限流,避免口径分散。
概念解释
- 限流维度:client_id、会话、IP、组件名,按业务风险选择。
- 超时防护:请求总时限、下游超时、长任务异步化。
- 位置:传输中间件统一拦截,工具函数聚焦业务逻辑。
原理流程
- 中间件识别身份与组件,检查配额与时间窗口。
- 超限返回限流错误,不进入工具执行。
- 执行中按超时预算取消下游调用,记录限流与超时指标。
代码或图示
request -> rate limit check (client, tool, window) -> allow / 429
-> tool execute with per-call timeout
常见误区
- 限流只在单实例内存计数:多副本下配额被放大,需共享计数或按实例配额估算。
- 工具内自行 sleep 等待:占用并发资源,应在入口拒绝排队。
追问
- 限流返回什么状态/错误?答:HTTP 429 或协议限流错误,附带重试提示。
- 限流阈值怎么定?答:压测容量与业务 SLA 确定,区分读写与重资源工具。
- 超时与限流区别?答:限流控制单位时间请求量,超时控制单次调用时长。
04.7.18.3-050 敏感信息为什么不能进入日志与错误返回?
一句话结论
令牌、密钥、密码、个人敏感数据与完整凭据不得写入日志、错误 message、响应 data 或指标标签;错误对外只给通用提示与必要标识,细节落受控服务端日志。日志与错误通道可能被采集、展示给调用方,泄露面必须按最小化原则控制。
概念解释
- 泄露通道:本地日志、stderr、错误响应、指标标签、事件存储。
- 脱敏范围:认证凭据、密钥、身份证/手机号等个人信息、内部路径。
- 最小返回:对外错误不含堆栈、SQL、内部主机与参数明文。
原理流程
- 定义敏感字段清单与脱敏规则。
- 日志记录前过滤/掩码;错误响应构造时剥离敏感细节。
- 代码审查与日志扫描检查敏感信息残留。
代码或图示
def mask(value: str) -> str:
if len(value) <= 4:
return "***"
return value[:2] + "***" + value[-2:]
常见误区
- 异常 message 拼接完整入参:堆栈与参数随错误返回调用方。
- 指标标签记 user_id 等敏感高基数值:既泄露身份又造成标签膨胀。
追问
- 调试需要看敏感值怎么办?答:受控环境临时开启,脱敏规则默认开启,不持久化明文。
- 第三方库日志会带敏感信息吗?答:需检查并配置日志脱敏,避免库默认打印请求头。
- 错误返回能带 request id 吗?答:可以,用标识关联服务端受控日志,不暴露内部细节。
04.7.18.3-051 MCP 服务端与既有 Web 服务同进程共存如何协调端口?
一句话结论
MCP 子应用可挂载到既有 ASGI/Web 应用的同一进程与端口下,按路径前缀区分路由,避免另开端口;挂载时共享父应用的中间件、CORS 与鉴权体系。端口冲突只在各自监听不同端口时出现,同进程共存应通过路由前缀而非多端口拆分。
概念解释
- 同进程挂载:父应用
mountMCP 子应用,复用事件循环与 HTTP 服务。 - 路由隔离:业务 API 与 MCP 端点使用不同前缀,避免路由冲突。
- 资源共享:连接池、配置与后台任务在 lifespan 统一初始化。
原理流程
- 父应用创建时挂载 MCP 子应用到独立前缀。
- 统一配置中间件顺序、CORS 与鉴权。
- 监听单一端口,请求按路径分发到业务路由或 MCP 端点。
代码或图示
mcp_app = mcp.http_app(path="/mcp")
app.mount("/mcp", mcp_app)
# 业务路由: /api/...
# MCP 端点: /mcp
常见误区
- MCP 与业务各起一个端口:进程与连接翻倍,部署与鉴权分散。
- 挂载前忽略子应用 lifespan:共享资源未随父应用启动初始化。
追问
- 同进程会互相阻塞吗?答:异步模型下共享事件循环,任一方阻塞都会影响另一方,需避免同步长阻塞。
- 端口被占用怎么判断?答:启动报错或检查监听端口,调整父应用端口配置。
- 鉴权能复用业务中间件吗?答:可以,挂载前在父应用统一配置,按路径区分策略。
04.7.18.3-052 同进程下 lifespan 与后台任务如何协调?
一句话结论
共享资源(数据库连接池、下游客户端、配置)在 MCP 实例或父应用的 lifespan 中初始化与清理;后台定时任务、消费者与服务端同生命周期启停。同进程共存时,lifespan 启动顺序保证资源先于路由就绪,停机时先停后台任务再释放共享连接。
概念解释
- 启动顺序:lifespan 进入阶段初始化配置、连接池与后台任务。
- 运行期:MCP 工具复用 lifespan 注入的共享资源。
- 关闭顺序:停止后台任务 → 等待在途调用 → 释放连接池与客户端。
原理流程
- 应用启动触发 lifespan,创建共享资源并启动后台任务。
- 组件执行从上下文/依赖获取共享资源,不在函数内新建连接。
- 关闭信号触发 lifespan 退出阶段,按相反顺序清理资源。
代码或图示
from contextlib import asynccontextmanager
@asynccontextmanager
async def lifespan(app):
pool = create_pool()
yield {"pool": pool}
await pool.close()
mcp = FastMCP("demo", lifespan=lifespan)
常见误区
- 工具函数内新建连接池:高频调用反复建连,资源泄漏。
- 后台任务脱离生命周期管理:停机后任务仍在跑,占用连接与协程。
追问
- lifespan 注入对象怎么传给工具?答:经 Context 读取,如
ctx.fastmcp实例与ctx.set_state/get_state存放的共享状态。 - 启动失败如何处理?答:lifespan 抛错应阻断启动,不进入服务就绪状态。
- 同进程两个应用 lifespan 顺序?答:按父应用与挂载子应用的启动嵌套顺序,测试中验证。
04.7.18.3-053 健康检查端点与就绪/存活探针如何设计?
一句话结论
健康检查区分存活探针(进程在跑、未死锁)与就绪探针(依赖可用、可接流量):就绪检查覆盖下游连接池、关键外部依赖;存活检查只反映进程与事件循环状态。MCP 端点本身不作为健康探针,避免把协议握手误当健康判断。探针路径不经过鉴权或按内部网络单独放行。
概念解释
- 存活 liveness:进程存活、事件循环可响应,失败由编排层重启。
- 就绪 readiness:依赖可用、连接池健康,失败时摘流不重启。
- 探针位置:父应用独立健康路由,与 MCP 协议端点分离。
原理流程
- 父应用提供
/health/live与/health/ready路由。 - 就绪检查探测下游依赖与连接池状态。
- 编排层按探针结果重启实例或摘除流量。
代码或图示
GET /health/live -> process alive
GET /health/ready -> dependencies reachable, pool healthy
常见误区
- 用 MCP 握手做健康检查:协议协商开销大,且鉴权/会话状态干扰探针结果。
- 就绪检查不区分依赖:下游抖动时实例被反复重启,应摘流等待恢复。
追问
- 探针需要鉴权吗?答:内部网络按白名单放行,公开暴露的探针不泄露依赖细节。
- 健康检查超时多久?答:短超时快速失败,与编排探测周期对齐。
- 指标能接入探针吗?答:可暴露基础存活信息,详细指标走独立监控端点。
04.7.18.3-054 优雅停机如何处理进行中调用、连接与资源释放?
一句话结论
优雅停机流程:停止接收新请求 → 等待在途工具调用与后台任务完成(或超过宽限强制取消)→ 关闭下游连接池与客户端 → 退出进程。长任务需配合事件存储或外部状态,避免停机硬切断导致结果丢失;停机宽限与编排层终止期限对齐。
概念解释
- 停止接流:关闭监听与新会话,不再派发新调用。
- 在途排空:等待进行中调用收尾,宽限期内未完成则取消。
- 资源释放:连接池、文件句柄、后台任务按顺序清理。
原理流程
- 收到 SIGTERM/关闭信号,进入停机阶段。
- 拒绝新请求,等待在途调用与后台任务结束。
- 释放共享资源,进程退出;超时未结束则强制取消。
代码或图示
signal -> stop accept -> drain in-flight (grace period) -> release pool -> exit
常见误区
- 直接退出进程:在途调用被切断,下游事务与连接残留。
- 等待无限期:编排层到点强杀,应设宽限并记录未完成任务。
追问
- 长任务停机后结果怎么办?答:状态落外部存储,新实例或客户端重连后查询恢复。
- 停机时新会话能建立吗?答:优雅阶段应拒绝新会话,只排空已有调用。
- 资源释放顺序?答:先停后台任务与新连接,再关池,最后释放配置。
04.7.18.3-055 协议流被日志污染如何系统排查?
一句话结论
排查按通道分工展开:确认 stdout 只含协议报文、stderr 承载日志;检查所有 print、第三方库启动横幅、日志处理器去向与标准流重定向。stdio 场景可抓取子进程 stdout 逐行检查是否为合法 JSON;HTTP 场景则检查响应体是否混入非协议文本。定位后把输出改到 stderr 或文件。
概念解释
- 污染源清单:业务 print、库日志、进度条、横幅、调试输出。
- 检查手段:标准流抓包、日志配置审计、第三方库初始化输出。
- 修复方向:所有非协议输出离开 stdout,配置归一化到 stderr。
原理流程
- 复现握手与一次调用,抓取 stdout/响应体。
- 逐行核对协议帧,定位非文本来源模块。
- 修改输出去向,复测协议流干净。
代码或图示
stdout lines -> JSON parse check
bad line -> trace source print/log handler -> redirect to stderr
常见误区
- 只改业务代码,忽略依赖库默认 stdout:库横幅与日志仍污染通道。
- 本地终端看不出通道:需按标准流分别抓取,不能凭控制台混排判断。
追问
- 怎么抓 stdio 子进程输出?答:客户端/调试器分别接管 stdin/stdout/stderr 记录。
- 框架日志默认走哪?答:检查日志处理器配置,必要时显式设为 stderr。
- 污染修复后验证什么?答:完整握手、list、一次工具调用,stdout 无额外文本。
04.7.18.3-056 阻塞调用卡死 transport 的现象与定位方法是什么?
一句话结论
事件循环被同步阻塞调用占住后,stdin/HTTP 读取暂停,后续请求无人处理:ping 超时、工具调用挂起、连接逐渐堆积。定位方法看日志时间线与线程/协程栈,确认是否有同步 IO、CPU 密集计算或锁等待在异步上下文执行;修复为异步驱动、执行器卸载或限制阻塞操作。
概念解释
- 阻塞类型:同步网络 IO、本地文件/计算、阻塞锁、同步库调用。
- 现象:无报错但不响应,健康检查可能通过而业务通道卡死。
- 定位:栈快照、耗时日志、事件循环阻塞监控。
原理流程
- 工具内同步阻塞调用占住事件循环。
- 后续消息无法读取派发,连接挂起。
- 抓栈定位阻塞点,改为异步或卸载线程,补充超时与阻塞监控。
代码或图示
# 问题: 同步阻塞在异步事件循环
# data = requests.get(url).json()
# 修复: 异步客户端
async with httpx.AsyncClient() as client:
resp = await client.get(url)
常见误区
- 把挂起当下游慢:下游有超时返回才是慢,完全不响应且无新日志多为循环阻塞。
- 用后台线程补救但不释放主循环:阻塞点仍占资源,需按并发模型改造。
追问
- 阻塞库必须用怎么办?答:放到线程执行器并设超时,不阻塞事件循环。
- 怎么监控事件循环阻塞?答:记录循环延迟/心跳,配合栈快照定位。
- 同步工具在异步框架里如何调度?答:FastMCP 2.x 把同步函数经线程池卸载执行,阻塞操作建议用
anyio.to_thread.run_sync,避免直接占住事件循环。
04.7.18.3-057 超大响应导致解析或上下文失败如何处理?
一句话结论
超大响应可能撑大报文、截断传输或挤占客户端上下文。服务端应控制结果体积:分页、字段投影、摘要化,大文件/大列表改资源 URI 按需读取;响应设大小阈值并记录超限指标。客户端解析失败时应能区分传输截断与上下文超限,服务端不默认返回全量明细。
概念解释
- 体积风险:JSON 序列化、代理缓冲区、通道报文上限。
- 上下文风险:结果进入客户端模型上下文后挤占后续空间。
- 降级策略:分页、摘要、URI 引用、流式分段返回。
原理流程
- 工具评估结果规模,超阈值走分页/摘要/引用方案。
- 响应只包含决策所需字段,大对象不内嵌。
- 客户端按需读取后续页或资源,错误按截断/超限分类处理。
代码或图示
@mcp.tool
def list_items(page: int = 1, size: int = 20) -> dict:
return {"page": page, "items": repo.page(page, size)}
常见误区
- 工具返回全表大对象:报文与上下文双重失控,模型只能看到截断内容。
- 只在客户端裁剪:服务端已把大数据推到通道,带宽与解析成本无法收回。
追问
- 响应大小上限在哪里设?答:由传输层、反向代理与序列化层按部署限制配置,框架不提供统一硬编码默认上限。
- 大文件怎么给?答:资源 URI 或外部链接,分块读取,不嵌入响应。
- 超限错误怎么返回?答:业务错误提示结果过大,给出分页/引用方式。
04.7.18.3-058 客户端重连丢会话的原因有哪些,如何规避?
一句话结论
丢会话原因:有状态会话存内存且重连漂移到其他实例、空闲超时已回收、无状态模式本不保留上下文、事件存储缺失导致任务事件不补收、代理未正确转发会话标识头。规避按场景选:粘性路由、共享会话/事件存储、无状态自包含设计、保留会话头与超时配置,并验证重连用例。
概念解释
- 状态位置决定可恢复性:内存状态绑定实例,外部存储才可跨实例恢复。
- 头与超时:会话标识未透传或空闲回收过快都会导致续接失败。
- 重连验证:测试断线后重连是否恢复会话与任务事件。
原理流程
- 梳理部署会话模型:有状态/无状态、存储位置。
- 检查代理头透传、超时与事件存储配置。
- 构造断线重连用例验证恢复行为,不满足则调整架构。
代码或图示
reconnect fail -> 实例漂移 / 会话过期 / 无状态 / 头丢失 / 无事件存储
remedy -> 粘性 / 共享存储 / 自包含请求 / 透传头 / 配置存储
常见误区
- 重连后默认会话还在:未验证恢复行为就上线,断线即丢任务。
- 只靠客户端重试:服务端状态不保留时重试只能重新发起,不能续接原会话。
追问
- 如何测试重连续传?答:断开连接后带原会话标识重连,断言会话与事件可恢复。
- 会话过期时间设多长?答:按业务空闲时长配置,兼顾内存回收与体验。
- 多副本无共享存储怎么办?答:启用粘性,或改造为无状态/外部状态方案。
04.7.18.3-059 部署上线前自检清单包含哪些项?
一句话结论
上线前逐项验证:传输握手成功、鉴权拒绝与放行正确、端点路径与代理前缀对齐、会话隔离与重连行为、日志/指标/trace 落地、健康探针可用、限流超时生效、错误响应脱敏、依赖与配置经环境变量注入。清单在测试与预发环境逐项跑通,遗留问题记录验证点并跟踪。
概念解释
- 连通性:握手、list 清单、一次成功调用、一次失败调用。
- 安全:鉴权、scope、脱敏、限流、路径/URI 校验。
- 运行:可观测性、探针、优雅停机、会话与扩展方案。
原理流程
- 按清单构造测试用例覆盖各检查项。
- 在预发环境经代理链路验证,不只本机直连。
- 记录结果与遗留风险项,通过后上线。
代码或图示
握手 -> 清单 -> 成功调用 -> 鉴权拒绝 -> 路径/前缀 -> 会话隔离
日志指标 -> 探针 -> 限流超时 -> 错误脱敏 -> 优雅停机
常见误区
- 只在本机验证:代理前缀、缓冲、超时与头透传问题在真实链路才暴露。
- 跳过失败路径自检:鉴权与错误脱敏问题上线后才被外部触发。
追问
- 自检需要自动化吗?答:核心链路纳入集成测试,部署后做冒烟回归。
- 未核实项怎么处理?答:标注验证点与负责人,未核实不写成对外承诺。
- 回滚预案包含什么?答:版本回退、配置回退与会话/任务状态兜底说明。
04.7.18.3-060 本章常见版本差异与待确认验证点有哪些?
一句话结论
版本敏感点包括:传输 API 与默认端点路径、会话标识头名称、有状态/无状态与 JSON 响应开关、事件存储后端、鉴权校验器类名与参数、测试传输辅助 API、指标与生命周期钩子接口、超时与大小默认值。这些不能凭旧版经验写死,应在目标版本核对文档、类型定义与运行报文后固化结论。
概念解释
- 差异类别:API 命名、默认值、配置开关、支持后端、行为口径。
- 验证路径:迁移说明 → 源码类型定义 → 内存内/ASGI 实跑 → 记录实际报文。
- 标注规则:真正版本敏感且未核实的项标注验证点,核实后移除标注。
原理流程
- 列出影响部署、鉴权、测试与观测的版本敏感点。
- 在当前安装版本逐项核对文档、源码与运行结果。
- 把确定结论写入测试断言,未核实项保留标注并跟踪。
代码或图示
已核实(FastMCP 2.x):
- 传输: run(transport="stdio"|"http"|"sse"), http 默认 127.0.0.1:8000/mcp
- 会话头: Mcp-Session-Id; 无状态: stateless_http=True 或 FASTMCP_STATELESS_HTTP=true
- 校验器: JWTVerifier / StaticTokenVerifier / IntrospectionTokenVerifier / DebugTokenVerifier
- 测试: from fastmcp import Client; Client(mcp) 内存内直连, call_tool / list_tools
- lifespan: 构造器 lifespan= 接异步上下文管理器
保留未核实项:
- EventStore 外部持久化后端与配置参数
- 内置指标导出接口是否存在
- 会话空闲超时参数名与默认值
常见误区
- 照搬其他语言 SDK 或旧版示例:Python 实现命名与默认值可能不同。
- 把未核实假设写进部署文档:未验证行为不应作为上线承诺。
追问
- 如何查当前框架版本?答:
pip show fastmcp查安装版本,对照该版本文档与类型定义。 - 未核实项何时关闭?答:目标版本观察到确定报文并补测试断言后关闭。
- 版本升级要回归什么?答:握手、鉴权、会话、重连、挂载链路与错误路径全量冒烟。
本节高频题
- stdio 通道纪律:stdout 协议流、stderr 日志、print 污染(001、002、003)
- stdio 进程模型、编码分帧、读取循环与并发限制(004、005、006、008)
- Streamable HTTP
/mcp端点与 SSE legacy 双端点(009、010) - JSON/SSE 响应形态、会话标识头、有状态/无状态与事件存储(011、012、013、014)
- 代理缓冲、超时、会话隔离与重连丢会话(015、016、017、018、019)
- 挂载前缀、root_path、CORS 与 TLS(020、021、022)
- Bearer 校验、OAuth 资源服务器、校验器、scope 与会话身份(023、024、025、026、027)
- OAuth 发现元数据、静态令牌注入与鉴权错误分层(028、029、030)
- 容器镜像、启动参数、进程信号与多副本粘性(032、033、034、035)
- 无状态扩展前提、共享存储后端与结构化日志(036、037、038)
- 指标、trace id 与超时预算(039、040、041)
- 内存内测试、结果断言、错误路径与契约快照(042、043、044、045)
- ASGI 链路测试、校验分层与注入防护(046、047、048)
- 限流超时与敏感信息脱敏(049、050)
- 同进程共存、lifespan、探针与优雅停机(051、052、053、054)
- 故障排查:日志污染、阻塞卡死、超大响应与重连(055、056、057、058)
- 部署自检与版本敏感项(059、060)