Feature: Lazy-load MCP tool schemas to reduce context usage

[emreceviz10]

Problem

All configured MCP server tool schemas are loaded into context at conversation start, regardless of whether they're used. With multiple MCP servers (e.g., Supabase, GitHub, Context7), this can consume ~25k+ tokens just for tool definitions — over 50% of the initial context budget before the user even sends a message.

This leaves significantly less room for actual conversation, code context, and reasoning — especially in longer sessions where context compression kicks in.

Proposed Solution

Lazy-load MCP tool schemas on demand instead of eagerly loading all of them at conversation start.

How it could work:

1. At conversation start, Claude receives only a lightweight summary of available MCP servers (name, description, number of tools) — maybe ~200 tokens per server instead of ~5-10k
2. When Claude determines it needs to use a tool from a specific MCP server, the full tool schemas for that server are loaded into context at that point
3. Optionally, servers could be marked as "always eager" vs "lazy" in the MCP config for frequently-used servers

Example summary vs full load:

# Summary (~50 tokens)
Supabase MCP: 22 tools for database operations, migrations, edge functions, branches

# Full schema (~8k tokens)  
[all 22 tool JSON schemas with parameters, descriptions, enums...]

Impact

• Context savings: ~20-25k tokens freed up per conversation for users with 3+ MCP servers
• Longer effective conversations before context compression
• Better scaling as users add more MCP servers — cost grows linearly today but would stay nearly flat
• No functionality loss — all tools remain available, just loaded when needed

Current Workarounds

• Manually toggling MCP servers on/off per session (tedious)
• Splitting configs into "always-on" vs "on-demand" groups
• Accepting the context tax and working with less headroom

None of these are great. The platform should handle this transparently.

Additional Context

Measured in a real project with Supabase + GitHub + Context7 MCP servers configured:

• Tool definitions: ~25k tokens (~53% of initial context)
• System instructions: ~15k tokens
• Project context (CLAUDE.md, git status): ~2.5k tokens
• Actual conversation: starts with less than half the context available

[github-actions]

Found 3 possible duplicate issues:

1. Feature: Lazy MCP tool group loading to reduce context usage #23508
2. Feature Request: Lazy-Loading / On-Demand MCP Tool Registration #16826
3. Feature Request: On-demand plugin loading to reduce token overhead #23522

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[github-actions]

This issue has been automatically closed as a duplicate of #23508.

If this is incorrect, please re-open this issue or create a new one.

🤖 Generated with Claude Code

[github-actions]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.