Feature Request: Lazy Loading for MCP Servers and Tools (95% context reduction possible)

Found 3 possible duplicate issues:

1. https://github.com/anthropics/claude-code/issues/6638
2. https://github.com/anthropics/claude-code/issues/7172
3. https://github.com/anthropics/claude-code/issues/3036

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

I've created a proof-of-concept implementation demonstrating this lazy loading system:

🔗 Repository: https://github.com/machjesusmoto/claude-lazy-loading

The implementation shows:

• ✅ 95% token reduction (from 108k to 5k)
• ✅ Working registry generation from MCP configs
• ✅ Intelligent keyword-based loading
• ✅ Preload profiles for common workflows
• ✅ Real-time token tracking

This could be integrated into Claude Code to dramatically improve the experience for power users with multiple MCP servers configured.

@machjesusmoto How does it work? Does it change what mcps / tools are visible when the /mcp command is invoked?

I think this is definitely a must to properly support MCP servers. I was thinking just giving defined Agents the ability to keep their own MCP server references (and being able to select only a sub-set of tools from any given MCP server). Then, for example, if I wanted to implement one of my Linear tasks it would call an Agent ("Implement Linear task KEY-123") with the MCP tools in its context for that specific task and not bloat the main thread with context.

Thank you for the feedback! Let me address the questions:

@lukemmtt - How it works

The proof-of-concept creates a lightweight registry (~500 tokens) that replaces loading all MCP tools upfront:

1. At startup: Only the registry loads (5k tokens vs 108k)
2. During conversation: The system analyzes input for keywords
3. On-demand loading: Only required tools are loaded when detected
4. Caching: Loaded tools stay in memory for the session

Currently, it's a simulation showing what's possible. The /mcp command would still show all configured servers, but only the registry would consume tokens until tools are actually needed.

@wizardlyluke - Agent-specific MCP servers

That's a brilliant approach! Agent-scoped MCP servers would be even more efficient. My implementation could extend to support:

{
  "agents": {
    "linear-implementer": {
      "mcp_servers": ["linear", "github"],
      "auto_load": false
    }
  }
}

Regarding Duplicates

