[FEATURE] Defer MCP server instructions on demand, the way ToolSearch already defers tool schemas

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Prior art, checked before filing:

| issue | state | relation |
|---|---|---|
| #7336 | closed, completed | Lazy loading for MCP servers/tools. Shipped as ToolSearch — but for tool definitions only. |
| #11364 | closed, duplicate | Lazy-load MCP tool definitions. Same scope as #7336. |
| #44536 | closed, not planned | Asked to extend the ToolSearch pattern to all context components. Closed by the stale bot for inactivity, with "open a new issue if this is still relevant." This is that issue, narrowed to one component. |
| #43474 | open | Server instructions silently truncated with multiple servers — same field, different failure. |
| #76372 | open | Built-in server instructions exceed the documented 2KB cap. |

No open request covers deferring server instructions specifically. This one does, and only that.

Problem Statement

ToolSearch solved half of the MCP context problem. Tool schemas now load on demand — a real and large win.

The other half didn't move: every connected MCP server's instructions block is injected in full, every session, before the first user turn. It is unconditional. A server whose tools are all deferred still pays its full instruction preamble, so the deferral that ToolSearch buys is partially refunded at startup.

There is no partial lever for it:

• alwaysLoad / tool-search config governs tool definitions, not instructions.
• The only control that touches instructions is enabling or disabling the whole server — binary. Disabling costs the capability entirely.

So an orchestrator that connects ten servers to stay capable pays ten instruction preambles to stay idle. In this session's system prompt that is a visible block for ten servers — several hundred to a few thousand tokens each, some explicitly documenting their own tools in prose that ToolSearch would otherwise have deferred.

Concretely, on our setup: the orchestrator's floor sits around 60k against a 45k target, and the instructions blocks are the largest remaining component we cannot address from the client side. Every client-side lever is exhausted — that number is ours and specific to our config, but the shape is not: it scales with server count for anyone running a broad MCP surface.

Two open issues suggest the field is under-designed generally, not just under-deferred: #43474 (silent truncation with multiple servers) and #76372 (built-ins exceeding the documented cap). A field that is simultaneously unconditional, uncapped in practice, and silently truncated is one worth revisiting as a whole.

Proposed Solution

Treat instructions the way ToolSearch already treats tool schemas: retrievable on demand, not resident by default.

The mechanism already exists and is proven in this codebase — it needs pointing at one more field.

1. Defer by default above a threshold. A server's instructions are replaced at startup by a one-line stub naming the server and what it's for. The body is fetched only when the model actually reaches for that server.
2. Retrieve through the existing path. When ToolSearch resolves a tool belonging to server X, X's instructions come with it — the model already knows it's about to use that server, which is exactly the moment the guidance is worth its tokens.
3. Per-server opt-out. A server whose instructions are genuinely load-bearing at all times keeps today's behaviour:

{
  "mcpServers": {
    "critical-server": { "instructionsLoading": "always" },  // today's behaviour
    "occasional-server": { "instructionsLoading": "deferred" } // stub + fetch on use
  }
}

A sensible default would be deferred above some size (2KB is already the documented cap, so it is a natural line) and always below it — small preambles cost little and deferring them adds a round trip for no gain.

Alternative Solutions

• Disable servers not in use. Today's only option. It trades context for capability, and the whole point of a broad MCP surface is that you don't know in advance which one you'll need. It also can't be decided per-session by the model.
• Ask server authors to write shorter instructions. Doesn't scale, doesn't apply to built-ins (#76372), and pushes a client-side budget problem onto third parties.
• A hard cap with truncation. Already effectively happening, and #43474 shows the failure mode: silent truncation means the model acts on half a contract with no signal that the other half existed. Deferral is strictly better than truncation — same tokens saved, nothing silently lost.
• Extend ToolSearch to every context component at once (#44536's framing). Right direction, too broad to land — which is plausibly why it went not planned. This request is deliberately one field.

Priority

High - Significant impact on productivity

Feature Category

MCP server integration

Use Case Example

A long-running orchestration session connects ~10 MCP servers so the model can reach any of them without a restart: issue tracking, observability, cloud config, docs, code intelligence, calendar/mail.

In a typical turn it uses one.

Today all ten instruction preambles are resident from before the first user message and stay resident through every compaction — they are re-injected into each fresh context window, so the cost is paid again on every page-out, not once per session.

With deferral, that session starts at the stub cost, and the one server it actually touches contributes its instructions at the moment ToolSearch resolves the tool. The capability surface is identical. The resident floor drops by roughly the sum of the nine unused preambles, and it drops again on every subsequent compaction.

That is the same trade ToolSearch already made for schemas, applied to the field sitting next to them.