MCP Python SDK · 第 7 章交互式能力:引导、采样与多轮往返

文档摘要

MCP Python SDK · 第 7 章交互式能力:引导、采样与多轮往返章节摘要:到目前为止,我们的工具都是「模型一发请求,服务端一口气算完返回」。但有一类真实需求让这个模式失效——工具执行到一半,需要问用户一个问题才能继续。比如转账工具要确认收款人、删除工具要二次确认、配置工具要用户从选项里挑一个。本章讲的就是 MCP 的交互式能力。核心是引导填写(Elicitation)——一种让工具在执行中途向用户反问的机制。我们会讲清它的两种模式(表单与 URL),以及 v2 里最重要的变化:在现代协议(2026-07-28)下,服务端不能直接发起请求,引导填写要靠返回对象、配合多轮往返(MRTR)机制实现。

MCP Python SDK · 第 7 章交互式能力:引导、采样与多轮往返

章节摘要:到目前为止,我们的工具都是「模型一发请求,服务端一口气算完返回」。但有一类真实需求让这个模式失效——工具执行到一半,需要问用户一个问题才能继续。比如转账工具要确认收款人、删除工具要二次确认、配置工具要用户从选项里挑一个。本章讲的就是 MCP 的交互式能力。核心是引导填写(Elicitation)——一种让工具在执行中途向用户反问的机制。我们会讲清它的两种模式(表单与 URL),以及 v2 里最重要的变化:在现代协议(2026-07-28)下,服务端不能直接发起请求,引导填写要靠 Resolve 返回 Elicit 对象、配合多轮往返(MRTR)机制实现。顺带覆盖采样(Sampling,工具反过来请客户端做一次 LLM 补全)与根(Roots)这两个已显弃用趋势但仍在工作的能力。读完本章,你能让一个工具安全地获取用户输入,而不是盲目执行或失败。

学习目标

阅读完本章,你应当能够:

区分引导填写的表单模式(ctx.elicit / Resolve 返回 Elicit 带结构化 Schema)与 URL 模式(elicit_url,跳转外部页面)。
解释 v2 里引导填写的现代实现路径——Resolve 返回 Elicit 对象,通过多轮往返(MRTR) 让客户端下次带答案回来,而非服务端直接发起请求。
说清为什么 2026-07-28 协议移除了「服务端发起请求」,以及这对引导填写实现的影响(legacy 连接仍可用 ctx.elicit)。
描述采样(Sampling) 与根(Roots) 这两个已显弃用趋势但仍在工作的能力,以及官方推荐用什么替代。
在「需要用户输入」的场景里,判断该用引导填写、还是改用提示词、还是预先在工具参数里要求。

核心概念速览

整章逻辑可浓缩为一句话:引导填写让工具从「一问一答的纯函数」升级为「执行中能反问的对话单元」——而 v2 的关键变化是,这种反问在现代协议下不再靠服务端直接发起,而是靠多轮往返让客户端「下次带答案回来」,这让协议更简单、也更安全。

子章节导航

01 引导填写:工具执行中途的反问

用一个「转账前确认收款人」的例子,讲清引导填写的动机——有些信息只在执行到一半时才该问(如「金额超过 1 万,确认继续?」)。对比「预先在工具参数里要求」的局限,说明为什么需要中途反问的能力。

02 两种模式:表单与 URL

表单模式(elicit 带 Schema)让宿主弹出一个结构化表单;URL 模式(elicit_url)让宿主跳转一个外部页面,用户在那里完成交互后回跳。讲清两者的适用场景——表单适合简单确认,URL 适合需要 OAuth、富交互、复用现有 Web 流程的场景。

03 现代路径:Resolve 返回 Elicit 与多轮往返

本章的硬核核心。讲清 v2 在 2026-07-28 协议下的新机制:服务端不能直接发起请求,所以引导填写要靠 Resolve 解析函数返回一个 Elicit 对象;SDK 把它转成「请求返回一个问题」,客户端下次重试时带上用户的答案,工具继续执行——这就是多轮往返(MRTR)。对比 legacy 连接上 ctx.elicit 的直接发起,理解取舍。

04 采样与根:已弃用趋势但仍在工作

采样(Sampling)让工具反过来请客户端做一次 LLM 补全;根(Roots)让客户端告知服务端工作区文件夹。这两个能力在 2026-07-28 已显弃用趋势(官方建议用 provider API 与显式参数替代),但仍能工作。讲清它们的现状与迁移方向,避免你在新代码里过度依赖。

05 进度上报与日志:单向通知

收尾性的一节。讲清工具执行中如何用 ctx.report_progress 上报进度、用 Python logging 模块写日志(被 SDK 转成通知发给客户端)。这两个是「不需要回答」的单向通知,与引导填写的「需要回答」形成对照。

子章节之间的逻辑关系

本章遵循「认识需求 → 看懂模式 → 理解现代机制 → 厘清弃用项 → 补全通知」的递进,围绕「工具与外界的双向交互」层层展开:


引导填写动机 (01) ── 为什么需要中途反问
   │
   ▼
两种模式 (02)    ── 表单与 URL,各适用什么
   │
   ▼
现代路径 (03)    ── Resolve + Elicit + MRTR,全书最微妙的变化
   │
   ▼
采样与根 (04)    ── 已弃用趋势,知道即可,新代码慎用
   │
   ▼
进度与日志 (05)   ── 单向通知,与「需要回答」对照
   │
   ▼
第 8 章:从「工具内部」转向「工具怎么传输」——传输层

认识需求是前提,看懂两种模式让你知道能问什么,理解现代机制让你在 v2 里写对代码(这是最容易踩坑的地方),厘清弃用项让你不在新代码里埋技术债,进度与日志补全「不需要回答」的另一类交互。第 03 节是全书最微妙的部分,直接关联 v2 协议的核心变化。

前置知识与后续延伸

前置知识:

第 6 章的 Context 与 Resolve 机制(本章是它们的高级用法)
第 2 章的协议版本概念(理解 legacy 与现代连接的差异)
对 OAuth 流程有概念(第 02 节 URL 模式会用到)

本章为后续章节奠定的基础:

多轮往返(MRTR)概念会在第 9 章(客户端 mode 协商)再次出现
Resolve 返回 Elicit 的写法是第 6 章依赖解析的进阶应用
采样与根的弃用趋势会提示读者:第 11 章(认证)等新机制才是未来方向
进度上报机制会在第 10 章(客户端订阅)被引用

MCP Python SDK · 第 7 章 交互式能力:引导、采样与多轮往返

文档摘要