[FEATURE] Lazy-load MCP servers only when specific agents are invoked

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

## Problem Statement

Currently, MCP servers configured at user scope are loaded into every Claude Code session across all projects. This causes:

1. Unnecessary context consumption - MCP tool definitions take up context space even when not needed
2. No agent-specific MCP isolation - The allowedMCPServers field in agent frontmatter only restricts which MCPs an agent can access from those already loaded; it doesn't enable lazy-loading
3. All-or-nothing availability - Users must choose between global availability (wastes context) or no availability (can't use in agents)

## Use Case

I created a docs-consultant agent that uses Context7 MCP for documentation lookups. I want:

• Context7 MCP to load only when docs-consultant agent is invoked
• Main Claude Code session and other agents to not have Context7 tools in their context
• No Context7 tool definitions consuming context in normal coding sessions

## Current Behavior

~/.claude/agents/docs-consultant.md
``
tools: WebSearch, Glob, Grep, Read, WebFetch, mcp__context7
allowedMCPServers: context7
``

• Context7 must be installed with user scope to be available to the agent
• Once installed, Context7 tools appear in every session across all projects
• deniedMcpServers in settings blocks the MCP entirely, including for agents
• allowedMCPServers in agent frontmatter doesn't override deny lists or trigger lazy-loading

## Proposed Solution

Benefits

1. Reduced context usage - MCP tools only loaded when needed
2. Better separation of concerns - Specialized agents get specialized tools
3. Cleaner main session - No tool clutter from agent-specific MCPs
4. Faster startup - Fewer MCP connections on session init

## Alternatives Considered

| Approach | Problem |
|------------------------------|--------------------------------------------------|
| deniedMcpServers in settings | Blocks MCP entirely, including for agents |
| Project-scoped MCP | Requires dedicated project just for docs lookups |
| Don't install MCP | Agent can't use it |
| Live with global scope | Wastes context in every session |

## Additional Context

Related to https://github.com/anthropics/claude-code/issues/11461 (per-project plugin configuration) - both address the need for more granular scoping of Claude Code extensions.

Proposed Solution

Add support for agent-scoped MCP lazy-loading:

### Option A: New agent frontmatter field
```
name: docs-consultant
tools: mcp__context7
loadMCPServers:

• context7

```

When the agent is invoked, Claude Code would:

1. Check loadMCPServers list
2. Connect to those MCP servers on-demand
3. Disconnect when agent completes

### Option B: Inline MCP definition in agent

  name: docs-consultant
  mcpServers:
    context7:
      transport: http
      url: https://mcp.context7.com/mcp
      headers:
        CONTEXT7_API_KEY: ${CONTEXT7_API_KEY}
  ```

  ### Option C: Scope modifier for allowedMCPServers

allowedMCPServers:

• name: context7

lazyLoad: true # Only connect when this agent runs
```

Alternative Solutions

Related: Anthropic's "Code Execution with MCP" Pattern

This issue highlights a real pain point with context consumption from MCP tool definitions. I wanted to share a related approach from Anthropic's engineering blog that addresses a similar (but broader) problem:
https://www.anthropic.com/engineering/code-execution-with-mcp.

How the approaches compare

| | This Issue (#13700) | Code Execution with MCP |
|----------------------|------------------------------------|-------------------------------------------------------------------|
| Problem addressed | Tool definitions loaded upfront | Tool definitions + intermediate results bloating context |
| Solution | Lazy-load MCP servers per-agent | Expose MCPs as filesystem modules; agent writes code to call them |
| Token savings | Avoids loading unused tool schemas | 98.7% reduction in their example (150K → 2K tokens) |
| Implementation scope | Claude Code feature | Fundamental agent architecture pattern |

The blog's approach

Instead of exposing MCP tools directly to the model, their pattern:

1. Exposes MCP servers as code modules on a filesystem
2. Agent discovers tools on-demand by reading schema files (not loading all upfront)
3. Agent writes code that imports and calls these modules
4. Intermediate results stay in the execution sandbox—only explicitly returned data enters context

#### Instead of direct tool calls, agent writes:
```from mcp_servers import context7
docs = context7.get_library_docs("/vercel/next.js", topic="routing")
return summarize(docs) # Only this enters Claude's context

  #### Why both matter

  This issue's proposal (loadMCPServers) solves the immediate problem within Claude Code's current architecture and should be implemented. It's practical, backwards-compatible, and addresses the specific use case of agent-scoped MCP loading.

  The code execution pattern is a longer-term architectural direction that would make this problem (and others) disappear entirely. If Claude Code eventually adopts this pattern:
  - No upfront tool definition cost (schemas read on-demand via filesystem)
  - Natural lazy-loading (code imports only what it needs)
  - Intermediate data filtering (sandbox keeps large payloads out of context)

  #### Suggestion

  Perhaps the loadMCPServers feature could be designed with an eye toward future compatibility with code-execution-style MCP access? For example, lazy-loaded MCPs could optionally be exposed as importable modules rather than direct tools, giving users
   a migration path toward the more efficient pattern.

### Priority

Medium - Would be very helpful

### Feature Category

MCP server integration

### Use Case Example

_No response_

### Additional Context

_No response_