Feature Request: On-demand plugin loading to reduce token overhead

Problem

Every active plugin's full tool/skill definitions are loaded into the system prompt on every single message — regardless of whether they're needed for the current task. With multiple plugins enabled, the system prompt easily reaches 40,000–50,000+ tokens before the user even types a word. That's 20–25% of the context window consumed by static definitions.

Real-world token measurements (via #16826)

| Server | Tools | Tokens |
|--------|-------|--------|
| notion | 14 | ~30k |
| github | 37 | ~27k |
| serena | 29 | ~20k |
| sentry | 18 | ~21k |
| playwright | 22 | ~14.5k |
| Total | 142 | ~150k |

That's 95% waste — in a typical session, only 6 tools (~6.6k tokens) were actually used.

Existing Approaches & Their Limitations

1. MCPSearch / ENABLE_TOOL_SEARCH (built-in, but unreliable)

There's already a feature that's supposed to defer MCP tool loading when context exceeds 10%. However, multiple bug reports (#19560, #18370, #14884) show it's not activating reliably — users report it simply doesn't work despite exceeding thresholds.

2. CLAUDE.md-based plugin awareness (our experiment)

We tried a different approach: disable plugins to save tokens, but document them in CLAUDE.md so the model knows they exist and can suggest activation:

## Inactive Plugins (disabled to save tokens)
IMPORTANT: Before starting work on a task, check if one of these plugins
would be better suited. If so, mention it and ask the user to activate it.
- PR Reviews → pr-review-toolkit
- Semantic Code Analysis → serena
- TypeScript Type-Errors → typescript-lsp

Result after 3 iterations of strengthening the wording: the model ignores this ~90% of the time. The CLAUDE.md content is ~2% of the total system prompt (~35 lines out of ~3,000) and gets drowned out by tool definitions and other instructions. This approach fundamentally doesn't work as a reliable gate mechanism.

3. Manual config management

Editing settings.json or .mcp.json to disable plugins — but this requires restarting the session, losing conversation context.

Proposed Solution

On-demand (lazy) plugin loading — allow plugins to be activated mid-session without restarting:

1. Lightweight registration: Disabled/lazy plugins are registered with just their name + one-line description (minimal tokens) instead of full tool/skill schemas
2. Mid-session activation: A command like /plugin activate <name> or /mcp add <name> loads the full plugin definitions into the current session context
3. Optional deactivation: /plugin deactivate <name> unloads the definitions to free up context space

Additional approaches worth considering (from community)

• Keyword-triggered loading (#16826): Configure trigger keywords per MCP server, auto-prompt user when keywords are detected
• Category-based loading (#16826): Group MCPs into profiles (debugging, documentation, testing, coding)
• Skills as MCP stubs (#16826 comment by @millimoose): Use Haiku to auto-generate lightweight skill definitions from full MCP schemas — load the stub, expand on demand
• Per-session /mcp add (#21545): Simple CLI commands to add/remove MCPs mid-session
• Role-based tool segmentation (#16826 comment by @alistairyes): Different agent types see only the tools they need

Why This Matters

This is not a niche issue — it has been independently reported at least 3 times in 4 weeks:

• #16826 (Jan 8) — "Lazy-Loading / On-Demand MCP Tool Registration" (5 comments)
• #21545 (Jan 28) — "Lazy-load skills and MCP servers (name-only stubs until invoked)"
• #23522 (this issue, Feb 6)

As the MCP ecosystem grows and users install more servers, this problem only gets worse. The existing MCPSearch feature is the right idea but needs to work reliably.

Benefits

1. Token Efficiency: 90%+ reduction in base token usage
2. No lost context: No session restart needed to change plugins
3. Better model behavior: Model can see available plugins (lightweight) and suggest activation
4. Scalability: Users can install many MCPs/plugins without penalty
5. Faster startup: Less tool parsing at conversation start

---

Greetings from @bmoers — who spent an evening empirically testing the limits of CLAUDE.md-based plugin management so you don't have to.

P.S. This issue was written by Claude (Opus 4.6) in Claude Code — the very tool this feature request is about. Yes, I'm requesting my own improvement. 🍻

---

Related: #16826, #21545