[FEATURE] Lazy-load MCP servers per agent instead of at startup

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

MCP tools are loaded into context at session startup, consuming tokens even when they're only needed by specific sub-agents. In my setup:

• Supabase MCP: ~15k tokens
• Maestro MCP: ~8k tokens
• Total: ~23k tokens in main context that I never use directly

I delegate all database work to a supabase-agent and all testing to a testing-agent. The main context only coordinates.

Proposed Solution

Allow MCP servers to be configured per-agent rather than globally. MCPs would lazy-load when an agent that needs them is spawned, keeping the main context lean.

Example config:
{
"agents": {
"supabase-agent": {
"mcpServers": ["supabase"]
},
"testing-agent": {
"mcpServers": ["maestro"]
}
}
}

Benefits:

• Main context stays lean for coordination
• Better token efficiency for agent-heavy workflows
• MCP costs only paid when actually needed

Alternative Solutions

_No response_

Priority

High - Significant impact on productivity

Feature Category

MCP server integration

Use Case Example

Building a new screen in a Flutter app with Supabase backend

1. User opens Claude Code to build a "Members Screen" for their app

• Session starts with 200k token limit
• MCP servers auto-load: Supabase (15k tokens) + Maestro (8k tokens)
• Main context immediately loses 23k tokens (11.5%) before any work begins

1. User asks Claude to build the screen

• Main Claude spawns flutter-screen-builder agent to write the UI code
• Agent doesn't need any MCP tools - just file read/write
• But those 23k MCP tokens are still consumed in main context

1. User asks to create the backend

• Main Claude spawns supabase-agent to write migrations
• Agent uses Supabase MCP tools
• Maestro MCP (~8k tokens) still sitting unused in main context

1. User asks to test the screen

• Main Claude spawns testing-agent to run Maestro flows
• Agent uses Maestro MCP tools
• Supabase MCP (~15k tokens) now sitting unused in main context

1. Result: Throughout the entire session, the main context carried 23k tokens of MCP tools it never directly used. All MCP usage happened in agents.

With lazy-loading per agent:

• Main context: 0 MCP tokens
• Supabase MCP loads only when supabase-agent spawns
• Maestro MCP loads only when testing-agent spawns
• Main context stays lean for coordination, gaining back ~11.5% of token budget

Additional Context

Technical considerations:

Current architecture:
claude mcp add supabase -- npx supabase mcp
claude mcp add maestro -- maestro mcp
All MCPs load at startup → tools injected into main context → agents inherit access.

Proposed architecture:
// .claude/settings.json
{
"mcpServers": {
"supabase": {
"command": "npx",
"args": ["supabase", "mcp"],
"agentOnly": true // Don't load in main context
}
}
}

// .claude/agents/supabase-agent.md
---
mcpServers: ["supabase"] // Load when this agent spawns
---

Similar patterns in other tools:

• VS Code extensions: Activate on-demand via activationEvents rather than at startup
• Webpack code splitting: Lazy-load modules only when needed
• Docker: Containers start only when called, not all at once

Constraints to consider:

• MCP server startup time (cold start latency when agent spawns)
• Connection pooling (reuse MCP connection if same agent spawns multiple times in session)
• Memory management (when to unload MCP after agent completes?)

Workaround (current):

Users can manually toggle MCPs per session:
claude mcp remove maestro # Before DB-heavy session
claude mcp add maestro -- maestro mcp # When testing needed
This is cumbersome and defeats the purpose of a unified workflow.