04.7.18.1 MCP 协议模型与 Server 核心
所属:全栈开发面试题库 / 04 后端语言与运行时 / 04.7 Python / 04.7.18 FastMCP 服务端框架
覆盖范围
- MCP 定位、JSON-RPC 2.0 报文基础与 host/client/server 三角色分工
initialize握手、protocolVersion 协商、能力声明与initialized通知- tools/resources/prompts 三个服务端原语的语义边界与报文形态
- 请求、通知、响应三类消息,progress/cancellation/ping 等通知机制
- stdio、SSE、Streamable HTTP 三种传输的结构差异与会话模型
- FastMCP 实例构造、能力自动声明、
lifespan生命周期与 ASGI 挂载 - JSON-RPC 错误码分层、协议层与业务层错误划分、规范版本演进与版本敏感项
04.7.18.1-001 MCP 解决什么问题,在系统中处于什么位置?
一句话结论
MCP(Model Context Protocol)是一套标准化的“能力暴露协议”:服务端把工具、资源、提示模板等能力按统一报文暴露给客户端,客户端再把这些能力交给上层模型或应用使用。它位于“宿主应用/客户端”与“能力提供方服务端”之间,解决的是不同客户端对接不同后端能力时重复写适配层的问题。
概念解释
- MCP 不是模型调用协议,不规定模型如何推理;它只负责能力清单、参数契约与调用通道。
- 与内部微服务间的 REST/gRPC 调用不同,MCP 客户端通常是模型宿主(桌面端、IDE、聊天应用),服务端是被接入的一方。
- 协议本身与语言无关,Python 实现的服务端可以被其他语言实现的客户端接入。
原理流程
- 宿主应用内运行 MCP Client,通过选定传输连接到一个或多个 MCP Server。
- 握手完成后,Client 拉取 Server 的 tools/resources/prompts 清单与 schema。
- 上层模型或用户决定调用某项能力时,Client 按协议把调用转发给 Server,Server 返回结果。
代码或图示
宿主应用 Host
└─ MCP Client ──stdio / SSE / Streamable HTTP──> MCP Server
├─ tools
├─ resources
└─ prompts
常见误区
- 把 MCP 当成“给模型发请求的 API 网关”:它暴露的是能力契约,模型选择能力的决策发生在客户端一侧。
- 认为 MCP 服务端必须直接连大模型:服务端只执行被调用的函数,模型编排不属于服务端框架职责。
追问
- MCP 与 OpenAPI 的区别?答:OpenAPI 描述 HTTP 接口契约,MCP 是面向能力发现与调用的会话式协议,含资源、提示模板等原语。
- 一个客户端能连多个服务端吗?答:可以,客户端按会话分别连接并合并能力清单。
- 服务端之间会直接互通吗?答:标准模型下不直接互通,由客户端编排;代理桥接属于框架扩展能力。
04.7.18.1-002 MCP 报文为什么建立在 JSON-RPC 2.0 之上?
一句话结论
MCP 的每条消息都是一个 JSON-RPC 2.0 对象:请求带 jsonrpc、id、method、params,响应带 result 或 error,通知不带 id。选用 JSON-RPC 是因为它的“请求-响应-通知”三元模型恰好匹配会话式能力调用,且报文自描述、跨语言易解析。
概念解释
- JSON-RPC 2.0 是无传输绑定的消息格式规范,不规定走 stdio、HTTP 还是其他通道。
method是字符串方法名,如tools/list;params是对象或数组;id用于把异步响应关联回请求。- 通知(notification)没有
id,发送方不等待响应,典型如进度上报、取消通知。
原理流程
- 发送方构造 JSON 对象,写入
jsonrpc: "2.0"与方法名。 - 需要响应的请求分配
id(字符串或数字);通知省略id。 - 接收方处理后按同一
id回result或error;通知不回包。
代码或图示
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/list",
"params": {}
}
常见误区
- 把 HTTP 状态码当成协议错误:HTTP 层只负责传输,业务错误仍要落在 JSON-RPC
error对象里。 - 给通知也分配
id:通知语义上不期待响应,带id会让接收方误判为请求。
追问
- JSON-RPC 2.0 与 1.0 的关键差异?答:2.0 统一了请求/响应/通知结构,错误对象独立,
id可为 null。 params可以省略吗?答:可以,无参数时省略或传空对象{}。- 报文必须是 JSON 吗?答:协议层载荷是 JSON;传输层编码与分帧由各传输规定。
04.7.18.1-003 Host、Client、Server 三个角色如何分工?
一句话结论
Host 是承载用户界面与模型运行环境的宿主应用;Client 是 Host 内部运行的协议客户端,负责与 Server 建会话、转发调用;Server 是能力提供方,注册并执行 tools/resources/prompts。三者中 Host 不直接说协议,Client 才是协议对端。
概念解释
- Host:桌面应用、IDE 插件、聊天客户端等,拥有用户上下文与模型调用入口。
- Client:协议实现侧,维护会话、能力清单、消息 id 关联与通知订阅。
- Server:被连接的一方,不主动选择客户端,只按协议暴露能力并执行调用。
原理流程
- Host 启动时按配置拉起或连接若干 Server。
- Client 与 Server 完成握手并拉取能力清单,交回 Host 展示或供模型选择。
- 调用发生时 Host/模型决策 → Client 发请求 → Server 执行 → 结果沿原路返回。
代码或图示
┌──────────── Host ────────────┐
│ UI / 模型运行环境 / 用户上下文 │
│ ┌──────── Client ────────┐ │
│ │ 会话管理 · 调用转发 · 订阅 │ │
│ └───────────┬───────────┘ │
└───────────────┼──────────────┘
│ 协议消息
┌───────┴───────┐
│ MCP Server │
└───────────────┘
常见误区
- 把 Host 与 Client 混为一谈:Host 是应用进程,Client 是其中的协议组件,一个 Host 可持有多个 Client。
- 认为 Server 能反向决定“哪个模型用我”:Server 只暴露能力与说明,选择权在 Host/Client 一侧。
追问
- 同一 Host 能接入多个 Server 吗?答:可以,每个 Server 对应独立 Client 会话。
- Server 知道 Host 的存在吗?答:协议握手只暴露 Client 侧信息(clientInfo),Host 细节通常不直接可见。
- 角色可以互换吗?答:标准角色固定;代理型服务端在框架扩展下可同时扮演对端客户端。
04.7.18.1-004 MCP 与传统 REST/gRPC 内部服务调用有何不同?
一句话结论
REST/gRPC 是“服务间点对点调用契约”,调用方预先知道接口;MCP 是“会话式能力发现与调用”,服务端先列出能力与 schema,客户端在会话内动态选择并调用。MCP 还包含资源读取、提示模板、进度通知等面向模型交互的原语,这是普通 RPC 没有的。
概念解释
- 发现模型:REST/gRPC 靠文档或 IDL 静态约定;MCP 在
initialize后通过tools/list等方法动态枚举。 - 载荷契约:MCP 工具入参出参用 JSON Schema 描述,客户端可据此生成调用参数。
- 交互形态:MCP 会话内允许服务端主动推送通知(进度、资源更新、日志)。
原理流程
- 传统 RPC:调用方按固定 IDL/接口文档直接发请求,无“先列清单”阶段。
- MCP:先握手 → 拉取清单与 schema → 客户端按 schema 组装参数 → 调用 → 接收通知与结果。
- 能力变更后,客户端下次
list即可感知,无需重新发布调用方代码。
代码或图示
REST/gRPC: client ──已知接口契约──> server
MCP: client ──initialize──> server
client <──清单+schema── server
client ──call(按schema)──> server
常见误区
- 把 MCP 服务端写成又一个 REST 控制器就完事:缺少能力清单、schema 与通知机制,客户端无法动态发现。
- 认为 MCP 调用一定同步阻塞:长任务可配合进度通知与流式响应,调用与推送可以并行。
追问
- MCP 服务端底层能用 HTTP 吗?答:能,Streamable HTTP 就是基于 HTTP 的传输,协议层仍走 JSON-RPC。
- 为什么需要资源与提示模板这类原语?答:它们分别对应“只读数据接入”和“可复用交互模板”,是模型交互场景下的常见需求。
- MCP 替代服务间 RPC 了吗?答:没有,定位不同;内部高频服务调用仍适合 gRPC/REST。
04.7.18.1-005 MCP 连接是单向还是双向,谁可以主动发消息?
一句话结论
MCP 会话是双向的:除了客户端请求、服务端响应这条主链路,服务端也可以在会话内主动发通知(进度、资源变更、日志、取消确认等)。是否允许服务端主动推消息取决于传输能力:stdio 与 Streamable HTTP/SSE 都支持会话内双向,纯一次性请求响应通道不适合承载长会话。
概念解释
- 双向性体现在“会话内消息流”,而不是两条独立业务通道。
- 服务端主动消息通常是通知(无
id),不需要客户端回包;少数方法由服务端反向调用客户端能力(如 sampling、roots),属于跨角色能力协商结果。 - 传输层决定消息如何分帧与投递,协议层不关心底层是管道还是 HTTP。
原理流程
- 握手建立会话后,通道保持打开。
- 客户端发起请求,服务端回结果;服务端在执行过程中可穿插通知。
- 若客户端能力被服务端使用,服务端可按已协商能力反向发请求给客户端。
代码或图示
Client ──request──> Server
Client <──result── Server
Client <──notification(progress/log/updated)── Server
Client <──request(sampling/roots, 若已协商)── Server
常见误区
- 以为服务端只能被动应答:进度上报、资源订阅更新都是服务端主动推送。
- 在无状态 HTTP 模式下假设服务端能随时推消息:无状态模式下主动推送能力受限,需结合事件存储与重连机制。
追问
- 服务端能调用客户端的模型能力吗?答:在客户端声明 sampling 能力后可以,这是客户端能力,不是服务端能力。
- 通知需要重试吗?答:通知语义为尽力投递,可靠语义需由传输层或上层补偿。
- 双向流在 stdio 下如何体现?答:stdin 收请求,stdout 发响应与通知,两条管道构成双向通道。
04.7.18.1-006 initialize 握手的报文结构与协商内容是什么?
一句话结论
initialize 是会话第一条请求:客户端在 params 里带上 protocolVersion、自身 capabilities 与 clientInfo;服务端回 protocolVersion、自身 capabilities、serverInfo,并可附 instructions。握手完成后客户端再发 initialized 通知,正式进入能力调用阶段。
概念解释
protocolVersion:双方协商使用的规范版本,服务端返回其实际采用的版本。capabilities:各自声明支持的方法族,如服务端的 tools/resources/prompts,客户端的 roots/sampling。clientInfo/serverInfo:名称与版本等标识信息,用于日志、排查与客户端 UI 展示。
原理流程
- 客户端发送
initialize请求,带期望协议版本、能力与身份信息。 - 服务端校验版本与能力,返回协商后的版本、服务端能力、服务端身份与使用说明。
- 客户端发送
notifications/initialized通知,握手结束;此后才能调用业务方法。
代码或图示
{
"jsonrpc": "2.0",
"id": 0,
"method": "initialize",
"params": {
"protocolVersion": "2025-06-18",
"capabilities": {},
"clientInfo": {"name": "demo-client", "version": "1.0.0"}
}
}
常见误区
- 握手未完成就调用
tools/list:协议要求先收到 initialize 响应并发出 initialized 通知,早期调用会被拒绝。 - 把
instructions当成工具说明:它是服务端整体使用指引,面向客户端理解“如何使用本服务”。
追问
- initialize 响应里的 instructions 给谁看?答:通常交给客户端模型作为系统级使用说明。
- 握手阶段会注册工具吗?答:注册发生在服务端构造/启动期;握手只做能力与身份协商。
- 协议版本号字符串以哪份规范为准?答:规范已发布版本标识如
2025-06-18、2025-11-25;服务端返回其实际采用的版本,SDK 常量以所装 Python SDK 为准。
04.7.18.1-007 protocolVersion 如何协商,版本不兼容怎么办?
一句话结论
客户端在 initialize 中给出期望版本,服务端返回它支持的版本;双方以服务端返回值为准继续会话。若版本差距过大导致方法或字段不兼容,接收方应按协议错误拒绝或降级处理,而不是静默忽略未知字段。跨版本接入时对照当前 MCP 规范变更记录与所装 SDK 发布说明即可。
概念解释
- 协商是“客户端提议、服务端裁定”:服务端选择自己能支持的版本返回。
- 未知字段按前向兼容原则忽略;未知方法则返回方法不存在错误。
- 跨版本接入时,旧客户端可能不认识新服务端能力,新客户端也可能遇到旧服务端缺方法。
原理流程
- 客户端携带
protocolVersion发起 initialize。 - 服务端比对支持列表,返回协商版本与自身能力。
- 后续方法调用按协商版本的报文形态进行;遇到不支持的方法走错误分支。
代码或图示
client: protocolVersion = "X"
server: 支持 X 与 Y,返回 Y
双方按 Y 的报文约定通信
常见误区
- 认为客户端版本号一定被采纳:最终版本以服务端返回为准。
- 用 SDK 包版本号代替协议版本:SDK 版本是实现版本,
protocolVersion是规范版本,两者不相等。
追问
- 服务端不支持客户端期望版本时怎么办?答:返回可协商版本或协议错误,由客户端决定是否降级连接。
- 如何排查版本不兼容?答:核对双方 initialize 报文里的 protocolVersion、能力字段与方法名,再对照规范变更记录。
- 未知参数字段会报错吗?答:通常按兼容原则忽略;强制严格校验由
strict_input_validation配置控制。
04.7.18.1-008 能力声明(capabilities)在 initialize 中起什么作用?
一句话结论
能力声明告诉对端“这一侧支持哪些方法族与扩展行为”:服务端声明 tools、resources、prompts、logging、completions 等,客户端声明 roots、sampling 等。未声明的能力,对端不应依赖;客户端据此决定是否展示资源订阅、是否请求采样等功能。
概念解释
- 能力是粗粒度开关:例如服务端声明
tools能力,客户端才会发起tools/list与tools/call。 - 能力对象内还可带子标志:
resources下有subscribe、listChanged,tools/prompts下有listChanged。 - 能力声明与组件实际注册情况应一致:声明了能力就应提供对应方法。
原理流程
- 服务端构造实例时按已注册组件与内置能力汇总 capabilities。
- initialize 响应把 capabilities 交给客户端。
- 客户端只对已协商能力发起调用;服务端收到未声明方法时按未知方法处理。
代码或图示
{
"capabilities": {
"tools": {},
"resources": {"subscribe": true},
"prompts": {}
}
}
常见误区
- 能力声明写全量、实际方法缺失:客户端尝试调用后失败,体验比不声明更差。
- 把工具数量写进 capabilities:能力只描述方法族,具体组件清单走
tools/list等枚举方法。
追问
- 服务端能力由谁生成?答:FastMCP 2.x 按注册的工具/资源/提示自动汇总;未注册对应组件即不声明该能力族。
- 客户端能力对服务端有什么用?答:服务端据此判断能否反向请求 roots 列表或 sampling 补全。
- 能力可以在会话中变更吗?答:标准会话内能力以握手结果为准;动态增减组件通过列表变更通知反映。
04.7.18.1-009 serverInfo 与 instructions 分别上报什么信息?
一句话结论
serverInfo 上报服务端身份标识:名称与版本,用于客户端 UI 展示、日志与排查;instructions 是一段面向使用方的说明文字,告诉客户端/模型这个服务端提供什么、如何调用各项能力。两者都在 initialize 响应中返回。
概念解释
serverInfo.name:服务端可读名称,FastMCP 2.x 未显式传name时默认值为"FastMCP"。serverInfo.version:服务端自身版本;FastMCP 2.x 未传version时回退为 FastMCP 库自身版本号,不等于产品版本。instructions:自然语言指引,不等同于单个工具的 description。
原理流程
- 构造服务端实例时传入 name、version、instructions 等参数。
- initialize 响应把这些字段组装进
serverInfo与instructions。 - 客户端把名称展示在连接列表,把 instructions 并入模型可用上下文。
代码或图示
from fastmcp import FastMCP
mcp = FastMCP(
name="analytics-server",
version="1.2.0",
instructions="提供指标查询与报表生成工具,调用前先确认时间范围参数。",
)
常见误区
- 把详细操作手册塞进 instructions:过长会占用客户端上下文,工具级细节应放在各工具 description。
- 依赖 version 自动等于依赖库版本:服务端版本是产品版本,应显式传入。
追问
- instructions 会被发给模型吗?答:通常由客户端并入模型上下文,具体展示策略取决于客户端。
- serverInfo.name 冲突影响什么?答:影响客户端列表识别与日志定位,多服务端接入时应保持唯一可读名称。
- 名称里能放环境标识吗?答:可以,如
analytics-server-prod,但避免放入敏感信息。
04.7.18.1-010 initialized 通知在握手流程中的位置是什么?
一句话结论
initialized(notifications/initialized)是客户端在收到 initialize 响应后发出的空通知,标志握手完成、双方可以进入业务调用。它不带 id、不需要服务端响应;服务端在收到该通知前不应假定客户端已就绪。
概念解释
- 顺序固定:
initialize请求 → 服务端响应 →initialized通知 → 业务方法。 - 通知本身不携带能力数据,能力协商结果已在 initialize 响应中确定。
- 框架在客户端会话层自动发送该通知,手写客户端时不能漏掉。
原理流程
- 客户端发 initialize,等待服务端响应。
- 客户端解析响应、记录协商版本与能力。
- 客户端发出 initialized 通知;此后发起
tools/list等业务调用。
代码或图示
{
"jsonrpc": "2.0",
"method": "notifications/initialized"
}
常见误区
- 在 initialize 响应后立即调用业务方法:漏掉 initialized 阶段,部分服务端实现会拒绝未完成握手的请求。
- 把 initialized 当请求等待响应:它是通知,无
id也不回包。
追问
- 服务端需要回 initialized 吗?答:不需要,该通知由客户端单向发出。
- 握手阶段出错会发 initialized 吗?答:不会,版本或能力协商失败应在 initialize 错误分支处理。
- 框架会自动处理这一步吗?答:客户端 SDK 通常在会话建立时自动完成,服务端侧无需手动发送。
04.7.18.1-011 一次成功握手后服务端处于什么会话状态?
一句话结论
握手成功后服务端为该连接建立独立会话:持有协商版本、双方能力、客户端身份与会话级上下文,后续消息都在该会话内路由。会话状态是否落盘、能否跨进程恢复,取决于传输模式(有状态/无状态)与框架实现。
概念解释
- 会话是协议层概念,不等于 HTTP 连接;同一传输连接上可能复用或重建会话。
- 会话上下文可存放认证结果、客户端标识、请求级缓存等;不同会话之间隔离。
- 会话结束(断开、超时、错误)后,会话内临时状态随之释放。
原理流程
- initialize 响应生成会话记录,写入协商版本与能力。
- 业务请求进入时按会话标识路由到对应上下文。
- 连接关闭或会话超时时清理会话资源;有状态模式下会话与事件保存在服务端内存,重连带回会话标识后可恢复,持久化跨进程恢复需外部存储支持。
代码或图示
session:
protocol_version: 2025-06-18
capabilities: {tools, resources, prompts}
client: {name, version}
auth: <认证结果或空>
常见误区
- 把服务端全局单例状态当成会话状态:模块级变量会被所有会话共享,不能存请求级身份。
- 认为握手后能力还能随意声明变更:会话内能力以握手结果为准,组件增减通过列表通知反映。
追问
- 会话标识在哪里传递?答:HTTP 传输通过
Mcp-Session-Id头携带;stdio 下一个进程对应一个会话,无需会话头。 - 会话超时由谁判定?答:传输层与框架按空闲超时判定,具体时长以配置为准。
- 多客户端并发会互相覆盖会话吗?答:按会话隔离不会;误用全局变量才会串扰。
04.7.18.1-012 客户端能力与服务端能力如何区分?
一句话结论
能力按角色分:服务端能力是“我能提供什么”,如 tools、resources、prompts、logging、completions;客户端能力是“我能配合什么”,如 roots(提供本地/项目根目录列表)、sampling(代发模型补全请求)。服务端只能使用客户端在握手时声明过的能力。
概念解释
- roots:客户端向服务端暴露可访问的文件根或项目列表,服务端读取时反向请求客户端。
- sampling:服务端在执行工具过程中请求客户端调用其模型生成文本,结果回传服务端。
- 能力是可选协商项;未声明即视为不支持,服务端不应尝试反向调用。
原理流程
- 客户端在 initialize 的
capabilities中声明 roots/sampling 等。 - 服务端记录客户端能力清单。
- 需要反向协作时,服务端按已声明能力发请求;客户端未声明则跳过该路径。
代码或图示
{
"clientCapabilities": {
"roots": {"listChanged": true},
"sampling": {}
}
}
常见误区
- 服务端默认客户端一定支持文件访问:roots 是可选能力,未声明时不能假设可读本地路径。
- 在服务端框架里直接实现模型调用去代替 sampling:sampling 走客户端模型,服务端本地直连模型属于另一套架构选择。
追问
- 服务端日志能力属于哪一侧?答:属于服务端能力,服务端通过日志通知把日志推给客户端展示。
- 客户端能力未声明时服务端如何降级?答:跳过反向协作功能,返回不支持或使用本地默认路径。
- 能力字段的子标志有哪些?答:
resources.subscribe、resources.listChanged、tools.listChanged、prompts.listChanged。
04.7.18.1-013 tools 原语的语义边界是什么?
一句话结论
tools 对应“可执行的动作或计算”:有明确入参 schema、执行函数、返回结果,允许产生外部副作用(写库、调 API、发消息)。凡是需要客户端触发一次操作、拿到执行结果的能力,都应注册为工具。
概念解释
- 工具是主动调用型组件:客户端通过
tools/call触发,服务端执行后返回内容块或结构化结果。 - 工具适合计算、检索后处理、外部系统写入等;纯静态数据读取优先考虑资源。
- 工具内部可包含业务校验、权限判断与错误处理,异常转换为协议错误返回。
原理流程
- 函数经装饰器注册为工具,签名推导出入参 schema 与工具描述。
tools/list把工具名、描述、输入 schema 交给客户端。- 客户端
tools/call传入参数,服务端校验后执行函数并返回结果。
代码或图示
@mcp.tool
def create_ticket(title: str, priority: str) -> dict:
"""创建一个工单并返回工单号。"""
return {"ticket_id": "T-1024", "title": title, "priority": priority}
常见误区
- 把无副作用的静态查询也做成工具:资源更贴合“只读数据接入”,清单更小、调用语义更清晰。
- 工具函数里做长时间无反馈的阻塞操作:应配合进度上报与取消信号,避免客户端长时间等待。
追问
- 工具必须有副作用吗?答:不必须,纯计算工具也常见;边界是“它是一次主动执行的动作”。
- 工具能返回文件吗?答:可以以二进制或媒体内容块形式返回,具体内容块形态见 Schema 主题页。
- 一个工具能调用多个下游系统吗?答:可以,但要控制职责粒度,避免单工具承载过多分支。
04.7.18.1-014 resources 原语的语义边界是什么?
一句话结论
resources 对应“可被读取的只读数据”:以 URI 标识,客户端通过 resources/read 取内容,语义接近 HTTP GET,原则上不产生写入副作用。配置项、文档片段、记录详情、文件内容等适合暴露为资源。
概念解释
- 资源由 URI 定位,静态资源是固定 URI,模板资源用
{占位符}动态匹配。 - 资源返回内容带 MIME 类型与编码信息,客户端据此判断是文本、JSON、图片还是其他二进制。
- 资源可被订阅:数据变化时服务端通过更新通知推送给已订阅客户端。
原理流程
- 资源函数绑定 URI(静态或模板),声明返回类型与 MIME 类型。
resources/list列出静态资源与可用模板。- 客户端按 URI 发起
resources/read,服务端返回内容块;订阅后变化时推送更新通知。
代码或图示
@mcp.resource("config://app-version")
def app_version() -> str:
"""返回当前应用版本号。"""
return "1.2.0"
常见误区
- 用资源执行写操作:资源语义是只读,写入类动作应归工具。
- 把资源 URI 当数据库主键直接拼 SQL:URI 参数仍需校验与白名单约束,见安全主题页。
追问
- 资源和工具查询接口怎么选?答:数据读取、可被重复引用选资源;需要计算、转换或触发动作选工具。
- 资源能返回结构化 JSON 吗?答:可以,按 MIME 类型标注为 JSON 内容。
- 资源必须长期存在吗?答:可以是临时计算结果,但读取过程应保持只读语义。
04.7.18.1-015 prompts 原语的语义边界是什么?
一句话结论
prompts 对应“可复用的交互模板”:把一段或多轮消息组织成模板,带可选参数,客户端通过 prompts/get 取出后交给模型作为对话起点。提示模板不执行动作、不提供数据,只定义“怎么问、按什么角色和上下文问”。
概念解释
- 提示模板是客户端可列举、可填充参数的消息序列,返回 user/assistant 角色消息。
- 适合固化排查话术、评审模板、多轮引导等重复交互模式。
- 参数可配补全建议(completion),辅助客户端填充取值。
原理流程
- 提示函数经装饰器注册,参数即模板入参,返回字符串或消息对象列表。
prompts/list列出提示名、描述与参数 schema。- 客户端
prompts/get填入参数,拿到消息序列并入对话上下文。
代码或图示
@mcp.prompt
def code_review(code_snippet: str) -> str:
"""生成一段代码评审请求。"""
return f"请评审以下代码的缺陷与风格问题:\n```python\n{code_snippet}\n```"
常见误区
- 在提示模板里塞业务逻辑或外部调用:模板只组装文本,动作交给工具。
- 把提示模板当成系统提示词下发机制:它是可被客户端列举和调用的模板,不等同于全局系统提示。
追问
- 提示模板能返回多轮消息吗?答:可以,返回 user/assistant 消息列表,组织多轮对话起点。
- 提示参数必填还是可选?答:由函数签名与默认值决定,schema 中体现为必填或可选。
- 提示模板与工具描述的区别?答:工具描述说明“这个动作怎么调”,提示模板定义“对话怎么开始”。
04.7.18.1-016 工具、资源、提示在副作用与只读性上有何区别?
一句话结论
工具允许副作用与计算,返回执行结果;资源是只读数据读取,不承诺写入;提示是纯文本模板组装,既不读实时数据也不产生副作用。选型时先问“这是动作、数据还是话术”,再落到对应原语。
概念解释
- 副作用边界:工具可写库、调外部 API;资源重复读取应得到一致或可解释的结果。
- 数据来源:资源可返回服务端持有数据;提示模板只做参数填充,不主动取数。
- 三者可组合:提示模板引导用户调用工具,工具结果可被资源引用展示。
原理流程
- 判断能力本质:触发动作 → 工具;读取数据 → 资源;组织话术 → 提示。
- 在对应原语下注册函数并补齐描述与 schema。
- 客户端按清单选择,调用语义与原语边界保持一致。
代码或图示
动作/计算/写入 -> tool(tools/call)
只读数据/URI -> resource(resources/read)
消息模板/参数 -> prompt(prompts/get)
常见误区
- 同一能力既挂工具又挂资源导致语义重复:客户端看到两套入口,参数与结果难以对齐。
- 把重计算结果放进提示模板:模板应保持轻量,重计算走工具,结果再交给提示使用。
追问
- 查询类接口放哪一类?答:只读、可重复引用放资源;需要聚合计算或触发流程放工具。
- 三类组件在清单里会混在一起吗?答:协议分方法族列举,客户端 UI 通常分组展示。
- 边界模糊时如何取舍?答:以客户端调用语义为准——动作入口用工具,数据入口用资源。
04.7.18.1-017 tools/list 返回哪些元数据,schema 在什么位置?
一句话结论
tools/list 响应的 tools 数组中,每项至少包含 name、description 与输入参数的 JSON Schema(inputSchema);还可附 title、annotations、outputSchema 等可选元信息。客户端依据 inputSchema 组装调用参数。
概念解释
name:工具唯一标识,调用时使用。description:来自 docstring 或装饰器显式描述,帮助模型理解用途。inputSchema:JSON Schema 对象,含类型、属性、必填项与约束说明。
原理流程
- 框架在注册时解析函数签名与类型注解,生成输入 schema。
tools/list遍历已注册工具,组装元数据数组。- 客户端读取 schema 生成参数提示或校验用户/模型填参。
代码或图示
{
"tools": [
{
"name": "add",
"description": "两个整数相加。",
"inputSchema": {
"type": "object",
"properties": {"a": {"type": "integer"}, "b": {"type": "integer"}},
"required": ["a", "b"]
}
}
]
}
常见误区
- 认为
tools/list会执行工具:它只返回清单与契约,不触发函数体。 - 忽略输出 schema:出参形态若有强约束,可用装饰器
output_schema=声明,便于客户端校验结果。
追问
- 工具描述从哪里来?答:默认取函数 docstring,也可在装饰器参数中显式覆盖。
- 清单顺序可控吗?答:FastMCP 2.x 按内部清单注册顺序输出,跨版本不承诺自定义排序键。
- 重名工具怎么处理?答:框架按重复注册策略报错、告警或替换,默认策略见 Schema 主题页。
04.7.18.1-018 tools/call 的入参与返回结果报文形态是什么?
一句话结论
tools/call 请求 params 含工具名与 arguments 对象;响应 result 含 content 内容块数组,并可用 structuredContent 携带返回对象。内容块分文本、结构化、二进制/媒体等类型;调用失败走 JSON-RPC error;工具级业务失败也可在结果中以 isError: true 标记。
概念解释
arguments:键值对,键对应函数参数名,值按输入 schema 校验。content:面向客户端展示的内容块列表,文本块含type: "text"与text字段。- 结构化返回:框架把 dict/Pydantic 模型序列化为可被客户端读取的结构,不必全部塞进纯文本。
原理流程
- 客户端按工具名与 schema 组装 arguments。
- 服务端校验参数、执行函数,把返回值转换为内容块与结构化结果。
- 响应回传 content 数组;异常被捕获后转为协议错误或错误内容。
代码或图示
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {"name": "add", "arguments": {"a": 1, "b": 2}}
}
常见误区
- 把所有返回都序列化成一大段字符串:结构化对象应保留字段结构,便于客户端二次处理。
- 工具内未捕获异常导致连接中断:应在框架边界转换为错误响应,避免裸异常冒泡到传输层。
追问
- 一次调用能返回多个内容块吗?答:可以,content 是数组,可混合文本与媒体块。
- arguments 缺必填参数会怎样?答:参数校验失败,按无效参数错误返回。
- 工具返回 None 怎么处理?答:FastMCP 2.x 返回空响应,
content为空列表。
04.7.18.1-019 resources/list 与资源模板如何区分?
一句话结论
resources/list 列出静态资源,每项带固定 URI 与 MIME 类型;参数化模板通过资源模板清单单独暴露,URI 中含 {占位符},客户端按模板构造具体 URI 后再读取。两者在协议上分属不同清单方法:模板通过 resources/templates/list 枚举,结果字段为 resourceTemplates。
概念解释
- 静态资源:URI 固定,如
config://version。 - 模板资源:URI 含占位符,如
users://{user_id}/profile,占位符与函数参数绑定。 - 客户端先看模板清单理解可用维度,再拼接具体 URI 请求读取。
原理流程
- 注册静态资源与模板资源。
- 静态资源进入
resources/list;模板进入模板枚举清单。 - 客户端按模板填占位符,生成具体 URI 发起
resources/read。
代码或图示
@mcp.resource("users://{user_id}/profile")
def get_profile(user_id: str) -> dict:
"""按用户 ID 读取档案。"""
return {"user_id": user_id, "status": "active"}
常见误区
- 把模板占位符当成普通查询参数:它出现在 URI 路径段,匹配规则按模板语法解析。
- 清单里只列静态资源漏掉模板:客户端无法发现可按维度查询的数据入口。
追问
- 模板占位符有类型约束吗?答:由函数参数类型注解与校验规则约束,生成对应 JSON Schema 约束。
- 一个模板能有多个占位符吗?答:可以,按模板语法依次绑定函数参数。
- 资源 URI 方案名可以自定义吗?答:使用自定义 scheme 需保证服务端内部可解析并做好校验。
04.7.18.1-020 resources/read 报文与内容块形态是什么?
一句话结论
resources/read 请求 params 带 uri;响应 result 含 contents 数组,每项描述一个资源内容:URI、MIME 类型、文本内容或二进制编码(如 base64)。文本与二进制按内容类型区分,客户端据此解码展示。
概念解释
- 文本内容:直接携带文本字段;二进制内容按约定编码传输并标注 MIME 类型。
- 一个资源可返回多个内容块;JSON 资源可用对应 MIME 标注。
- URI 非法或资源不存在时返回错误,不返回空内容冒充成功。
原理流程
- 客户端构造具体 URI 发起 read 请求。
- 服务端匹配静态资源或模板,校验 URI 与参数。
- 读取数据并包装为 contents 条目返回;失败走资源不存在或参数错误分支。
代码或图示
{
"jsonrpc": "2.0",
"id": 3,
"method": "resources/read",
"params": {"uri": "users://123/profile"}
}
常见误区
- 二进制不标注编码直接塞文本:客户端无法解码,应按协议二进制内容形态返回。
- 资源读取不做存在性判断:缺失资源应返回明确错误,便于客户端区分“无数据”与“URI 错误”。
追问
- 资源内容会被缓存吗?答:协议不强制缓存;是否缓存由客户端决定,服务端可在资源元信息中标注
lastModified等更新语义。 - 大文件如何通过资源返回?答:需考虑分片或大小上限,直接返回超大内容可能撑爆客户端上下文。
- MIME 类型由谁指定?答:注册资源时用
mime_type=显式声明;未声明时 FastMCP 按返回类型推断:str 为text/plain,dict/list/模型为application/json,bytes 为二进制 blob。
04.7.18.1-021 resources/subscribe 订阅通知的语义与适用场景是什么?
一句话结论
客户端对某个资源 URI 发起订阅后,服务端在该资源内容变化时推送资源更新通知,避免客户端反复轮询。订阅是可选能力:服务端在能力声明中未提供订阅时,客户端只能主动 read。
概念解释
- 订阅按 URI 建立,静态资源与模板匹配出的具体 URI 都可作为订阅目标。
- 服务端在数据变更时机主动发
notifications/resources/updated通知,params携带变更后的uri。 - 取消订阅解除推送关系,会话结束时订阅随之失效。
原理流程
- 客户端先 read 确认资源存在,再发起订阅请求。
- 服务端记录订阅关系,纳入会话上下文。
- 数据变化时服务端推送更新通知;客户端取消订阅或会话关闭时清理关系。
代码或图示
client -> server: resources/subscribe {uri}
server -> client: notifications/resources/updated {uri}
(会话结束时订阅随之释放)
常见误区
- 假设所有资源都可订阅:订阅取决于服务端能力与资源实现,不支持时应降级为定时读取。
- 在无状态 HTTP 模式下依赖长连接推送:无状态模式主动推送受限,需结合重连与事件存储。
追问
- 订阅状态存在哪里?答:随会话上下文保存,会话结束即释放。
- 资源高频变更适合订阅吗?答:频繁更新会产生大量通知,需评估推送频率与客户端承受能力。
- 订阅通知需要响应吗?答:通知不回包;订阅/退订请求本身是普通请求,有响应。
04.7.18.1-022 prompts/list 与 prompts/get 的参数化消息模板形态是什么?
一句话结论
prompts/list 列出提示名、描述与参数 schema;prompts/get 按提示名与参数取值返回消息序列。参数在 list 的 schema 中声明,get 时按名传入;返回消息带角色(user/assistant)与内容块。
概念解释
- 提示参数与工具参数类似,由函数签名推导 schema,区分必填与可选。
- 返回消息可以是单条 user 消息,也可以是多轮 user/assistant 序列。
- 提示模板不执行外部动作,参数缺失时按默认值或校验错误处理。
原理流程
- 注册提示函数,装饰器收集名称、docstring 与参数签名。
- list 把参数 schema 交给客户端;客户端展示可填充字段。
- get 传入参数,服务端填充模板并返回消息列表。
代码或图示
{
"method": "prompts/get",
"params": {"name": "code_review", "arguments": {"code_snippet": "def add(a, b): return a + b"}}
}
常见误区
- 提示参数不做校验:非法取值应在模板函数内或 schema 层拦截,避免拼出无意义文本。
- 把提示返回当成工具结果展示:它是对话消息,进入的是模型上下文而非执行结果区。
追问
- 提示参数能给取值建议吗?答:可配合 completion 能力提供补全建议(待确认:验证点:completion 接入方式)。
- 一个提示能返回多条 assistant 消息吗?答:可以按多轮序列组织,角色与顺序由返回结构决定。
- 提示名冲突如何处理?答:FastMCP 2.x 提示重复策略默认
"replace",可在构造器on_duplicate_prompts=配置。
04.7.18.1-023 普通请求、通知、响应三类消息的字段差异是什么?
一句话结论
请求有 id、method、params;通知只有 method、params,无 id;响应有 id 与 result 或 error,无 method。三类消息都带 jsonrpc: "2.0"。按字段即可判断消息类型与是否需要回包。
概念解释
- 请求:期待响应,
id用于关联;方法名标识要调用的能力。 - 通知:单向事件,发送方不等待响应,常用于进度、日志、变更告知。
- 响应:与请求一一对应,成功带
result,失败带error。
原理流程
- 发送方按是否需要响应决定带不带
id。 - 接收方按字段集合识别类型:有 method 无 id 为通知,有 result/error 为响应。
- 响应
id必须与请求id一致,便于异步多路复用下关联。
代码或图示
request: {jsonrpc, id, method, params}
notify: {jsonrpc, method, params}
response: {jsonrpc, id, result} | {jsonrpc, id, error}
常见误区
- 通知里塞
id等待回包:违背通知语义,接收方可能忽略该字段。 - 响应忘记回填
id:异步通道下客户端无法把结果关联回原请求。
追问
params可以是数组吗?答:JSON-RPC 允许对象或数组,MCP 各方法均使用对象参数。- 响应能同时带 result 和 error 吗?答:不能,二者互斥。
- 通知需要重试保证送达吗?答:协议层不保证,可靠投递需上层补偿。
04.7.18.1-024 请求 id 的作用、类型与错误响应中的 id 回填规则是什么?
一句话结论
id 把异步响应关联回请求,类型为字符串或数字;服务端响应必须原样回填请求 id。若请求本身无法解析、拿不到 id,错误响应的 id 按 JSON-RPC 2.0 规则置空。通知没有 id,也不产生带 id 的响应。
概念解释
- 多路复用:同一通道上多个请求并行,靠
id区分结果归属。 - id 由发送方分配,服务端不重新生成;同一会话内建议唯一。
- 解析级错误(报文不是合法 JSON)无法确定 id,响应 id 为 null。
原理流程
- 客户端为每个请求分配唯一 id 并记录待响应表。
- 服务端处理后在响应中带回同一 id。
- 客户端按 id 查表完成回调;解析失败类错误按 null id 返回。
代码或图示
{"jsonrpc": "2.0", "id": "req-7", "method": "tools/call", "params": {}}
常见误区
- 服务端自增 id 覆盖客户端 id:会破坏客户端关联。
- 用时间戳当 id 却不保证唯一:并发下可能撞号,建议带序号或 UUID。
追问
- id 可以是浮点数吗?答:JSON-RPC 允许数字,但工程上常用整数或字符串避免精度问题。
- 通知触发的错误怎么标识?答:通知无 id,相关错误通常以日志或后续请求错误体现。
- 响应 id 类型必须一致吗?答:应保持与请求一致,避免字符串与数字混用导致匹配失败。
04.7.18.1-025 错误对象 error 的 code/message/data 结构是什么?
一句话结论
协议错误对象含 code(数字错误码)、message(可读描述)与可选 data(补充细节,如校验字段、内部错误标识)。错误挂在响应的 error 字段,与 result 互斥;data 用于结构化细节,不替代 message 的可读说明。
概念解释
code:区分错误类别,标准码段与自定义码段见错误码分层题。message:面向排查的简短描述,避免泄露内部敏感信息。data:可选载荷,如参数名、校验失败原因、错误子类型。
原理流程
- 服务端在参数校验、方法分发、业务执行各层捕获异常。
- 按错误类别映射到错误码与 message,必要时附 data。
- 响应以
error返回;传输层异常另按 HTTP/通道状态处理。
代码或图示
{
"jsonrpc": "2.0",
"id": 4,
"error": {
"code": -32602,
"message": "Invalid arguments",
"data": {"field": "user_id", "reason": "must be integer"}
}
}
常见误区
- 把堆栈跟踪直接写进 message 对外返回:既泄露内部细节,也可能含敏感信息。
- 业务失败也用通用内部错误码:应区分参数错误、未找到、冲突等类别,便于客户端分支处理。
追问
- data 里能放原始异常对象吗?答:不建议,应转成可序列化的安全字段。
- 错误码负数区间如何划分?答:标准保留段与实现自定义段见错误码分层题。
- 客户端如何区分协议错误与业务失败?答:看错误码类别与 data 子类型;具体约定需在服务端文档中说明。
04.7.18.1-026 completion(参数补全)能力与提示参数是什么关系?
一句话结论
completion 是服务端可选能力:为提示或资源参数提供取值建议(如枚举选项、前缀匹配结果),客户端在用户填写参数时请求补全。它只给候选值,不替代参数校验;参数是否支持补全由服务端在定义时标注。
概念解释
- 补全请求按参数引用与当前输入前缀查询候选列表。
- 典型场景:限定枚举的分类、可搜索的项目名、已知 ID 列表。
- 补全候选应控制数量,避免一次性返回超长清单。
原理流程
- 客户端在提示/资源参数旁展示输入框,需要候选时发 completion 请求。
- 服务端按参数名与前缀过滤候选,返回建议列表。
- 用户选定后取值作为正式参数提交,仍走正常校验。
代码或图示
client -> server: completion/complete {ref, argument, prefix}
server -> client: {values: ["open", "closed"], total: 2}
常见误区
- 把补全候选当成白名单强约束:补全只是建议,服务端仍需对最终入参校验。
- 补全接口返回全量数据:应按前缀分页或限量返回。
追问
- 工具参数支持补全吗?答:completion 面向 prompts/resources 参数;工具入参取值约束靠 schema 枚举(
enum)表达。 - 补全失败会阻断调用吗?答:不会,建议缺失时用户仍可手动输入。
- 候选值需要翻译或分组吗?答:按客户端展示需要决定,协议只承载值与数量信息。
04.7.18.1-027 日志通知 logging/setLevel 与客户端日志展示是什么关系?
一句话结论
服务端可通过日志通知把运行日志推给客户端展示;客户端可通过 logging/setLevel 告知服务端关注的日志级别,降低低级别噪声。日志通知是服务端主动推送的单向消息,不期待客户端回包。
概念解释
- 级别常见为 debug/info/warning/error,按 MCP 日志级别枚举取值。
- 服务端日志进入客户端 UI 便于排查本地接入问题;生产环境仍应落自己的结构化日志。
- 日志内容不得包含密钥、令牌等敏感信息。
原理流程
- 客户端连接后按需发送 setLevel 设置级别。
- 服务端在执行工具/资源过程中按级别记录并推送日志通知。
- 客户端展示或忽略对应级别消息。
代码或图示
client -> server: logging/setLevel {level: "info"}
server -> client: notifications/logging {level: "info", data: "tool add finished"}
常见误区
- 把服务端应用日志全部走协议通知:量大且受通道限制,应用日志应写本地日志系统,协议通知只放对接排查所需信息。
- 在日志通知里打印完整请求参数:可能含个人信息或凭据。
追问
- 日志级别不设置时默认行为是什么?答:FastMCP 2.x 全局日志级别默认为 INFO,可经
fastmcp.settings.log_level调整。 - 服务端能读客户端日志吗?答:不能,日志通知方向是服务端到客户端。
- 日志通知与进度通知如何区分?答:日志是事件记录,进度是任务完成度,方法名与载荷不同。
04.7.18.1-028 通知类消息为什么不带 id,是否需要响应?
一句话结论
通知表示“事件告知”,发送方不等待处理结果,因此省略 id,接收方也不回响应。进度、日志、资源更新、取消确认等都走通知;需要确认是否执行成功的操作必须用带 id 的请求。
概念解释
- 无 id 意味着无法也无需关联响应;通知丢失不会自动重发。
- 通知与请求可在同一通道交错出现,接收方按方法名分发。
- 重要操作不能只靠通知宣告完成,必须有请求响应或结果确认。
原理流程
- 发送方判断:需要结果 → 请求;仅告知事件 → 通知。
- 通知构造不含 id,直接发出。
- 接收方处理事件,不生成响应消息。
代码或图示
{"jsonrpc": "2.0", "method": "notifications/progress", "params": {}}
常见误区
- 用通知触发写操作并假定成功:没有响应就无法确认执行结果。
- 给通知补 id 后等待超时:接收方不会回包,等待方会一直挂起。
追问
- 通知顺序有保证吗?答:同一通道内通常按发送顺序到达,跨通道不保证。
- 通知携带的 params 结构固定吗?答:按方法类型约定,见各通知方法说明。
- 客户端会收到服务端通知吗?答:会,服务端是通知发送方之一;客户端也可发通知(如取消、initialized)。
04.7.18.1-029 progress 进度上报机制与 progress token 来源是什么?
一句话结论
长任务执行中,服务端按阶段向客户端上报进度:当前值、总量与进度消息。进度关联到原始调用,进度标识(progress token)由客户端在请求 _meta.progressToken 中携带;框架通过 Context 的 report_progress 方法上报,通知中回传同一 token。
概念解释
- 进度通知用于避免客户端在长任务中误判卡死,配合心跳与超时设置。
- 上报频率应均衡:过密产生噪声,过疏失去反馈意义。
- 进度不保证严格单调,失败重试时可能回退到较早阶段。
原理流程
- 客户端发起长任务调用,请求中带进度关联信息。
- 服务端在循环/分阶段执行中调用进度上报方法。
- 服务端推送进度通知;任务结束后返回最终结果或错误。
代码或图示
await ctx.report_progress(progress=30, total=100)
常见误区
- 只在任务结束才上报:中途无反馈,客户端/用户无法判断是否存活。
- 进度总量无法估计时硬填 100:总量未知时可省略
total,只上报当前进度值。
追问
- 进度通知需要客户端确认吗?答:不需要,通知单向投递。
- 进度上报会阻塞任务执行吗?答:上报本身是轻量消息发送,不应在循环内做重同步操作。
- 长任务超时由谁控制?答:客户端超时与服务端任务超时共同约束,见部署测试主题页。
04.7.18.1-030 cancellation 取消通知如何终止进行中的调用?
一句话结论
客户端可向服务端发送取消通知,请求终止正在进行的调用;服务端在协作式检查点响应取消,停止后续工作并释放资源。取消是信号通知而非强制杀线程,服务端必须在函数内配合检查取消状态,不能依赖框架硬中断。
概念解释
- 取消通知关联到被取消的请求 id 或会话任务标识。
- 协作式取消:在循环、IO 等待点检查取消状态,抛出取消异常或提前返回。
- 已完成的工作不可撤销;取消只阻止后续执行与副作用扩展。
原理流程
- 客户端判断任务不再需要,发出取消通知。
- 服务端把取消状态记入会话/任务上下文。
- 工具函数在检查点读取取消状态,停止执行并返回取消结果或错误。
代码或图示
client -> server: notifications/cancelled {requestId}
server: 在检查点检测取消,停止循环,清理资源
常见误区
- 认为发出取消就会立即终止:Python 线程/协程不能被安全强杀,必须函数内协作检查。
- 取消后不清理已打开的资源:应在退出路径关闭连接、文件句柄与临时对象。
追问
- 取消通知需要响应吗?答:不需要;取消结果通过原请求的最终错误或返回体现。
- 长 IO 等待中如何响应取消?答:IO 需支持超时或取消信号,避免一直挂在不可中断的阻塞调用上。
- 服务端能主动取消自己的任务吗?答:可以按内部错误或超时终止,取消语义主要用于客户端中止。
04.7.18.1-031 ping 心跳机制与超时判定是怎样的?
一句话结论
ping 是双方互发的存活探测请求:收到方应回 pong 类响应,用于判断通道是否仍通。心跳配合空闲超时判定死连接;长时间无 ping 响应或无任何消息,传输层可关闭会话并触发重连。
概念解释
- ping 是带 id 的请求,响应
result为空对象。 - 心跳间隔、超时阈值由客户端/传输层配置,服务端按收到的 ping 应答即可。
- 长任务执行期间不应因“无业务消息”被误判为死连接,进度通知本身也充当存活信号。
原理流程
- 一侧按周期或按需发送 ping 请求。
- 另一侧收到后立即回响应。
- 发送方在超时窗口内未收到响应,判定通道失效,关闭并进入重连流程。
代码或图示
client -> server: ping
client <-- server: pong(空 result)
常见误区
- 把业务请求当心跳:业务调用有自己的超时,不能替代定期存活探测。
- 在服务端阻塞循环里不响应 ping:事件循环被同步阻塞占住时,ping 无法被及时处理。
追问
- 谁发起 ping?答:通常客户端周期发起,服务端也可按需探测,规范未强制单向。
- ping 失败后会话状态保留吗?答:取决于实现,有状态模式可在重连后按会话标识恢复。
- 心跳频率越高越好吗?答:过高增加开销,应按网络环境与空闲超时合理设置。
04.7.18.1-032 listChanged 通知何时由服务端发出?
一句话结论
当工具、资源或提示清单发生增减、变更时,服务端可向已连接客户端发送列表变更通知,告知客户端重新拉取清单。通知只提示“清单变了”,不携带完整新清单;客户端收到后再调用对应 list 方法刷新。
概念解释
- 适用场景:运行期动态注册/移除组件、按环境切换暴露集合。
- 通知按组件类型区分:
notifications/tools/list_changed、notifications/resources/list_changed、notifications/prompts/list_changed。 - 不支持变更通知的服务端,客户端只能在需要时主动 list。
原理流程
- 服务端在动态注册或移除组件后更新内部清单。
- 向会话内客户端推送对应 listChanged 通知。
- 客户端收到后重新调用 list 方法,刷新本地缓存的能力清单。
代码或图示
server -> client: notifications/tools/list_changed
client -> server: tools/list (刷新)
常见误区
- 通知里直接塞新清单:协议语义是变更提示,清单仍由 list 方法提供。
- 静态启动期注册也依赖变更通知:启动清单在握手后首次 list 即可获取。
追问
- 变更通知会发给所有会话吗?答:按服务端实现推送到已连接会话;无状态模式下推送能力受限。
- 客户端漏掉变更通知怎么办?答:可在关键操作前主动 list 兜底刷新。
- 动态改清单需要重启服务吗?答:框架支持运行期注册/移除时不需要,具体 API 见 Schema 主题页。
04.7.18.1-033 stdio 传输的帧格式与进程模型是什么?
一句话结论
stdio 传输通过标准输入读取消息、标准输出写回消息,消息以换行分隔的 JSON 文本帧;服务端进程由客户端拉起,一个进程对应一个本地会话,进程退出即会话结束。stderr 用于日志,不承载协议消息。
概念解释
- 帧格式:每行一条 JSON-RPC 消息,UTF-8 编码,按换行分帧解析。
- 进程模型:客户端按配置启动服务端子进程,管理其生命周期与标准流。
- 本地场景优势:无需端口、无需网络配置,凭据随进程环境隔离。
原理流程
- 客户端拉起服务端进程,接管 stdin/stdout/stderr。
- 服务端从 stdin 逐行读取请求,处理后把响应/通知写入 stdout。
- 客户端关闭 stdin 或进程退出,会话结束并回收子进程。
代码或图示
client process
├─ spawn: server subprocess
│ stdin <- client writes JSON-RPC lines
│ stdout -> client reads JSON-RPC lines
│ stderr -> client reads log lines
常见误区
- 在服务端代码里向 stdout 打印调试信息:会污染协议帧,导致客户端 JSON 解析失败。
- 假设 stdio 服务端常驻后台:默认由客户端按需拉起,不是长期监听端口的守护进程。
追问
- stdio 下能多客户端并发吗?答:每个客户端拉起独立进程;stdio 通道模型以单进程单会话为主,多会话并发应改用 HTTP 传输。
- 消息有大小上限吗?答:按通道与实现限制,超大响应需评估分帧与缓冲区行为。
- 子进程崩溃如何感知?答:客户端监听进程退出码与流关闭,重建会话。
04.7.18.1-034 SSE 传输的双端点结构是什么(legacy)?
一句话结论
早期 SSE 传输是双端点结构:客户端通过 GET 建立到 /sse 的服务器推送流接收服务端消息,再通过 POST 到消息端点把请求发回服务端。该传输已被 Streamable HTTP 取代,保留主要为兼容旧客户端。
概念解释
- 服务端到客户端:SSE 长连接,事件流推送。
- 客户端到服务端:独立 POST 请求,携带会话标识关联到对应 SSE 流。
- 两个端点的路径由框架维护:legacy SSE 为 GET
/sse建流、POST/messages回传请求。
原理流程
- 客户端 GET
/sse建立长连接,服务端返回会话通道标识。 - 客户端 POST 请求到消息端点,带上会话标识。
- 服务端把响应通过已建立的 SSE 流推回客户端。
代码或图示
client --GET /sse----------> server (SSE 长连接, server -> client)
client --POST /messages----> server (client -> server)
server --SSE events--------> client
常见误区
- 把 SSE 传输等同于 Streamable HTTP:SSE 是旧双端点方案,双向通道靠两条 HTTP 连接拼合,健壮性与代理兼容性较差。
- 新部署仍选 SSE:新项目应使用 Streamable HTTP,SSE 仅用于兼容未升级的客户端。
追问
- SSE 传输支持多客户端吗?答:支持,每个连接独立会话;水平扩展受会话内存状态限制。
- 双端点如何关联会话?答:握手阶段交换的会话标识在 POST 时经
Mcp-Session-Id头带回。 - SSE 为什么被淘汰?答:单端点、可恢复性、代理友好性与双向流式体验均不如 Streamable HTTP。
04.7.18.1-035 Streamable HTTP 传输的单端点形态是什么?
一句话结论
Streamable HTTP 是当前推荐的网络传输:客户端向单一端点(默认 /mcp)发 POST 请求,服务端响应可以是一次性 JSON,也可以是 SSE 流以持续推送进度与后续消息。会话通过会话标识头关联,支持有状态与无状态两种模式。
概念解释
- 单端点:请求与响应都走同一 URL,不再需要独立的服务端推送连接。
- 响应形态:短结果用普通 JSON 响应;流式结果用 SSE 事件流持续写入。
- 代理友好:在标准 HTTP/HTTPS 之上运行,可接入网关、负载均衡与 TLS 终止。
原理流程
- 客户端 POST 协议消息到
/mcp,首次请求完成握手并获得会话标识。 - 后续请求携带会话标识头;服务端按会话路由。
- 服务端按结果形态返回 JSON 或 SSE 流;长任务进度在流内持续推送。
代码或图示
client --POST /mcp (initialize)--> server
client <--{protocolVersion, capabilities, sessionId}-- server
client --POST /mcp (tools/call, Mcp-Session-Id)--> server
client <--SSE stream: progress ... result-- server
常见误区
- 把 Streamable HTTP 当普通 REST 短连接:它承载长会话与流式响应,代理必须关闭缓冲并放宽空闲超时。
- 路径写死成
/messages:Streamable HTTP 默认路径是/mcp,可在创建应用时配置。
追问
- 响应何时用 JSON 何时用 SSE?答:短结果框架直接返回 JSON;需要流式推送进度或后续消息时升级为 SSE 事件流。
- 会话标识头叫什么?答:
Mcp-Session-Id。 - 无状态模式还需要会话标识吗?答:无状态模式不保留会话状态,请求自包含;具体差异见后续题。
04.7.18.1-036 三种传输在双向流式与多客户端上有何差异?
一句话结论
stdio 靠两条管道构成双向通道,适合单客户端本地进程;SSE 用长连接加 POST 拼合双向,多客户端可行但链路脆弱;Streamable HTTP 在单端点上支持 JSON/SSE 流式,多客户端并发与代理兼容性最好。选型本质是本地进程隔离还是网络集中服务。
概念解释
- 双向流式:stdio 与 Streamable HTTP 原生支持会话内推送;SSE 服务端推送依赖长连接存活。
- 多客户端:stdio 每进程一会话;HTTP 类传输在单进程内可并发多会话,受内存与下游连接池约束。
- 可恢复性:HTTP 传输配合事件存储可在重连后补收事件;stdio 进程退出后状态不保留。
原理流程
- 按部署位置选传输:本地命令行/桌面集成 → stdio;网络集中部署 → Streamable HTTP。
- 评估并发模型:进程隔离 vs 单进程多会话。
- 评估链路韧性:代理缓冲、空闲超时、断线重连与会话恢复要求。
代码或图示
stdio: 1 process <-> 1 session, pipes
SSE(legacy): 1 SSE long link + 1 POST endpoint per session
Streamable HTTP: 1 endpoint, JSON/SSE response, session header
常见误区
- 认为传输可以无缝互换而不改部署:stdio 无端口与鉴权概念,HTTP 传输需要处理会话、鉴权与代理配置。
- 把本地 stdio 工具直接暴露到公网:缺少网络传输层的鉴权、限流与超时防护。
追问
- 同一套服务端逻辑能换传输吗?答:可以,框架把服务端组件与传输层解耦,通过运行入口选择传输。
- HTTP 传输下 stdio 式子进程隔离还存在吗?答:不存在,会话由服务端进程内管理。
- 哪种传输调试最方便?答:stdio 可用标准流日志排查;HTTP 可用 HTTP 客户端与代理日志排查。
04.7.18.1-037 Streamable HTTP 的会话标识头与会话恢复是怎样的?
一句话结论
握手成功后服务端在响应中返回会话标识,客户端后续请求通过专用请求头携带;服务端按标识查找会话上下文。会话标识是有状态模式的关联钥匙,标识丢失或服务端不持有状态时,请求无法路由到原会话。
概念解释
- 会话标识在首次 initialize 响应中下发,后续每个请求回传。
- 服务端内存中保存会话:能力协商结果、认证结果、订阅与任务上下文。
- 恢复能力:断线重连带回标识后能否继续,取决于服务端是否保留会话与事件存储配置。
原理流程
- 客户端首次 POST initialize,无会话标识。
- 服务端创建会话,响应中返回会话标识。
- 客户端把标识放入后续请求头;服务端按标识匹配会话处理。
代码或图示
POST /mcp
Mcp-Session-Id: <返回值, 首次响应后携带>
常见误区
- 会话标识写进工具参数:它是传输层关联信息,不属于业务 arguments。
- 多副本下假定会话标识全局有效:会话状态在某一实例内存中,未做共享存储时其他实例查不到。
追问
- 会话标识会过期吗?答:按空闲超时与会话生命周期回收,过期后需重新握手。
- 标识头标准名称是什么?答:
Mcp-Session-Id。 - 重连后能继续之前的长任务吗?答:有状态且会话仍在、事件可补收时可以;否则需重新发起。
04.7.18.1-038 有状态(stateful)与无状态(stateless)HTTP 模式有什么区别?
一句话结论
有状态模式在服务端保存会话上下文,支持会话内推送、订阅与跨请求关联;无状态模式每个请求自包含,服务端不保留会话,横向扩展更容易,但主动推送与会话级能力受限。两者由服务端配置切换,适用场景不同。
概念解释
- 有状态:需要会话标识与内存状态,长任务进度、资源订阅、上下文复用更自然。
- 无状态:请求之间不依赖服务端内存,适合多副本水平扩展;流式推送与持久订阅能力受限制。
- 无状态模式下响应仍可按推送需要选择 JSON 或 SSE 流;会话状态不随服务端保留。
原理流程
- 部署侧决定:需要会话内协作选有状态;追求水平扩展选无状态。
- 有状态服务端在握手后保存会话;无状态服务端按请求独立处理。
- 无状态模式下客户端不依赖服务端保留会话,重连即重新协商。
代码或图示
mcp = FastMCP("stateless-demo", stateless_http=True)
常见误区
- 无状态模式下还依赖服务端记住上次调用参数:服务端不存会话,需要的数据必须每次请求带上。
- 有状态服务随意多副本扩容:会话粘滞或共享存储未解决前,扩容会导致会话丢失。
追问
- 无状态模式支持资源订阅吗?答:订阅与推送依赖会话上下文,无状态模式下受限,客户端通常降级为主动读取。
- 有状态会话存在哪里?答:默认保存在进程内存;跨进程共享需接入外部会话/事件存储后端。
- 如何在两者间取舍?答:先看是否需要服务端主动推送与会话记忆,再看扩展诉求。
04.7.18.1-039 传输层与协议层如何解耦?
一句话结论
服务端框架内部把“组件注册、schema 生成、方法分发、上下文管理”与“消息如何在 stdio/HTTP 上收发分帧”分开:协议处理层产出或消费 JSON-RPC 消息,传输层只负责字节流与通道管理。同一服务端实例可通过不同入口切换传输。
概念解释
- 协议层:方法名路由、参数校验、通知生成、错误映射。
- 传输层:stdin/stdout 管道、HTTP 路由、会话头、SSE 分帧、连接管理。
- 解耦收益:业务代码不关心通道类型,测试可在内存内直连,部署再选传输。
原理流程
- 注册组件时框架生成协议层可分发的方法表与 schema。
- 选定传输后,传输层把收到的字节解码为 JSON-RPC 消息交给协议层。
- 协议层返回结果或通知,传输层编码回对应通道。
代码或图示
transport(stdio/sse/http) <--序列化/分帧--> protocol(session/router/schema) <--> tools/resources/prompts
常见误区
- 在工具业务代码里直接操作 stdout 或 HTTP 响应:绕过协议层会破坏帧格式与会话管理。
- 认为换传输就要重写服务端:组件代码保持不变,只改运行入口与部署配置。
追问
- 解耦后鉴权属于哪一层?答:HTTP 传输层接入认证钩子,认证结果写入会话供协议层使用。
- 测试为什么能内存内直连?答:跳过真实传输层,直接在协议会话上收发消息。
- 传输层异常如何反馈给协议层?答:以传输错误或会话断开事件通知协议层清理上下文。
04.7.18.1-040 选择传输方式时有哪些部署决策要点?
一句话结论
先定接入形态:本地命令行、桌面应用集成选 stdio;网络集中服务、多客户端共享、需要鉴权与负载均衡选 Streamable HTTP;SSE 仅兼容旧客户端。再评估会话状态、推送需求、代理链路与扩展方式,最后落实超时、重连与可观测性配置。
概念解释
- 本地场景:进程由客户端拉起,隔离性好,不暴露端口。
- 网络场景:需要鉴权、TLS、反向代理、多副本与监控体系。
- 遗留兼容:老客户端未升级时保留 SSE,同时规划迁移到 Streamable HTTP。
原理流程
- 明确用户位置:本机进程还是远程网络访问。
- 评估能力需求:主动推送、订阅、长任务流式、多会话并发。
- 结合扩展模型与基础设施(代理、证书、日志)选定传输并配置参数。
代码或图示
本机集成 / 桌面端 -> stdio
网络集中 / 多客户端 / 鉴权 -> Streamable HTTP
旧客户端兼容 -> SSE(legacy)
常见误区
- 只按框架默认值选传输:默认 stdio 适合本地,不等于适合生产网络部署。
- 忽略代理与超时就上 HTTP 传输:缓冲、空闲超时、TLS 任一不匹配都会导致流式中断。
追问
- 一个服务端能同时提供两种传输吗?答:FastMCP 实例的
run()按选定传输启动;同进程同时提供 stdio 与 HTTP 需分别启动不同入口/实例。 - 远程服务必须鉴权吗?答:暴露到网络即应配置认证,公开无鉴权端点风险极高。
- 传输选型影响测试策略吗?答:影响,内存内直连测试传输无关,网络测试需覆盖代理与重连。
04.7.18.1-041 FastMCP 实例构造参数 name/version/instructions 各自起什么作用?
一句话结论
name 是服务端可读标识,进入 serverInfo.name;version 是服务端自身版本,进入 serverInfo.version;instructions 是面向使用方的整体指引,在 initialize 响应中下发给客户端。三者都在构造实例时确定,握手时一并上报。
概念解释
name:多服务端接入时用于区分连接,应唯一且可读,避免使用默认占位名。version:产品版本号,不等同于依赖库版本;未传时 FastMCP 2.x 回退为库自身版本号。instructions:自然语言说明服务端用途与调用约定,粒度粗于工具 description。
原理流程
- 构造
FastMCP实例时传入身份与说明参数。 - 实例内部保存这些元数据,注册组件时不覆盖身份信息。
- initialize 响应组装
serverInfo与instructions返回客户端。
代码或图示
from fastmcp import FastMCP
mcp = FastMCP(
name="report-server",
version="2.0.1",
instructions="提供报表生成与指标查询工具,时间范围参数必填。",
)
常见误区
- 把工具级使用细节写进 instructions:单工具的参数说明应放工具 docstring,避免 instructions 过长。
- 依赖自动填充 version:服务端版本应随发布流程显式配置,不能默认等于框架版本。
追问
- 构造参数还有哪些常见项?答:
auth(鉴权提供者)、lifespan、include_tags/exclude_tags、on_duplicate_tools/on_duplicate_resources/on_duplicate_prompts、strict_input_validation、include_fastmcp_meta等。 - name 会被工具名占用吗?答:不会,name 是服务端身份,工具名在工具命名空间内唯一。
- instructions 可以运行期修改吗?答:握手后以会话内协商结果为准,运行期改动不自动刷新已建立会话。
04.7.18.1-042 服务端能力声明如何随注册内容自动生成?
一句话结论
框架按已注册组件自动汇总服务端能力:注册了工具即声明 tools 能力,注册了资源即声明 resources 能力,注册了提示即声明 prompts 能力;内置能力如日志、补全按实现开启。能力清单在握手响应中交给客户端,通常不需要手工逐一声明。
概念解释
- 能力与组件对应:组件存在才有对应方法族,避免声明空能力。
- 子标志(如
resources.subscribe、listChanged)由框架按已注册能力附加。 - 动态增减组件后,已建立会话的能力视图通过 listChanged 通知配合刷新。
原理流程
- 装饰器或程序化注册把组件加入实例内部清单。
- 握手时遍历清单,生成 capabilities 对象。
- 客户端按能力决定展示哪些入口、发起哪些方法调用。
代码或图示
注册 tool -> capabilities.tools
注册 resource -> capabilities.resources
注册 prompt -> capabilities.prompts
常见误区
- 手工在能力里声明未实现的方法:客户端调用后失败,比不声明更损害体验。
- 认为能力声明需要每次 list 时重算:握手阶段生成一次,组件变更走通知刷新。
追问
- 如何关闭某个能力对外暴露?答:不注册对应组件,或用标签过滤/条件注册控制可见集合。
- 客户端能力会影响服务端能力声明吗?答:不会,两侧能力在各自一侧声明。
- 能力自动生成覆盖哪些框架版本?答:FastMCP 2.x 按注册组件自动汇总能力;更早的官方 Python SDK 行为需对照迁移说明。
04.7.18.1-043 serverInfo.name 默认值与未传 version 时的行为是什么?
一句话结论
FastMCP 2.x 未显式传 name 时默认名为 "FastMCP";未传 version 时回退为 FastMCP 库自身版本号。服务端产品版本应显式传入,不能假定等于框架版本。
概念解释
- 默认名只影响客户端展示与日志识别,不影响协议方法路由。
- 版本字段用于排查“线上跑的是哪个构建”,应在部署配置中显式注入。
- 框架自身版本与服务端产品版本是两个概念,握手上报的是后者。
原理流程
- 构造实例时检查 name/version 是否提供。
- 缺失时套用框架默认值或空值规则。
- initialize 响应把最终值写入 serverInfo。
代码或图示
# 显式指定,避免依赖默认值
mcp = FastMCP(name="inventory-server", version="1.0.0")
常见误区
- 测试断言默认名等于某个固定字符串:跨版本默认值可能变化,测试应显式传名。
- 把库版本当服务端版本上报:排查问题时无法对应产品发布记录。
追问
- 默认名在客户端哪里显示?答:连接列表、会话标题与日志标识中。
- version 为空会导致握手失败吗?答:不会,
serverInfo.version属于标识字段,缺失不阻断握手。 - 如何在多环境区分实例?答:name 或 version 中带环境标识,但避免写入敏感信息。
04.7.18.1-044 description/title 与 instructions 在客户端展示上有什么区别?
一句话结论
title/description 偏服务端身份与摘要展示,instructions 是给模型/使用方的操作指引文本。title 用于界面标题类展示,description 是简短说明,instructions 会被并入模型可用上下文指导调用方式。
概念解释
- 身份字段:name、title、description、version 构成服务端档案。
- 指引字段:instructions 回答“这个服务怎么用”,可包含调用顺序、前置条件与注意事项。
- 粒度差异:服务端整体说明放 instructions;单工具用途放工具 description。
原理流程
- 构造实例时分别提供身份摘要与使用指引。
- 握手响应把身份字段放入 serverInfo,指引字段单独下发。
- 客户端 UI 展示身份信息,模型上下文吸收指引文本。
代码或图示
mcp = FastMCP(
name="doc-server",
title="文档检索服务",
description="按关键词检索内部文档片段。",
instructions="检索前先确认文档范围;返回片段仅供引用,不代表全文结论。",
)
常见误区
- 用 instructions 堆产品营销文案:模型需要的是可执行调用约定,不是宣传语。
- 三个字段内容重复:title/description 做摘要,instructions 做指引,各司其职。
追问
- 字段名在不同版本有差异吗?答:FastMCP 2.x 构造器以关键字参数为主:
name、version、instructions、auth、lifespan。 - instructions 为空时模型如何理解服务端?答:只能依据各工具 description 与资源/提示清单推断,理解质量下降。
- 这些字段会进入工具 schema 吗?答:不会,它们属于服务端元数据,不在工具 inputSchema 内。
04.7.18.1-045 服务端生命周期:启动与关闭钩子的执行时机是什么?
一句话结论
服务端生命周期覆盖“启动初始化 → 会话服务 → 关闭清理”三个阶段:启动期建立下游连接、加载配置、预热缓存;服务期处理各会话请求;关闭期释放连接、文件句柄与后台任务。框架通过生命周期钩子或异步上下文管理器暴露启动/关闭逻辑。
概念解释
- 启动钩子:在接受首个会话前执行,适合初始化数据库连接池、客户端实例、资源加载。
- 关闭钩子:在停止接受新会话后执行,等待进行中任务收尾再释放资源。
- 生命周期与传输无关:stdio 进程启动退出、HTTP 服务启停都走同一套阶段划分。
原理流程
- 实例进入启动阶段,执行生命周期初始化代码。
- 启动完成后开始接受客户端会话与方法调用。
- 收到停止信号后停止新请求,执行关闭清理,释放资源后退出。
代码或图示
startup: 加载配置 / 建连接池 / 预热
serve: 会话握手 / 工具资源提示调用
shutdown: 收尾任务 / 关闭连接 / 释放资源
常见误区
- 在模块导入阶段做重初始化:导入时资源可能未就绪,且测试导入会触发副作用;应放生命周期钩子。
- 关闭阶段直接杀连接:未完成的调用与事务被中断,应先优雅收尾再释放。
追问
- 生命周期钩子在哪个对象上配置?答:FastMCP 构造器
lifespan=参数,接收一个异步上下文管理器。 - 启动失败如何处理?答:初始化异常应阻断启动并上报,不要带病进入服务期。
- 生命周期内能访问工具清单吗?答:可访问已注册组件;动态注册时机需在启动阶段完成。
04.7.18.1-046 lifespan 异步上下文管理器的写法与作用域是什么?
一句话结论
lifespan 是一个异步上下文管理器函数:进入时执行启动逻辑,yield 后服务端进入服务期,退出时执行关闭逻辑。它以 async with 方式被框架驱动,作用域覆盖整个服务运行期,适合管理连接池、外部客户端与共享资源。
概念解释
- 写法:
@asynccontextmanager装饰的 async 函数,yield分隔启动与关闭两段。 - 作用域:从服务端启动到关闭,跨所有会话共享其中创建的资源。
- 与请求级上下文区别:lifespan 资源是全局共享的;会话级身份与状态放在会话上下文。
原理流程
- 定义异步上下文管理器,进入段创建共享资源。
yield挂起,框架在此期间对外服务。- 关闭时回到退出段,按逆序释放资源。
代码或图示
import contextlib
import httpx
@contextlib.asynccontextmanager
async def lifespan(server):
client = httpx.AsyncClient(timeout=10)
try:
yield
finally:
await client.aclose()
常见误区
- 在 lifespan 里存请求级数据:跨会话共享会串扰,请求级身份应放会话上下文。
- 退出段不做异常隔离:启动段抛错会阻止服务启动;关闭段异常应记录并尽量继续释放其他资源。
追问
- lifespan 接收的参数是什么?答:异步上下文管理器函数接收服务端实例作为参数,
yield前后分别为启动与关闭逻辑。 - 多个服务端实例如何组合 lifespan?答:挂载多个实例时需合并各自生命周期,确保每个会话管理器都被启动与关闭。
- 同步资源能放进 lifespan 吗?答:可以创建,但关闭时同步释放要注意不要长时间阻塞事件循环。
04.7.18.1-047 如何把 FastMCP ASGI 应用挂载进 FastAPI?
一句话结论
先由 FastMCP 实例生成 ASGI 应用对象(如 http_app(path="/mcp")),再用 FastAPI 的 mount 挂到指定前缀;同时必须把 MCP 应用的 lifespan 传给 FastAPI 实例,保证会话管理器正确初始化。挂载后既有 API 路由与 MCP 端点共存于同一进程与端口。
概念解释
http_app:把服务端组件包装成 ASGI 可挂载应用,路径参数决定 MCP 端点在子应用内的位置。mount:Starlette/FastAPI 的子应用挂载机制,前缀下的请求转发给子应用。- 生命周期传递:父应用启动时要触发 MCP 会话管理器启动,否则会话无法建立。
原理流程
- 创建 FastMCP 实例并注册工具/资源/提示。
- 调用
http_app(path=...)得到 ASGI 子应用。 - 创建 FastAPI 时传入
lifespan=mcp_app.lifespan,再app.mount("/mcp", mcp_app)。
代码或图示
from fastapi import FastAPI
from fastmcp import FastMCP
mcp = FastMCP("api-tools")
@mcp.tool
def query_database(query: str) -> dict:
"""执行只读查询。"""
return {"result": "data"}
mcp_app = mcp.http_app(path="/mcp")
api = FastAPI(lifespan=mcp_app.lifespan)
api.mount("/mcp", mcp_app)
常见误区
- 挂载时不传 lifespan:会话管理器未初始化,握手或后续请求失败。
- 路径拼接算错:挂载前缀加子应用内路径共同构成最终 URL,测试时按完整路径连接。
追问
- 能挂载多个 FastMCP 实例吗?答:可以,分别生成子应用挂到不同前缀,并合并各自 lifespan。
- MCP 子应用能复用父应用的中间件吗?答:父应用中间件会经过,但鉴权与 CORS 叠加需注意冲突,见部署测试主题页。
- 生成 ASGI 应用的方法名在版本间有差异吗?答:FastMCP 2.x 为
mcp.http_app(path=..., middleware=..., event_store=..., retry_interval=...)。
04.7.18.1-048 挂载到 Starlette/FastAPI 时为什么必须传递 lifespan?
一句话结论
嵌套挂载时父应用不会自动识别子应用的生命周期;不显式传递 MCP 应用的 lifespan,其会话管理器、启动资源与关闭清理就不会被驱动,表现为握手失败、会话无法建立或资源未释放。因此创建父应用时要把 lifespan=mcp_app.lifespan 传入。
概念解释
- ASGI 生命周期:应用启动与关闭由父应用在生命周期事件中驱动,子应用不会自行运行。
- 会话管理器:HTTP 传输依赖它维护会话表、事件存储与连接状态。
- 多实例场景:每个挂载的 MCP 应用都需要进入生命周期,必要时用组合 lifespan 统一管理。
原理流程
- 父应用启动时执行其 lifespan 链。
- 传入 MCP lifespan 后,启动段初始化会话管理器与共享资源。
- 父应用关闭时退出段执行,子应用资源随生命周期释放。
代码或图示
from starlette.applications import Starlette
from starlette.routing import Mount
app = Starlette(
routes=[Mount("/mcp", app=mcp_app)],
lifespan=mcp_app.lifespan,
)
常见误区
- 只 mount 不传 lifespan:路由可达但会话初始化缺失,错误可能表现为握手超时或内部错误。
- 认为子应用会自己监听端口:挂载模式下端口由父应用(uvicorn 等)统一监听。
追问
- 多个子应用 lifespan 如何合并?答:用异步退出栈(如
AsyncExitStack)依次进入各上下文管理器,关闭时逆序退出。 - lifespan 漏传会在启动时报错吗?答:不一定立即报错,常延迟到首个会话请求才暴露,需在测试中覆盖握手。
- 父应用已有自己的 lifespan 怎么办?答:把 MCP 生命周期并入父应用 lifespan 链,不要互相覆盖。
04.7.18.1-049 JSON-RPC 标准错误码段与自定义错误码段如何划分?
一句话结论
JSON-RPC 2.0 保留标准码段:解析错误 -32700、无效请求 -32600、方法不存在 -32601、参数无效 -32602、内部错误 -32603;-32000 到 -32099 为实现自定义保留段。协议框架错误落标准码,业务自定义错误落自定义段,避免混用。
概念解释
- 标准码:描述协议层通用失败,客户端可按码做通用分支处理。
- 自定义段:服务端业务错误子类型,在
data中补充细分原因。 - 错误码负数区间之外的取值不建议使用,以免与未来规范冲突。
原理流程
- 报文解析失败 → -32700;请求结构不合法 → -32600。
- 方法未注册 → -32601;参数校验失败 → -32602;执行期异常 → -32603 或自定义码。
- 业务细分错误在自定义段取值,并在 data 中写明子类型。
代码或图示
-32700 Parse error
-32600 Invalid Request
-32601 Method not found
-32602 Invalid params
-32603 Internal error
-32000..-32099 实现自定义
常见误区
- 所有业务失败都返回 -32603:客户端无法区分参数问题、未找到与冲突,应细分到自定义码或 data 子类型。
- 自定义码占用标准保留段:未来规范扩展时可能产生冲突。
追问
- MCP 自身有额外错误码吗?答:MCP 在 JSON-RPC 标准码之上使用 -32000 段的实现/应用错误码,如资源不存在 -32002。
- HTTP 状态码与 JSON-RPC 错误码如何配合?答:HTTP 表达传输层结果(401/404/500 等),协议错误体现在 JSON-RPC error 对象。
- 错误码需要文档化吗?答:需要,自定义段取值与 data 子类型应在服务端说明中列出。
04.7.18.1-050 协议层错误与业务层错误在服务端如何划分处理?
一句话结论
协议层错误由框架在报文解析、方法分发、参数 schema 校验阶段产生,映射到标准错误码;业务层错误是工具/资源/提示函数执行中的领域失败(未找到、冲突、权限不足等),由业务代码抛出并转换为自定义错误码或错误内容。两层分别捕获,避免业务异常裸冒泡到传输层。
概念解释
- 协议层:JSON 解析、请求结构、方法存在性、参数类型与必填校验。
- 业务层:领域规则校验、下游调用失败、资源状态冲突。
- 错误映射:业务异常在框架边界被捕获,转成带 code/message/data 的协议错误;敏感细节不外泄。
原理流程
- 传输层解码报文,协议层校验结构与方法。
- 参数按 schema 校验通过后进入业务函数。
- 业务异常被捕获并映射为协议错误响应;未捕获异常兜底为内部错误并记录日志。
代码或图示
class NotFoundError(Exception):
pass
# 框架边界捕获后映射:
# code: 自定义段, message: "记录不存在", data: {"id": rid}
常见误区
- 业务异常直接冒泡成连接断开:客户端只看到通道错误,拿不到结构化失败原因。
- 把业务校验失败归为协议参数错误:参数格式合法但领域规则不满足,应走业务错误分支。
追问
- 业务错误应该在 result 里还是 error 里?答:执行失败、未完成语义走 error;成功返回但结果内含状态字段,可放结构化 result,约定需在服务端文档说明。
- 下游超时算哪层错误?答:触发点在业务调用,错误归类为业务/外部依赖错误,包装后返回。
- 如何统一错误格式?答:在服务端边界定义异常到错误码的映射表,集中处理 message 与 data 脱敏。
04.7.18.1-051 参数校验失败、方法不存在、内部异常分别落到哪个错误码?
一句话结论
方法名未注册或不可识别落“方法不存在”;参数结构、类型、必填项不满足 schema 落“参数无效”;函数执行期未预期异常落“内部错误”,业务可识别的失败应进一步映射到自定义错误码。三类失败在框架边界分别捕获,错误 message 与 data 按类别填充。
概念解释
- 方法不存在:路由表查不到对应方法,通常与组件未注册或名称拼写错误有关。
- 参数无效:schema 校验阶段拦截,data 可带字段名与失败原因。
- 内部错误:执行期异常兜底,应记录完整堆栈到服务端日志,对外只给安全描述。
原理流程
- 收到请求先查方法表,未命中返回方法不存在错误。
- 命中后按输入 schema 校验 arguments,失败返回参数无效错误。
- 执行函数,捕获业务异常映射自定义码;未捕获异常兜底内部错误并记日志。
代码或图示
unknown method -> -32601
invalid params -> -32602
unhandled error -> -32603 / 自定义段
常见误区
- 参数格式问题与领域规则问题混在同一错误:前者是协议参数错误,后者是业务错误,data 子类型应区分。
- 内部错误对外返回堆栈:泄露实现细节,堆栈只落服务端日志。
追问
- 工具主动抛出自定义异常如何转码?答:在框架边界的异常映射中按类型映射错误码与 data。
- 方法不存在也可能是版本不兼容吗?答:可能,旧客户端调用新方法或反之,需结合协议版本排查。
- 校验失败会执行函数体吗?答:不会,schema 校验通过后才进入函数。
04.7.18.1-052 MCP 规范版本演进的大致脉络是什么?
一句话结论
MCP 规范经历了从早期草案到稳定版本的迭代:传输上从 stdio 起步,加入 SSE 远程传输,再演进到 Streamable HTTP;能力模型围绕 tools/resources/prompts 逐步扩展鉴权、订阅、补全等机制。规范已发布版本标识如 2025-06-18、2025-11-25;实现版本与规范版本要分开核对。
概念解释
- 规范版本:协议报文、方法、字段的稳定承诺,握手时通过 protocolVersion 协商。
- 实现版本:SDK/框架包版本,同一规范版本下可能有 API 与默认值差异。
- 演进方向:远程部署友好、可恢复性、安全鉴权与多端一致性。
原理流程
- 对照官方规范确认当前实现遵循的 protocolVersion。
- 查 SDK/框架迁移说明识别 API 重命名、参数顺序与默认值变化。
- 跨版本接入时按能力与方法名做兼容判断,不凭印象写死字段。
代码或图示
规范层: protocolVersion / methods / fields
实现层: SDK 或框架包版本 / 装饰器 / 默认行为
常见误区
- 把框架包版本号当协议版本号上报或比对:两者不是一回事。
- 照搬旧文档示例到新版本:装饰器名、构造参数顺序、传输方法名可能已变更。
追问
- 在哪里查规范最新版本?答:MCP 官方规范站点 modelcontextprotocol.io 的规范版本页与变更记录章节。
- 旧规范客户端能连新规范服务端吗?答:靠版本协商与能力降级,未声明能力不调用;破坏性变更需双端升级。
- 版本演进会改变三原语定位吗?答:tools/resources/prompts 核心定位保持稳定,细节字段与能力子标志可能调整。
04.7.18.1-053 实现中常见的待确认行为与验证方法有哪些?
一句话结论
版本相关的默认值、API 命名、参数顺序与子字段最容易随版本变化,不能凭印象写死。验证方法:查当前版本文档与迁移指南、在隔离环境跑最小握手/调用用例、检查 initialize 响应与 list 清单的实际字段,再把结论固化到代码与测试断言中。
概念解释
- 已核实类别:构造器默认值、传输字面量、ASGI 应用方法名、鉴权校验器类名、会话头名称、输出 schema 行为。
- 验证手段:阅读官方文档与源码类型定义;写内存内 client 用例观察实际报文;比对 initialize 响应结构。
- 真正版本敏感且无法从官方资料确认的项标注验证点,不编造确定行为。
原理流程
- 列出影响接口契约的版本敏感点。
- 逐一在当前安装版本的文档/源码/运行报文中核实。
- 核实前代码保留灵活写法,测试断言基于实际观察到的行为。
代码或图示
文档 -> 源码类型定义 -> 最小用例实跑 -> 记录实际报文 -> 更新断言
常见误区
- 凭其他语言 SDK 印象推断 Python API:各语言实现命名与默认值可能不同。
- 把未核实项写进对外承诺文档:未核实前标注验证点,避免误导调用方。
追问
- 如何查看本地安装的框架版本?答:
pip show fastmcp查询依赖版本,再对照该版本文档与类型定义。 - 未核实项什么时候可以去掉?答:在目标版本上跑通用例并观察到确定报文后,移除标注并补充断言。
- 源码里如何找默认值?答:查构造器签名、默认参数与能力汇总函数,不凭类名猜测。
04.7.18.1-054 服务端如何向客户端暴露额外元数据(meta 字段)?
一句话结论
组件与方法响应可携带 meta 元数据字段,附在工具、资源、提示或结果上,用于标签、展示信息或框架自定义标记。FastMCP 2.x 通过构造器 include_fastmcp_meta(默认 True)控制是否在 _meta 中附带框架内部元数据;自定义标签经装饰器 tags= 附加。
概念解释
- meta 不改变方法语义,只补充展示与治理信息。
- 框架可能在 meta 中放入自身命名空间下的标签、排序、描述等内部标记。
- 对外集成时可选择是否暴露框架内部 meta,减少与外部系统的耦合。
原理流程
- 注册组件时附加标签或元信息。
- 框架在生成 list 清单与结果时把 meta 一并组装。
- 客户端按 meta 做展示分组、过滤或其他增强。
代码或图示
# tags 作为组件元数据附加
@mcp.tool(tags=["report"])
def daily_report(date: str) -> str:
"""生成日报。"""
return "report"
常见误区
- 把业务必填参数塞进 meta:入参契约必须走 inputSchema,meta 不参与调用校验。
- 依赖框架内部 meta 键名做跨版本集成:内部命名空间可能重命名,升级时需回归。
追问
- meta 会出现在 initialize 响应里吗?答:服务端身份字段在 serverInfo;组件 meta 在各 list 清单与结果中。
- 能关闭框架内部 meta 输出吗?答:构造器
include_fastmcp_meta=False可关闭框架内部 meta 附带。 - 自定义 meta 需要客户端识别吗?答:未约定的 meta 客户端可忽略,集成前需双方对齐键名。
04.7.18.1-055 会话内上下文:服务端如何区分不同客户端调用?
一句话结论
服务端按会话隔离上下文:每个连接/会话持有独立的认证结果、客户端标识、订阅关系与请求级缓存。工具函数通过 Context 拿到当前会话信息,不能用模块级全局变量保存身份,否则并发会话会串扰。
概念解释
- 会话上下文随握手建立,随连接关闭释放。
- Context 是访问当前会话信息与能力的入口,框架按调用注入对应实例。
- 共享资源(连接池、配置)放 lifespan;会话身份与状态放会话上下文。
原理流程
- 握手完成,框架创建会话记录并绑定连接。
- 请求进入时把会话上下文传给工具/资源/提示函数。
- 函数通过 Context 读取当前客户端信息,写入会话级临时状态。
代码或图示
@mcp.tool
def whoami(ctx: Context) -> dict:
"""返回当前会话客户端标识。"""
return {"client_id": ctx.client_id}
常见误区
- 在工具里用全局 dict 按参数名存用户身份:多会话并发时互相覆盖。
- 假设 Context 在函数外也能访问:它是调用期注入对象,模块作用域内不存在当前会话。
追问
- Context 上有哪些会话信息?答:
ctx.client_id、ctx.session_id、ctx.request_id,以及日志(info/debug/warning/error)、report_progress、read_resource、list_resources、list_prompts等方法。 - 会话上下文能跨请求保留吗?答:同一会话内可以,会话结束即释放。
- 无状态模式下上下文如何区分?答:请求自包含,会话级记忆受限,身份信息需每次请求携带。
04.7.18.1-056 协议版本、服务能力与组件元信息三者是什么关系?
一句话结论
协议版本定义报文与方法的规范基线;服务能力是握手时声明的方法族开关;组件元信息是具体工具/资源/提示的名称、描述、schema 与标签。版本决定“能说什么话”,能力决定“开了哪类通道”,元信息决定“通道里有哪些具体能力”。
概念解释
- 协议版本:跨端兼容的最高层约定,握手协商。
- 服务能力:在版本基线内选择启用的方法族,按注册内容汇总。
- 组件元信息:能力族内的具体条目,通过 list 方法枚举。
原理流程
- initialize 协商 protocolVersion,确定报文基线。
- 响应 capabilities 声明开放的方法族。
- 客户端再调 list 方法获取各组件的元信息与 schema。
代码或图示
protocolVersion -> 报文/方法基线
capabilities -> tools / resources / prompts ...
component meta -> name, description, inputSchema, tags
常见误区
- 把组件清单写进 capabilities:能力只描述方法族,具体条目走 list 枚举。
- 忽略版本直接读元信息字段:旧版本字段名可能不同,先确认协商版本。
追问
- 三者在哪一步分别出现?答:版本与能力在 initialize 响应;组件元信息在后续 list 响应。
- 组件增减需要改能力声明吗?答:会话内能力族不变,具体条目变更通过 list 与变更通知反映。
- 客户端如何判断某组件是否可用?答:先看能力族是否声明,再在对应 list 清单中查找条目。
04.7.18.1-057 一个最小可运行服务端的完整结构是什么?
一句话结论
最小结构:导入 FastMCP、创建实例、用装饰器注册至少一个工具、在入口处调用运行方法启动传输。本地默认走 stdio;网络部署再切换传输并配置端口路径。代码体量很小,但握手、schema 生成、方法分发都由框架完成。
概念解释
- 实例:持有组件清单与配置。
- 组件:装饰器注册的函数。
- 运行入口:按所选传输启动服务,stdio 下由客户端拉起进程。
原理流程
- 导入框架并创建
FastMCP实例。 - 注册工具函数,docstring 与类型注解自动生成描述与 schema。
run()启动默认传输;脚本作为主程序执行时进入服务循环。
代码或图示
from fastmcp import FastMCP
mcp = FastMCP("demo-server")
@mcp.tool
def add(a: int, b: int) -> int:
"""两个整数相加。"""
return a + b
if __name__ == "__main__":
mcp.run()
常见误区
- 把实例创建写在
if __name__块内:其他地方需要引用实例时不可见,注册应在模块层完成。 - 忘记调用运行入口:实例只在内存中注册组件,不启动传输就不会响应任何连接。
追问
- 默认传输是什么?答:
mcp.run()默认 stdio;网络服务显式传transport="http"(Streamable HTTP),另有 legacy"sse"。 - 最小服务需要资源和提示吗?答:不需要,单一工具即可构成可运行服务端。
- 脚本如何被客户端拉起?答:stdio 客户端按配置启动该脚本进程,通过标准流通信。
04.7.18.1-058 服务端启动后默认监听的传输与端口行为是什么?
一句话结论
默认运行入口采用 stdio 传输,不监听 TCP 端口;切换到 HTTP 类传输后才绑定 host 与 port,Streamable HTTP 端点默认在 /mcp 路径。未显式配置时 FastMCP 2.x 默认 host 127.0.0.1、port 8000、HTTP 路径 /mcp。
概念解释
- stdio:无网络监听,进程生命周期由客户端管理。
- HTTP 传输:监听配置的 host/port,路径决定端点 URL。
- 容器部署时 host 通常绑定
0.0.0.0,端口由环境变量或启动参数注入。
原理流程
- 调用
run()时读取传输类型参数。 - stdio 直接接入标准流;HTTP 类传输创建 ASGI 服务并绑定地址端口。
- 反向代理或容器映射外部端口到监听端口。
代码或图示
mcp.run(transport="http", host="0.0.0.0", port=8000, path="/mcp")
常见误区
- 以为默认就监听 8000 等端口:默认 stdio 没有端口概念。
- 绑定
127.0.0.1后容器外部不可达:容器内监听需用0.0.0.0或对应接口地址。
追问
- 端口冲突如何排查?答:检查监听占用与启动日志,确认 host/port 配置与代理映射一致。
- 能同时跑 stdio 与 HTTP 实例吗?答:通常分别启动不同入口/实例;单实例
run()只绑定一种传输。 - 生产环境默认值够用吗?答:host、port、路径、超时都应按部署环境显式配置,不依赖默认值。
04.7.18.1-059 跨语言互通:Python 服务端与其他语言客户端互通的前提是什么?
一句话结论
互通前提是双方遵循同一 MCP 规范基线:报文都是 JSON-RPC 2.0,方法名、参数结构、内容块形态与能力协商一致;传输层按 stdio 或 HTTP 标准对接。Python 侧使用框架自动处理协议细节,不依赖 Python 专属私有扩展;未约定的自定义 meta 与扩展能力需客户端可忽略。
概念解释
- 规范一致性:协议版本、方法族、字段命名跨端对齐。
- 传输一致性:stdio 标准流或 Streamable HTTP/SSE 端点形态匹配。
- 类型兼容:入参出参用 JSON Schema 描述,避免依赖 Python 独有类型序列化。
原理流程
- 确认客户端实现遵循的规范版本与支持传输。
- Python 服务端按规范注册组件,避免私有报文扩展。
- 握手对齐版本与能力,按标准方法完成 list 与 call 联调。
代码或图示
Python server --JSON-RPC 2.0 / stdio|HTTP-- 其他语言 client
常见误区
- 返回 Python 专属对象(如日期时间、自定义类)不做序列化:其他语言无法解析。
- 使用框架私有 meta 当契约:跨语言客户端不认识会忽略,不能作为必需参数。
追问
- 跨语言联调先测哪一步?答:先完成 initialize 握手与 list 清单,再测 tools/call。
- 规范版本不一致怎么办?答:按协商结果降级,未声明能力不调用;必要时双端升级。
- 二进制内容跨端如何保证?答:按协议内容块的编码与 MIME 类型传输,不用语言特定格式。
04.7.18.1-060 本章边界:哪些内容不属于 MCP 服务端框架范畴?
一句话结论
本章只覆盖 MCP 服务端框架本身:协议模型、Server 核心、组件注册与 schema、传输鉴权、生命周期、部署测试与安全。模型调用、RAG 检索、Agent 编排、工具链调度与 LangChain 类集成属于 AI 应用开发分册,不在本页展开;服务端代码即使被模型调用,也只描述其作为能力提供方的职责。
概念解释
- 服务端职责:暴露契约、执行函数、返回结果、管理会话与传输。
- 不属于服务端:选模型、拼上下文、检索知识库、多工具规划、多轮 Agent 循环。
- 边界意义:避免把框架题库写成应用编排题库,职责分层清晰。
原理流程
- 判断题目是“能力如何暴露与执行”还是“模型如何决策编排”。
- 前者归入本章;后者归入 AI 应用开发分册。
- 跨边界话题只在服务端接口处提及,不展开编排细节。
代码或图示
本章: tools/resources/prompts 注册, schema, 传输, 鉴权, 生命周期, 测试
非本章: 模型选择, RAG, Agent 规划, 编排框架
常见误区
- 在服务端工具里硬编码模型提示与多步规划:那是应用层职责,服务端应保持单一动作粒度。
- 把客户端模型上下文管理写进服务端文档:上下文拼装发生在客户端一侧。
追问
- 工具内部可以调用外部 API 吗?答:可以,执行外部动作是工具的正常职责;调用模型做编排则不属于本框架边界。
- Context 的 sampling 怎么理解?答:它是协议允许的服务端反向请求客户端模型能力,属于协议能力点;具体模型编排仍在客户端一侧。
- 跨分册引用怎么标注?答:在服务端接口处说明调用方职责归属,不展开应用层实现细节。
本节高频题
- MCP 定位与三角色(001、003)
- JSON-RPC 2.0 报文结构(002、023、024)
- initialize 握手与能力协商(006、007、008、012)
- serverInfo 与 instructions(009、043、044)
- 三原语语义边界(013、014、015、016)
- tools/list 与 tools/call 报文(017、018)
- resources/list/read 与订阅(019、020、021)
- prompts/list/get 报文(022)
- 进度、取消、心跳与通知机制(029、030、031、028)
- 三种传输差异与选型(033、034、035、036、040)
- 有状态与无状态 HTTP 模式(038)
- 实例构造与能力自动声明(041、042)
- lifespan 生命周期与 ASGI 挂载(045、046、047、048)
- 错误码分层与协议/业务错误(049、050、051)
- 版本敏感项与验证方法(053)
- 跨语言互通前提(059)