While related issues exist (#6638, #7172, #3036), this implementation offers:

1. Working code: Not just a request, but functioning proof-of-concept
2. 95% reduction achieved: Concrete metrics showing feasibility
3. Keyword-based loading: Intelligent detection beyond manual control
4. Registry approach: Minimal overhead solution that scales

The key differentiator is having working code that demonstrates the solution. This could help accelerate implementation by providing a reference.

Test It Yourself

git clone https://github.com/machjesusmoto/claude-lazy-loading.git
cd claude-lazy-loading
python3 optimization/lazy-loader.py stats

Happy to collaborate with others experiencing this issue to refine the approach!

Regarding Duplicate Status

After reviewing the related issues, I believe this should remain open as it provides unique value:

Issue Comparison

#3036 - Reports the problem ("MCP servers eat context")
#6638 - Requests dynamic loading/unloading
#7172 - Proposes token management improvements

#7336 (This) - Provides working implementation with:

• 📦 Functional code: https://github.com/machjesusmoto/claude-lazy-loading
• 📊 Proven metrics: 95% reduction achieved
• 🔧 Registry approach: Novel solution using lightweight index
• 🎯 Keyword detection: Intelligent loading based on context

Why Keep Open

1. Solution, not just problem: Others identify the issue; this provides a solution
2. Reference implementation: Gives Claude team concrete code to work from
3. Community testable: Others can validate the approach with their configs
4. Different approach: Registry-based vs manual loading/unloading

I suggest we could:

• Link these issues together as "related"
• Keep this open as the "implementation reference"
• Use others for requirements gathering

What do you think @lukemmtt @wizardlyluke? Should we consolidate discussion or keep the implementation separate?

Seems like a neat implementation, I'll give it a shot this week.

I've personally been getting by with less refined approach: a custom-built script that I made that adds/removes mcps from the actual claude config files (using a separate json file to persistently store the mcp configs)—the obvious caveat being that I still need to restart the claude code session after each change for it to take effect; your solution sounds much more elegant.

As for consolidating the discussions or not, that's reasonable, but more importantly would be to just mention your solution in the other discussions to tie everything together, and maybe share it in the anthropic / claude / claude code subreddits for visibility, rather than wait for moderator intervention, which seems sparse in this noisy forum.

@lukemmtt Thanks for trying it out! Your config-swapping approach is clever - it's actually complementary to what I built.

Current Limitations

You're absolutely right that this can't truly lazy-load without Claude Code native support. What it does:

1. Shows what's possible: Demonstrates 95% reduction is achievable
2. Simulates the behavior: Shows which tools would load for given inputs
3. Provides the blueprint: Registry structure and loading logic ready for integration

Combining Approaches

Your script + this registry could work together:

# Use lazy-loader to analyze what's needed
python3 lazy-loader.py analyze "building React components today"
# Output: Would load context7, magic

# Use your script to update config with just those MCPs
your-script enable context7 magic

# Restart Claude with minimal MCPs loaded

Next Steps

Great idea about cross-posting! I'll:

1. ✅ Comment on related issues (#3036, #6638, #7172) - Done!
2. ✅ Post to r/ClaudeLLM and r/AnthropicClaude
3. ✅ Share in Claude Discord if there's a channel for it

The real win would be getting this integrated natively. Until then, your config-swapping + my analysis tool might be the best workaround.

Would you be interested in combining efforts? We could:

• Add config manipulation to the lazy-loader
• Auto-generate minimal configs based on task analysis
• Create a wrapper that restarts Claude with optimized MCPs

lol... @machjesusmoto , you got me. Freeze all motor functions

It is worth noting that a runtime MCP Toggle feature has been introduced in Claude Code 2.0.10:

## 2.0.10 - Rewrote terminal renderer for buttery smooth UI - Enable/disable MCP servers by @mentioning, or in /mcp - Added tab completion for shell commands in bash mode - PreToolUse hooks can now modify tool inputs - Press Ctrl-G to edit your prompt in your system's configured text editor - Fixes for bash permission checks with environment variables in the command

Dynamically-loading MCPs is still an interesting concept, but the new ability to enable by "@mentioning" is almost equally valuable for my needs.

It is worth noting that a runtime MCP Toggle feature has been introduced in Claude Code 2.0.10: > ## 2.0.10 > > Rewrote terminal renderer for buttery smooth UI > Enable/disable MCP servers by @mentioning, or in /mcp > Added tab completion for shell commands in bash mode > PreToolUse hooks can now modify tool inputs > Press Ctrl-G to edit your prompt in your system's configured text editor > Fixes for bash permission checks with environment variables in the command Dynamically-loading MCPs is still an interesting concept, but the new ability to enable by "@mentioning" is almost equally valuable for my needs.

Wouldn't this feature be the equivalent (though faster and not requiring Claude Code restart) of just removing/adding them manually? The true power of using many MCPs will be when you can get them added per defined agent, or allow the main agent to enable/disable them itself by knowing which MCPs it could have available.

Yes exactly, I would like my main agent to not have any mcp servers and then have specialized research agents etc.. who have mcp severs and use them for example for more detailed research (github mcp, linear, context7) and then report back a condensed summary to the main agent. So the main session always stays clean

2.0.10 made my work on machjesusmoto / mcp-toggle redundant, but then they delivered plugin extensibility in 2.0.12. A plugin system makes makes the project's overarching goal possible when it was previously only a theoretical PoC (machjesusmoto / claude-lazy-loading
So, with a lot of caffeine and a little luck, I'll have functional "lazy loading & unloading with a registry being all that's held in context at launch" code to test soon.

I'd like to second @EugenEistrach 's idea of being able to enable select MCPs for specific subagents, while leaving it disabled for the main agent. Currently if you disable it in the main agent, then you cannot enable it for any subagent.
I understand that there is a security aspect here so subprocesses can't have great privileges than parent processes. I suppose a true lazy-load would work, but something deterministic would be ideal.

https://www.anthropic.com/engineering/advanced-tool-use Hopefully support for this gets added to Claude Code soon 🤞

Update: Anthropic Released an Official API Solution

On November 24, 2025, Anthropic released the Tool Search Tool beta feature that directly addresses this problem.

How It Works

| Approach | Token Usage |
|----------|-------------|
| Traditional (all tools upfront) | ~77K tokens |
| With Tool Search Tool | ~8.7K tokens |
| Reduction | 85% |

Accuracy Improvements

• Opus 4: 49% → 74%
• Opus 4.5: 79.5% → 88.1%

API Usage

client.beta.messages.create(
    betas=["advanced-tool-use-2025-11-20"],
    tools=[
        {"type": "tool_search_tool_regex_20251119", "name": "tool_search_tool_regex"},
        {
            "name": "mcp__server__tool",
            "description": "...",
            "input_schema": {...},
            "defer_loading": True  # Not loaded until searched
        }
    ]
)

Proposed Claude Code Integration

Since this is now a first-party Anthropic feature, it would be great to see Claude Code CLI support via:

Option 1 - Global config:

{
  "betaFeatures": ["advanced-tool-use-2025-11-20"],
  "toolSearch": {
    "enabled": true,
    "defaultDeferLoading": true
  }
}

Option 2 - Per-server config:

{
  "mcpServers": {
    "my-server": {
      "command": "...",
      "deferLoading": true,
      "alwaysLoadTools": ["critical_tool"]
    }
  }
}

Option 3 - Auto-enable when MCP tool count exceeds a threshold (e.g., 20+ tools)

References

• Anthropic Blog: Advanced Tool Use
• Tool Search Tool Docs
• Cookbook Example

+1 to see how and when claude code will implement this

@ everyone try this: https://github.com/anthropics/claude-code/issues/12836#issuecomment-3629052941

Basically:

1. Add the following to your shell file (~/.zshrc, ~/.bashrc, etc)

```bash

Claude Code - Enable experimental MCP-CLI for reduced token consumption

export ENABLE_EXPERIMENTAL_MCP_CLI=true

2. Make sure you have claude code version > `2.0.62`.
3. Enjoy what you see in /context
😊

Running into the same issue and gald to see this work and active development, I would like to chip in an idea on adding a lightweight router model for tool selection for your consideration.

95% token reduction already is awesome, but strict adherence to predefined keywords might hinder some users. Thus -->

Proposed Enhancement: Phase 4 - Intelligent AI Router

The Problem with Static Keyword Matching

While keyword triggers work well for explicit mentions (e.g., "docker" → load docker-mcp), they have limitations:

• Implicit requests: "Show me what containers are running" (no "docker" keyword)
• Multi-domain tasks: "Email the team about the database migration" (needs both gmail + database tools)
• Ambiguous keywords: "push" could mean git, docker, notifications, etc.
• Manual configuration: Requires users to define all triggers upfront

Solution: Two-Phase Architecture with Lightweight Model Router

Phase 1: Lightweight Router (Haiku/Fast Model)

User prompt → Haiku analyzes intent
              ↓
         Tool catalog scan (name + description only)
              ↓
         Intelligent tool selection
              ↓
         Returns minimal tool set

Phase 2: Main Model (Sonnet/Opus)

User prompt + selected tools only → Execute task

How It Works

1. At Session Start

// Haiku loads ultra-lightweight tool catalog (~2-3k tokens)
{
  "catalog": [
    {
      "server": "docker-mcp",
      "tool": "list-containers",
      "description": "List all Docker containers",
      "tags": ["docker", "containers", "processes"]
    },
    {
      "server": "google-workspace",
      "tool": "send_gmail_message",
      "description": "Send an email via Gmail",
      "tags": ["email", "gmail", "communication"]
    }
    // ... all tools as lightweight entries
  ]
}

2. On User Input

User: "Show me what containers are running and email the status to ops@company.com"

Haiku Router:
1. Analyzes prompt semantics (not just keywords)
2. Identifies intents: [container_listing, email_sending]
3. Searches catalog for relevant tools
4. Returns: [docker-mcp::list-containers, google-workspace::send_gmail_message]

Main Model:
- Receives only 2 tool definitions (~1k tokens)
- Executes task with 98%+ context efficiency

3. Fallback Mechanism

If Router misses tools:
  → Main model requests additional tools mid-conversation
  → Router re-analyzes with conversation context
  → Tools load on-demand
  → No session restart needed

Integration with Your Registry System

Your POC already has the foundation! The enhancement would be:

{
  "optimization": {
    "lazyLoading": true,
    "loadingStrategy": "ai-router",  // NEW: "keywords" | "ai-router" | "hybrid"
    "routerModel": "haiku",          // NEW: Fast, cheap model for routing
    "fallbackToKeywords": true,      // NEW: Use keywords if router unavailable
    "maxInitialTokens": 3000,
    "cacheMinutes": 30
  },
  "mcpServers": {
    "docker-mcp": {
      "lazyLoad": true,
      "triggers": ["docker", "container"],  // Fallback keywords
      "semanticTags": ["containerization", "processes", "services"]  // NEW: For AI router
    }
  }
}

Implementation Phases

Phase 4.1: Basic AI Router

• Haiku analyzes user prompt
• Selects tools from catalog based on semantic understanding
• Main model receives selected tools only

Phase 4.2: Context-Aware Routing

• Router considers conversation history
• Predictive preloading based on workflow patterns
• Learning from tool usage (which tools actually get used)

Phase 4.3: Hybrid Intelligence

• Combines AI routing + your keyword triggers
• Falls back to keywords if AI router is uncertain
• User can override with explicit @server mentions

Benefits Beyond Keyword Matching

| Feature | Keyword Matching | AI Router |
|---------|------------------|-----------|
| Explicit mentions | ✅ Excellent | ✅ Excellent |
| Implicit requests | ❌ Misses | ✅ Handles |
| Multi-domain tasks | ⚠️ Partial | ✅ Optimizes |
| Context awareness | ❌ No | ✅ Yes |
| Ambiguity resolution | ❌ No | ✅ Yes |
| Setup effort | ⚠️ Manual triggers | ✅ Zero config |
| Token overhead | ~5k registry | ~3k catalog |

Real-World Example

Scenario: "Check if the deployment is healthy and notify the team"

Keyword Approach:

Triggers: deployment? notify? team?
→ Might load all of: kubernetes, docker, slack, email, github
→ 5-10k tokens for tools user might not need

Discussion Questions

1. Would you consider such an AI router enhancement to your POC?
2. If so, would you think of it as a plugin to your registry system or rather a integrated core feature?
3. Any concerns about the additional Haiku API call overhead vs. token savings?

---

Technical Notes

Edge Cases to Handle:

• Router uncertainty → load broader tool set + use conversation context for refinement
• Consider user overrides to limit tool set to consider by router model by limiting to specific mcp servers by name → Explicit @server mentions limit to these tools considered by router model which then subsets to the tools used for main model call
• Offline/API unavailable/model uncertainty what the best choice would be or lack of adequate tools among the user-subset mcp server(s) → Fall back to keyword matching

Looking forward to hear if this might be of interest and add useful functionality to the keyword registry approach!

Thanks @machjesusmoto for this excellent feature request and the detailed technical proposal! The discussion here has been very insightful.

My use case adds another dimension: multi-project MCP management with RAM constraints. While most comments focus on context window savings, I'm hitting hard memory limits running Claude Code on a dedicated "AI machine", having 16 GB RAM with multiple projects requiring different MCP combinations. Using a mini PC for my AI projects maybe wasn't such a good idea after all.

---

Additional Use Case: Multi-Project MCP Management with Resource Constraints

I'm running Claude Code on a resource-limited machine (16 GB RAM) managing multiple projects, each requiring different MCPs:

• webapp-frontend: github, postgres-mcp, redis-mcp
• devops-automation: docker, kubernetes-mcp, aws-mcp, terraform-mcp
• data-pipeline: bigquery-mcp, snowflake-mcp, dbt-mcp
• Global: github, slack-mcp

Current problems:

1. Each MCP uses 50-150 MB RAM - loading all simultaneously exhausts available memory
2. No way to start/stop MCPs during a session without full restart
3. No tracking of which MCPs are actually being used
4. Tasks spanning multiple sessions require manual MCP lifecycle management

Workaround I've implemented:

• Manual tracking in SESSION_NOTES.md with (TEMPORARY) markers
• Documented procedures for MCP start/cleanup in PROJECT_RULES.md (rules shared by _all_ projects)
• This is error-prone and adds significant overhead

Desired behavior:

1. MCPs load on-demand when their tools are first invoked
2. Optional: MCP profiles per project that can be switched without restart
3. Ability to unload unused MCPs to free resources
4. Session-persistent MCP state (don't restart MCPs on context refresh)

This would enable efficient multi-project work on resource-constrained machines.

Given a tool tool, how about a skill skill, a tool/skill skill, or a skill/tool tool?

nice

Adding a data point: on a real project with GSD workflow agents + custom agents + skills, measured ~20% context consumed at session start before typing anything.

After manually deleting unused agents and trimming CLAUDE.md files, got it down to ~9%. But agents I actually want to keep (just not every session) still cost ~3-5% of context permanently.

The current workaround is moving agent files to a disabled folder and back — functional but defeats the purpose of having an integrated ecosystem. Lazy-loading agent/skill descriptions (name-only in system prompt, full description on spawn) would solve this cleanly.

Real-world data from an enterprise iOS dev environment (1M context, Opus 4.6)

Adding concrete numbers from a production setup with 9 MCP servers configured for iOS development at Microsoft:

| MCP Server | Tools | Tokens | Notes |
|---|---|---|---|
| azure-devops | 77 | ~17.2K | Core workflow, can't remove |
| xclaude-plugin (plugin) | 59 | ~13.2K | 36 are duplicates (see below) |
| azure-mcp | 55 | ~12.3K | Rarely used for iOS dev |
| IcM-MCP | 20 | ~4.5K | On-call engineering |
| cupertino | 10 | ~2.2K | Apple docs search |
| bluebird | 5 | ~1.1K | Code search |
| microsoft-docs-mcp | 3 | ~0.7K | MS docs |
| ESChat | 3 | ~0.7K | Internal knowledge base |
| workiq | 2 | ~0.4K | M365 Copilot |
| Total | 234 | ~53K | 5.3% of 1M context |

Even on a 1M context window, 53K tokens of tool definitions is painful -- it's context that could hold ~100 files of source code instead.

The plugin duplication problem makes this worse. The xclaude-plugin registers 59 tools across 8 categories (xc-setup, xc-build, xc-interact, xc-ai-assist, xc-launch, xc-testing, xc-meta, xc-all), but only 23 are unique. The xc-all category is a superset of all others. The category system was designed so agents pick the smallest needed set, but since everything loads at startup, you pay for all 59 regardless.

What I'd want from lazy loading:

1. MCP servers connect at startup (for health/auth) but don't inject tool schemas into context until first use
2. A lightweight registry (~50 tokens per server: name + one-line description) lets Claude decide when to load a server's full tool set
3. Plugin categories like xclaude-plugin's should deduplicate -- load xc-all OR the individual categories, never both

This is the single highest-ROI improvement for power users with enterprise tooling.

Built a userland solution for this — an MCP gateway that replaces N tool schemas with 3-4 dispatch tools.

Instead of registering each MCP server directly, you register a single gateway server that proxies gw("account", "tool_name", {params}) to the right upstream MCP server on demand.

My setup went from 644 tool schemas (~57K tokens) to 7 schemas (~6.2K tokens) — 89% reduction.

Two patterns included (~150 LOC each):

1. CLI Dispatch — for upstream servers with --cli mode (subprocess per call)
2. Persistent MCP Client — for servers without CLI mode (keeps connections alive, lazy connect, auto-reconnect)

Both support multi-account routing, tool discovery with caching, and batch execution. Works with any upstream MCP server.

Open source (MIT): https://github.com/block-town/mcp-gateway

This has shipped and is now the default behavior — no configuration needed.

What changed:

• All tool definitions (MCP + built-in) are now lazy-loaded by default. The model receives only tool names upfront, and fetches full schemas on demand via the ToolSearch tool.
• MCP tool auto-deferral shipped first (v2.1.7, when >10% of context), then expanded to defer all tools unconditionally.
• Your "39.8k tokens for MCP tools + 22.6k for system tools" example now shows up as a handful of name-only lines at conversation start, with schemas fetched only when actually needed.

What you'll see in /context:
Most of the Tools section is gone from the upfront context. Tool schemas are loaded progressively as the model uses them.

To opt out (if you prefer the old behavior):
~~~json
// settings.json
{ "env": { "ENABLE_TOOL_SEARCH": "false" } }
~~~

Or add ToolSearch to disallowedTools.

Closing as resolved — thanks for the detailed breakdown, it was a great framing of the problem.

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.