[Feature] Lazy-load MCP tool schemas into context — only inject when tools are needed

[Evan-Kim2028]

Problem

When MCP servers are configured, all tool schemas (names, descriptions, input JSON schemas) are injected into the LLM context at the start of every session. With multiple MCP servers this can consume thousands of tokens of context budget before the user sends a single message.

This leaves less room for conversation history and actual work, and hurts quality on long tasks — especially in sessions that never end up using most of the configured MCP tools.

Related issues

• [Feature request]: allow disabling some of the tools in a given mcp #1177 — disabling specific tools is a partial mitigation, but tool schema injection still happens upfront at session start
• PR perf: streamline startup paths and interactive MCP loading #1486 — deferred async MCP server connection startup (great improvement, but doesn't address schemas being loaded into LLM context)

Proposed solution

Lazy-load MCP tool schemas into the LLM context only when tools are actually needed, rather than injecting all schemas at session start. A few approaches:

1. On-demand discovery: inject a lightweight list_tools stub first; only fetch and inject full schemas when the model determines a tool domain is relevant to the current task
2. Task-scoped injection: analyse the user's first message and only inject schemas for servers likely to be relevant
3. Deferred full load: keep schemas out of the initial context and inject them progressively as tools are invoked

Prior art

• Claude Code uses a ToolSearch deferred-tool primitive — MCP tool schemas are not loaded into context until explicitly fetched, keeping the base context lean
• opencode tracks the same request at [FEATURE]: Lazy/dynamic loading for mcp tools anomalyco/opencode#8277

Impact

Users with many MCP servers configured (10+ servers, 50+ tools) can lose a significant fraction of their context window before any work begins. Lazy loading would make Kimi Code CLI viable for heavily MCP-configured environments without sacrificing context budget.

[TheFox666]

Approach 1 throws away more than it needs to. On my setup, 7 servers and 290 tools: the tool definitions are 295 kB, of which 273 kB is JSON Schema. Names and descriptions together are 22 kB. So there's a middle option: keep names and descriptions, defer only the input schemas. Routing survives, the part that scales doesn't. (Tokens as bytes ÷ 4, ratios not exact counts.)

What it won't fix: out of context, out of mind. Over two days I logged 21 calls to a code-index server against 270 greps into the repos it had indexed. The names were in the prompt the whole time. Dropping descriptions makes that worse.

Numbers and method, my own tool so discount accordingly: https://github.com/TheFox666/mduct#the-context-bill-is-a-side-effect-of-the-pipe