文档示例提议：用“搜索后读取”演示 MCP catalog 按需披露与调用权限边界

[ct-jaryn]

想讨论一个小范围的使用示例：用“搜索公开资料，再读取选中页面”的连续任务，说明现有 MCP catalog 模式怎样发现、加载契约并调用工具，以及哪些设置决定工具能否被调用。

我已阅读官方 Agent 教程。目前已有 WebUI 添加 HTTP/SSE 服务、headers、超时、工具开关和权限说明；#792已修复鉴权头转发，#1005已加入按需披露。本提议只为这些现有能力补充具体使用过程，不新增传输实现或内置服务商。

拟补充的示例只覆盖以下差异：

1. 对照 eager 和 catalog。 用同一个含搜索、读取两个工具的合成 MCP 服务，对照 MCP 部分直接披露各工具与只披露 search_mcp_tools / invoke_mcp_tool 两个网关的过程。
2. 展示一次完整的按需调用。 search_mcp_tools(action="search") 找到候选 → action="schema" 读取指定 server/tool 的实际 inputSchema → invoke_mcp_tool 按该契约调用；读取网页时再选择对应工具。不硬编码第三方服务的参数，也不把“查到工具”当成成功执行。
3. 列清调用范围。 展示工具关闭、当前调用上下文不允许该工具、参数不符合 Schema 时的结果；说明 catalog 是披露方式，不授予额外权限，也不代替服务端授权。
4. 补一个明确的 Header 例子。 区分 HTTP 的字面量 Authorization: Bearer … 与 stdio 的环境变量配置；不暗示 ${VAR} 或其他环境语法会自动在 Header 展开。示例使用占位值，真实 Key 不进入聊天、仓库或日志。

如果这个范围有帮助，我可以先交付一个使用回环 MCP 服务和合成凭据的可复现例子，再补一段可选的百智云接入说明。该说明会沿用现有 MCP 配置，不增加默认预设、自动启用或新包装插件。若项目希望保持中立，完全可以只保留合成服务例子，把服务专属内容留在个人社区指南。

关联披露：我参与百智云 Agent Toolkit 的集成推广工作。百智云是托管服务，需要用户自己的账号和 Key，工具调用可能计费，模型费用另计；公开客户端示例不代表托管后端开源，也不代表 ChatLuna 官方认可。当前仅核对了源码与已有文档，尚未完成上述 ChatLuna 宿主示例的运行验证或生产调用。

这个具体示例适合补进现有 Agent 文档，还是更适合作为社区独立示例？若现有内容已经足够，我会保持独立指南，不重复提交相同教程。