On-demand MCP resources and scoped server instructions
按需 MCP 资源与作用域服务器指令
MCP servers expose documents and URI templates separately from tools. A tools-only client cannot read those documents or use a server that offers resources without tools. Servers also supply instructions that explain how their operations fit together; ignoring those instructions removes context needed to choose and combine operations.
English
Problem
MCP servers expose documents and URI templates separately from tools. A tools-only client cannot read those documents or use a server that offers resources without tools. Servers also supply instructions that explain how their operations fit together; ignoring those instructions removes context needed to choose and combine operations.
Decision
mcp-resources provides three shared tools for listing resources, listing templates, and reading a URI. Each requires an explicit configured server name. When system-prompt assembly is composed, a literal section derives the caller-visible names from the dispatch registry, so resource-only servers remain discoverable without server instructions. The existing system-message log records those names; provider disposal removes them from later assemblies. The execution path resolves that server in the calling agent's scope before dispatch; provider registrations use reversible Cordis effects.
The profile availability decision supersedes the separate opt-in resource mount and owns conditional tool visibility. This note retains the resource operations, result representation, and instruction decisions. Each mcp-client instance owns its connection and registers a resource provider when the service is mounted. The SDK returns empty resource and template lists when the server lacks the resource capability; unsupported reads fail. Servers need not advertise tools. The official SDK owns protocol operations; list cursors and resource URIs remain opaque, and an explicit cursor requests one page while an omitted cursor lets the SDK collect pages.
Resource results preserve the complete canonical JSON for programmatic callers. Native text includes the configured server name and returned URI metadata. String-valued blob fields become binary descriptions instead of inline base64. Existing tool-result logging records the model projection; this package does not create a parallel resource log or a binary attachment store.
Server instructions contribute one scoped literal system-prompt section per configured MCP server. The existing logged system message records the assembled instructions that reach the model. Resource contents remain on demand, so connecting a server does not preload its documents into the prompt.
This decision supersedes only the resource deferral in the original MCP client note. That note remains active because its tool naming, canonical-result, environment, and transport rationale still apply. Prompts remain unsupported.
Alternatives considered
Separate resource tools for every server. Rejected because every server would add another set of identical operation schemas. Three shared tools keep the catalog small; explicit server arguments and execution-time scope resolution select the provider.
Automatically inject or refresh resource contents. Rejected because resource listings do not establish which documents a task needs. On-demand reads let the model choose content, avoid unrelated documents, and retain the result it actually used. Resource subscriptions and update notifications remain unimplemented.
Project binary resources as native content. Deferred because images and audio require coordinated capability, persistence, and presentation support. Preserving canonical bytes while rendering metadata supplies useful text-resource access without inventing another content mechanism.
Add MCP-specific durable events for instructions and reads. Rejected because the assembled system message and tool results already record the model-visible inputs. A second event authority would duplicate those records.
Verification
The resource tests pin all three operations, unchanged cursors, required server arguments, unavailable-server rejection, scoped provider selection, duplicate rejection, disposal, and lossless canonical results with binary-free model text. They also verify caller-visible server names without server instructions, literal names, and removal of prompt context when providers or the resource service are disposed. The tool-result contract owns the distinction between execution-time values and recorded model content.
Consequences
Resource-only servers become useful without adding per-server model tools. Caller-visible server names and server instructions add prompt tokens; resource documents add tokens only when read. Shared schemas stay stable during connection failures while a caller-visible client remains configured, but a call still fails when its selected server is unavailable. Binary resources remain programmatic values, and pagination follows the SDK.
中文
问题
MCP 服务器将文档与 URI 模板作为独立于工具的能力暴露。只支持工具的客户端无法读取这些文档，也无法使用仅提供资源而不提供工具的服务器。服务器还提供指令来解释各项操作如何配合；忽略这些指令会丢失选择和组合操作所需的上下文。
决策
mcp-resources 提供三个共享工具，用于列出资源、列出模板及读取 URI。每个工具都要求显式指定已配置的服务器名称。组合包含系统提示词装配时，字面段落从派发注册表获取调用方可见的名称，因此没有服务器指令的纯资源服务器仍可被发现。已有的系统消息日志记录这些名称；提供方释放后，后续组装会移除其名称。执行路径在派发前于调用 agent 的作用域中解析该服务器；提供方注册使用可撤销的 Cordis effect。
Profile 可用性决策取代单独启用资源服务的挂载方式，并拥有工具条件可见性。本笔记保留资源操作、结果表示与指令决策。每个 mcp-client 实例拥有自己的连接，并在服务已挂载时注册资源提供方。服务器缺少资源能力时，SDK 返回空的资源列表与模板列表；不受支持的读取会失败。服务器无需声明工具能力。官方 SDK 负责协议操作；列表游标与资源 URI 保持不透明；显式游标请求一页，省略游标则由 SDK 汇总各页。
资源结果为程序化调用方保留完整规范 JSON。Native 文本包含已配置的服务器名称及返回的 URI 元数据。字符串值的 blob 字段变为二进制说明文字，不内联 base64。已有的工具结果日志记录模型投影；本包不创建并行的资源日志或二进制附件存储。
服务器指令为每个已配置的 MCP 服务器贡献一个作用域内的字面系统提示词段落。已有的系统消息日志记录最终送达模型的组装后指令。资源内容保持按需读取，因此连接服务器不会将其文档预加载到提示词中。
本决策仅取代原 MCP 客户端记录中延后资源支持的决定。该记录继续保留在活跃目录，因为其工具命名、规范结果、环境与传输理由仍然适用。Prompts 仍不受支持。
曾考虑的替代方案
为每台服务器创建独立的资源工具。 不予采用，因为每台服务器都会增加另一套相同的操作 schema。三个共享工具保持较小的工具目录；显式服务器参数与执行时的作用域解析负责选择提供方。
自动注入或刷新资源内容。 不予采用，因为资源列表无法确定任务需要哪些文档。按需读取让模型选择内容，避免读取无关文档，并保留实际使用过的结果。资源订阅与更新通知仍未实现。
将二进制资源投影为原生内容。 延后，因为图片与音频需要能力、持久化和呈现的协同支持。保留规范字节并渲染元数据，可以提供实用的文本资源访问，而无需另建内容机制。
为指令和读取添加 MCP 专属持久事件。 不予采用，因为组装后的系统消息与工具结果已经记录模型可见输入。第二个事件权威会重复这些记录。
验证
资源测试固定了三个操作、原样游标、必填服务器参数、不可用服务器拒绝、作用域提供方选择、重复注册拒绝、释放，以及保留完整规范结果但不向模型文本写入二进制的行为。它们还验证无服务器指令时调用方可见的服务器名称、名称的字面保留，以及提供方或资源服务释放时移除提示词上下文。工具结果契约拥有执行时值与已记录模型内容之间的区分。
后果
仅提供资源的服务器无需添加按服务器区分的模型工具即可使用。调用方可见的服务器名称和服务器指令增加提示词 token；资源文档仅在读取时增加 token。只要调用方可见的客户端仍已配置，连接失败期间共享 schema 就保持稳定，但所选服务器不可用时调用仍会失败。二进制资源仍是程序化值，分页遵循 SDK。