MCP 插件

MCP 插件让 AI 应用调用另一个程序实现的工具。宿主记录工具描述及执行地址，分发器据此在本地运行内置工具，或经 MCP 客户端向外部服务端发送调用。工具实现仍由服务端保管。

本例要读取项目文件与重试策略笔记。宿主已有 read_file，笔记则在 Notes 服务端。接入其工具，相当于给工具目录增加转发地址：描述说明能请求什么，地址说明交给谁执行。但地址正确不代表所请求的笔记一定存在。

MCP 插件如何扩展工具池

宿主负责协调模型与工具，拥有工具池及连接 Notes 的 MCP 客户端。服务端实现外部工具，可以是本地进程，也可以是远程服务。图中跨越边界只表示离开宿主执行器，不一定访问互联网。这些职责来自 MCP 的架构说明。

这里的“插件”指宿主封装集成配置的方式，MCP 不要求所有应用采用同一种包格式。启用示例集成后，宿主建立 Notes 客户端并发现工具。

MCP 插件逐步演示

默认启用 Notes 集成，请求笔记 n1。两次调用都是预设测试输入，用于观察路由，不代表模型真实选择。

1. 从内置工具开始。 工具池只有 read_file，指向本地执行器。本地、外部执行计数均为 0。创建 Notes 客户端不会调用工具。

2. 发现能力，再列出工具。 宿主发送 server/discover，请求 ID 为 notes-1。服务端返回 tools 能力。接着发送 tools/list，ID 为 notes-2，得到 read_note（字符串参数 id）和 search_notes（字符串参数 query）。此时工具池仍只有一个已注册项，返回的两个描述尚待注册。

3. 注册执行目标。 宿主给外部名称加上 notes. 前缀，同时在路由中保留服务端原名。

工具池现在有三项。前缀是宿主的命名约定，服务端仍收到自己的名称。宿主向模型提供名称、描述、输入 schema，执行器对象留在宿主内部。

4. 执行本地调用。 c1 请求 read_file({"path":"README.md"})。分发器选本地执行器，读取示例文件，得到 Project: Sketchpad，再把观察结果关联到 c1。本地执行 1 次，外部仍为 0。

5. 路由外部调用。 c2 请求 notes.read_note({"id":"n1"})。注册路由选择 Notes 客户端，发送 tools/call：请求 ID 为 notes-3，服务端工具名为 read_note，参数原样为 {"id":"n1"}。

6. 执行并返回。 Notes 在自己的示例集合查找 n1，返回原文 Retry policy: Retry temporary failures up to three times.。完整结果包含 isError: false，响应 ID 为 notes-3。宿主把响应对应到等待中的 c2，再加入观察结果。最终本地执行 1 次，外部执行 1 次。

线路请求 ID 与 c1、c2 调用 ID 属于不同层，由宿主建立映射。MCP 基础协议 定义请求与响应的关联；c1、c2 是宿主记账标识。演示没有生成最终模型回答。

工具已列出，为何仍会失败

保持集成启用，把笔记 ID 改成 missing。发现与注册仍得到同样三项工具，宿主找到路由，客户端发送请求，服务端执行一次 read_note，但查找返回 Note not found: missing，并标记 isError: true。

工具可用回答“能否派发调用”，查找结果回答“数据是否存在”。发现成功不能提前保证后者。MCP 用工具结果承载执行失败；未知服务端工具名等协议错误则通过 JSON-RPC error 响应返回，区别见工具规范。

禁用集成后，无论笔记 ID 是什么，工具池都只有 read_file。c1 仍成功，预设的 c2 探测找不到 notes.read_note，宿主在本地产生可用性错误，没有发送 MCP 请求。不能把它标成服务端响应。

关闭集成和工具可用，笔记缺失 都暂停在路由 c2 前。先预测服务端执行计数是否增加，再播放验证。

修改输入前先定位失败位置

同一 Notes 服务端增加另一个工具时，只需再注册描述与服务端路由，已有客户端可承载调用。分发器仍按名称查找目标，无需为每个新工具另写一套分发流程。

边界情况

• 未接入集成。 内置工具仍保留，改变参数无法补出外部路由。
• 笔记缺失。 工具已执行并返回失败。错误结果成功送达，不是网络丢包。
• 搜索无匹配。 已公布的 search_notes 返回空搜索提示，不标为执行错误。它参与发现，但这两次示例调用只使用 read_note。
• 发现与权限。 已发现的工具仍受宿主策略约束。只读示例策略允许这些调用；权限 课解释那项独立决定。

常见错误

• 把描述当成执行代码。 名称后必须有实现或路由。schema 约束调用形状，不能读取笔记。
• 把宿主别名原样发出。 notes.read_note 是宿主条目名，服务端期望 read_note。
• 把发现计为工具执行。 能力发现和工具列表都不增加执行计数。
• 丢掉错误标记。 结果即使有可读文字，后续处理方仍需要失败信号。
• 断言模型选择了不可用工具。 禁用场景故意注入预设探测，不推断真实模型面对工具列表会如何选择。

本课使用的协议版本

本课采用 MCP 2026-07-28。请求携带协议版本和客户端元数据。宿主选择先用 server/discover 查询支持版本与能力。该调用对客户端可选，不是强制会话握手。旧版协议使用 initialize 与 notifications/initialized。比较不同版本示例时，参见发现契约和版本说明。

模型的简化

本课使用内存宿主、一个模拟服务端、两个固定调用和小型数据集，不替代协议规范或系统训练。没有展开传输、身份认证、权限协商、模型决策、流式传输、重试、分页、缓存、订阅、资源和提示词。

插件包与别名约定属于宿主的教学设计。检查面板显示载荷摘录，生成记录仍保留必需的请求元数据和响应字段。播放秒数表示教学节奏，不是 MCP 延迟测量。