Skip to content

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

Closed

Description

@machjesusmoto

Feature Request: Lazy Loading for MCP Servers and Tools

Problem Statement

Currently, Claude Code loads all configured MCP servers, tools, and agents at session startup, consuming significant context before any conversation begins. In my environment:

  • MCP tools: 39.8k tokens (19.9%)
  • Custom agents: 9.7k tokens (4.9%)
  • System tools: 22.6k tokens (11.3%)
  • Memory files: 36.0k tokens (18.0%)
  • Total: ~108k tokens (54% of 200k limit)

This leaves only 92k tokens for actual conversation and work, severely limiting complex tasks.

Proposed Solution

Implement lazy loading for MCP servers and tools, loading them only when needed based on conversation context.

Core Features

  1. Lightweight Registry System

    • Load only a small index (~5k tokens) at startup
    • Registry contains tool names, descriptions, and trigger keywords
    • Tools load on-demand when keywords are detected
  2. Intelligent Loading

    • Analyze user input for relevant keywords
    • Load only required tools for the task
    • Cache loaded tools for session duration
    • Preload related tools that commonly work together
  3. Configuration Options

    {
      "optimization": {
        "lazyLoading": true,
        "maxInitialTokens": 5000,
        "autoLoadThreshold": 0.8,
        "cacheMinutes": 30
      },
      "mcpServers": {
        "example-server": {
          "command": "...",
          "lazyLoad": true,
          "triggers": ["keyword1", "keyword2"],
          "preloadWith": ["related-server"]
        }
      }
    }

Benefits

  • 95% Token Reduction: From 108k to ~5k initial tokens
  • Longer Conversations: 195k tokens available vs 92k currently
  • Better Performance: Faster startup, lower memory usage
  • Scalability: Can add more tools without context penalty

Implementation Suggestion

Phase 1: Basic Lazy Loading

  • Add lazyLoad flag to MCP server configs
  • Load registry instead of full tool definitions
  • Implement on-demand loading when tool is called

Phase 2: Intelligent Preloading

  • Keyword-based auto-loading
  • Pattern recognition for common workflows
  • Tool relationship mapping

Phase 3: Advanced Optimization

  • Session-based learning of tool usage patterns
  • Predictive preloading based on project context
  • Dynamic unloading of unused tools

User Experience

Before (Current)

Starting session...
Loading 73 MCP tools... [39.8k tokens]
Loading 56 agents... [9.7k tokens]
Loading system tools... [22.6k tokens]
Ready with 92k tokens remaining.

After (With Lazy Loading)

Starting session...
Loading tool registry... [5k tokens]
Ready with 195k tokens available.

User: "I need to build a React component"
> Auto-loading: context7, magic [+3.5k tokens]
> 191.5k tokens remaining

Test Case

I've already built a proof-of-concept in ~/.claude/optimization/ that demonstrates:

  • Registry generation from existing MCP configs
  • Keyword extraction and mapping
  • Lazy loader with pattern matching
  • 95% token reduction achieved

Files available for reference:

  • tool-registry.json - Example registry structure
  • lazy-loader.py - Proof of concept implementation
  • generate-index.py - Registry generation logic

Priority

High - This is a critical limitation for power users with many tools and complex workflows. The current 54% context consumption at startup makes many advanced use cases impossible.

Similar Products

  • VSCode: Lazy loads extensions based on file types and activation events
  • JetBrains IDEs: Load plugins on-demand based on project type
  • Vim/Neovim: Lazy loading plugins (lazy.nvim, vim-plug with lazy loading)

Contact

Happy to provide more details, test beta implementations, or share the proof-of-concept code.


Submitted by: dtaylor
Date: July 9, 2025
Claude Code Version: [Current Version]
Impact: Affects all users with multiple MCP servers configured

Activity

  1. github-actions commented on Sep 9, 2025

    @github-actions

    Found 3 possible duplicate issues:

    1. Add dynamic loading/unloading of MCP servers during active sessions #6638
    2. Feature Request: Improve Claude Code Token Management with MCP Servers #7172
    3. Having multiple MCP servers running Eats into Context Window #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

  2. machjesusmoto commented on Sep 9, 2025

    @machjesusmoto
    Author

    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.

  3. lukemmtt commented on Sep 9, 2025

    @lukemmtt

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

  4. wizardlyluke commented on Sep 10, 2025

    @wizardlyluke

    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.

  5. machjesusmoto commented on Sep 10, 2025

    @machjesusmoto
    Author

    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!

  6. machjesusmoto commented on Sep 10, 2025

    @machjesusmoto
    Author

    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:

    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?

  7. lukemmtt commented on Sep 10, 2025

    @lukemmtt

    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.

  8. machjesusmoto commented on Sep 10, 2025

    @machjesusmoto
    Author

    @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 (Having multiple MCP servers running Eats into Context Window #3036, Add dynamic loading/unloading of MCP servers during active sessions #6638, Feature Request: Improve Claude Code Token Management with MCP Servers #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
  9. lukemmtt commented on Sep 10, 2025

    @lukemmtt

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

  10. lukemmtt commented on Oct 10, 2025

    @lukemmtt

    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.

  11. 8 remaining items

  12. merlinrabens commented on Dec 14, 2025

    @merlinrabens

    @ everyone try this: #12836 (comment)

    Basically:

    1. Add the following to your shell file (~/.zshrc, ~/.bashrc, etc)
    # Claude Code - Enable experimental MCP-CLI for reduced token consumption
    export ENABLE_EXPERIMENTAL_MCP_CLI=true
    1. Make sure you have claude code version > 2.0.62.
    2. Enjoy what you see in /context
      😊
  13. heuselm commented on Dec 22, 2025

    @heuselm

    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 [email protected]"
    
    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!

  14. McBenac commented on Jan 7, 2026

    @McBenac

    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.

  15. added a commit that references this issue on Jan 15, 2026
    af2831c
  16. curtcox commented on Jan 15, 2026

    @curtcox

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

  17. DeutscheOsman commented on Jan 16, 2026

    @DeutscheOsman

    nice

  18. added a commit that references this issue on Jan 18, 2026
    aa4419e
  19. added a commit that references this issue on Jan 21, 2026
    054a0c1
  20. mercierj commented on Feb 2, 2026

    @mercierj

    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.

  21. ChNorman commented on Feb 20, 2026

    @ChNorman

    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.

  22. block-town commented on Mar 8, 2026

    @block-town

    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

  23. bcherny commented on Mar 12, 2026

    @bcherny
    Collaborator

    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):

    // 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.

  24. github-actions commented on Mar 19, 2026

    @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.

  25. locked as resolved and limited conversation to collaborators on Mar 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions