09 · MCP：怎样让Agent接入文档能力？

MCP统一宿主发现和调用外部能力的方式，宿主与业务服务仍负责上下文选择、权限和执行结果。

本课的位置：MCP位于左侧能力接入层，为工具、资源等提供统一接入方式；任务状态与业务权限仍由应用管理。

下面是教学设例：用户问“文档索引应该从哪里对用户开放”。资料服务有两份相关笔记，Agent需要先搜索“索引”，再读取笔记N1，得到“正式入口只读取已提交版本，不读取暂存内容”，最终给出带来源的回答。

这里需要两项能力：search_notes搜索笔记，read_note读取正文。它们如何被Agent发现、怎样说明输入、出错后如何继续，就是MCP所处的位置。

先判断需不需要这层协议

如果检索实现与Agent在同一个受信进程中，且不需要跨产品复用，直接函数调用最省事。类型、错误和调试链路都在一处，代价是语言与发布周期绑定，换一个宿主要重新适配。

若检索已经是HTTP业务服务，可以沿用现有鉴权与监控，再由宿主提供Tool适配。当前任务可能很快接通，但工具发现、参数描述与调用映射需要自行维护。

当同一能力要被多个Agent宿主采用，或需要统一发现工具、读取资料与提示模板时，MCP适配层更有价值。它增加了连接初始化、能力协商、结构描述和互操作验证，并非每项集成都必然更简单。

工具调用表达要做什么，传输负责把消息送过去。 MCP使用JSON-RPC描述请求、响应与通知，可以通过进程标准输入输出，也可以通过Streamable HTTP传递。MCP服务内部仍可能调用普通HTTP业务接口；使用HTTP不自动等于支持MCP，支持工具也不意味着必须走HTTP。

谁管理模型，谁负责连接？

Host是宿主应用，保存用户任务、模型与治理策略；Client是宿主内的协议连接组件；Server是能力提供方，暴露工具、资源或提示模板。一个宿主可以管理多个Client，各自连接对应Server。

在文档场景中，宿主保存用户问题和对话，Client连接资料Server，Server按权限查询笔记。Server不应自动看见全部对话，也不应获得其他Server的数据。

连接建立后先初始化。Client发起initialize，说明支持的协议版本、能力与实现信息；Server回应自身版本与能力；Client确认可用后发送就绪通知，再开始正常操作。不兼容就按规则处理，不靠反复发送业务请求碰运气。

能力协商表达“双方实现了什么”，不是“当前用户批准做什么”。Server声明提供工具，不代表每位用户都能调用全部工具；宿主允许连接，也不代表任意外部动作都已获准。

搜索之前，先把工具目录读完整

服务返回工具名称、用途和输入结构。search_notes要求query为文字；read_note需要笔记ID。宿主据此把适合当前任务的能力提供给模型。

假设第一页只有search_notes，并带有nextCursor；Client用原样游标继续请求，第二页才获得read_note。只取第一页，Agent就可能找到N1，却没有读取正文的入口。

游标是不透明的后续位置标识，由服务生成，客户端不猜页码、不解析内容，也不把旧会话的游标长期保存。工具目录发生变化时，根据协商的变化通知更新；没有支持这一能力，就采用相应刷新策略。

同名工具也要与所属连接关联。两个服务都叫search，宿主不能因为显示名相同就把请求发错地方。协议规范化消息形式，具体路由仍由宿主管理。

接下来的一次请求，可以用下面的过程理解：

这次修复不需要重建连接。初始化已经完成，错误发生在某次工具输入；修改参数后发出新请求即可。若每个业务错误都重启服务，既增加开销，也可能留下未完成调用。

工具之外，Resources和Prompts有什么用？

Resources是用URI标识的可读上下文资料，例如文档目录、字段说明或一份参考材料。宿主决定哪些内容适合进入当前上下文，URI不一定是浏览器可打开的网页。

Prompts是可发现、可填参数的消息模板，例如“按指定格式生成文档摘要”。取回模板只是获得组织要求的方法，不会自动执行其中的查询或发布动作。

当前任务用搜索与读取工具就能完成，不必为同一段笔记强造三个入口。若用户需要浏览文档目录、选择资料或订阅更新，再由Server实现并声明相应资源能力；具体交互由宿主设计。

工具通常用于选择和执行操作，资源用于组织上下文，模板帮助用户采用某种工作方式。三者可以配合，但不能因模板写着“发布”就视为用户授权。

连接成功以后，还要处理哪些结果？

工具输入的日期、范围或格式错误，可以通过带isError的工具结果返回，让模型调整。未知工具、请求外层结构不符合约定等属于协议错误。网络断线或进程退出又是另一层：可能根本没有收到响应。

三者不能都变成一段普通文字。否则模型可能把错误信息当成检索证据，或把结果未知的写动作再做一次。请求ID用于关联一次通信，不等于第08篇的业务幂等键；重新连接不会撤销已经发生的外部动作。

宿主还要管理超时、取消、迟到响应与连接关闭。某次Run已经结束，稍后返回的搜索结果可以登记，但不能继续推进旧任务。关闭连接也不证明Server背后的外部操作已经停止。

进程标准输入输出传输要求协议消息与普通日志分开；HTTP传输则要处理版本信息、会话、JSON或事件流响应及相应断线语义。它们都需要完整生命周期管理，不能只关注成功调用。

鉴权确认连接代表谁、能访问什么；单次动作授权确认这次具体能做什么。Host限制可见能力，Server检查资源与业务权限，令牌只用于获准目标。工具注解写“只读”也不是安全证明。

最后，N1的正文与来源身份要一起保留。资料后来变化时，还需要版本或读取时间说明当时依据。MCP提供通道，检索相关性、上下文预算和证据是否支持答案，仍是应用的工作。

下一篇Skill讲另一层复用：外部能力已经接入以后，怎样把“整理文档时该按哪些步骤做”组织成可采用、可维护的方法。