Opt MCP tool schemas into the existing deferLoading pipeline (tool-search style lazy loading, like Claude Code's ENABLE_SEARCH_TOOL)

[sailsgo]

Motivation

dsh-mcp-client registers every discovered MCP tool eagerly (ctx.tools.register(definition) in src/index.ts), so all tool descriptions and input schemas ride on every model request. A single MCP gateway scope can easily expose 50–100 tools; at ~100–400 tokens per schema this adds 15k–30k tokens per request before the conversation starts, and dominates cost for deployments that mount several servers/scopes.

The Harness already has the equivalent infrastructure — it is just not wired into MCP (verified on the 0.2.0-rc.2 desktop runtime):

• @deepseek-ai/dsh-tools accepts a deferLoading flag on registered definitions;
• @deepseek-ai/dsh-llm / dsh-llm-deepseek project it to provider-side defer_loading: true and handle mid-conversation tool-addition developer messages;
• @deepseek-ai/dsh-llm-pi-ai's compat gate already contains supportsToolSearch, supportsMidConvoToolAdditions, supportsMidConvoToolChanges — currently all withhold.

Behavior

Please consider:

1. A dsh-mcp-client config field such as toolMode: "eager" | "deferred", so a server's tool schemas are withheld until the model first references or searches for them (tool-search style), leveraging the existing deferLoading pipeline instead of putting every MCP schema in every request.
2. If deferred discovery is further out, a stopgap per-server includeTools / excludeTools allowlist would already let deployments trim the largest schemas without disabling an entire server.
3. Keep the existing invariants: server-qualified mcp__<server>__<tool> naming, whole-generation atomic swap, and KV-cache-stable prefixes when the tool set is unchanged.

[jannerchang]

Measured data point supporting this proposal (fresh tools/list against a real-world server: REA, a reverse-engineering agent toolkit exposing its full catalog over stdio MCP, measured 2026-10-15):

• 170 tools, total serialized tools payload: 1,954,674 bytes (~1.9 MB)
• Largest single schemas:
  • compare_web_captures — 69,778 B
  • analyze_javascript_application — 44,807 B
  • capture_browser_scenario — 43,165 B
  • compare_application_versions — 35,239 B
  • reconcile_javascript_runtime — 34,269 B

The pattern: the server inlines usage playbooks into descriptions/input schemas, so a single tool can carry more bytes than an entire typical server. With it mounted, DSH reported ~200k tokens of resident context before the first user message; unmounting it dropped that to ~10k (remaining law-search MCP servers).

Two notes relative to the proposal:

1. This strengthens the stopgap ask (item 2): an includeTools/excludeTools allowlist alone would have let me keep REA mounted for reverse-engineering sessions while at least excluding the five largest schemas (~227 KB) — though for a server like this, per-server toolMode: "deferred" (item 1) is the real fix.
2. Per Tool schemas: where they really cost you (prompt-cache order) and what happens if you drop them #9190's cache-order finding (cached prefix is system → tools → messages), whichever deferred mechanism lands should keep the serialized tools array byte-stable per session — provider-side defer_loading satisfies this; client-side mid-conversation appends would re-price the retained history.

[ryan4yin]

Same issue here. Currently I choose to switch to Codex for any tasks that need MCP servers.

[seashot]

Supporting measurement from a different route, plus one sequencing note.

Environment: desktop 0.2.1-rc.2 (Windows), @deepseek-ai/dsh-mcp-client 0.2.1-rc.2, and a @deepseek-ai/dsh-llm-pi-ai route with api: openai-responses, a custom baseURL, and no compat block. Profile mounts several MCP/extension tool groups (canva, playwright browser, univer office, windows computer-use) on top of the built-in office/ops tools.

Measured in one real session (numbers decoded from the session log's request/header events; 4 chars/token as in dsh-token-meter):

resident tool definitions	182
serialized tools array	212,458 chars ≈ 53K tokens
share of the first request (122K prompt)	~43%, before any conversation text
per-step prompt	~122K, re-sent at every step
prefix cache hit on this route	40%, vs 98% in the same session's earlier turns on the built-in provider

Two things this adds to the proposal:

1. The compat gate degrades silently, even on capable routes. dsh-llm-pi-ai only sets updates.toolUpdate = "addition-only" when compat.supportsAdditionalTools || compat.supportsToolSearch is present. A route declared without compat therefore falls back to a full top-level tools list on every request, even when the wire protocol is openai-responses and the gateway would accept anchored additions. Worth (a) documenting the per-model compat fields so deployments can opt in, and (b) surfacing the fallback instead of degrading silently.

2. Cache economics are half the cost. A 40%→98% hit-rate swing on a 122K prompt costs much more than the schema bytes themselves, which is why jannerchang's byte-stability requirement is load-bearing: if toolMode: "deferred" reshuffles or re-serializes the array between steps, the token saving is paid back as cache misses.

Sequencing. #9143 shows deferLoading: true has no activation channel on the DeepSeek Messages API today, so shipping toolMode: "deferred" before an activation path exists would just hide MCP tools. Suggest landing in this order: (a) includeTools / excludeTools allowlist (cheap, no protocol dependency), (b) compat opt-in for addition-only, (c) deferred + tool_search once activation is supported.

+1 from a daily MCP-heavy profile — this is the single largest lever on per-request cost we have.