MCP servers must lazy-load in every fleet agent

rule Mon Jul 06 2026 00:00:00 GMT+0000 (Coordinated Universal Time) mcpperformancefleetagentlazy-load

MCP must lazy-load

Rule

Every fleet agent (CC, OpenCode, Kilo, Antigravity, Copilot CLI, Freebuff, Qwen) MUST connect to MCP via a schema-loading gateway:

• Claude Code: ENABLE_TOOL_SEARCH=auto in ~/.claude/settings.json. Deferred tool schemas load on ToolSearch invocation.
• OpenCode + Kilo: Smithery toolbox remote MCP as first entry (toolbox name reserved). Other MCP servers become fallback / dev-only.
• Everyone else: same Smithery toolbox pattern where the agent supports remote MCP; otherwise scope stdio MCP to <5 essential servers.

Reason: stdio MCP spawns TWO node.exe per server on connect (npx-cli parent + child). With N MCP entries × M concurrent agent sessions, node count balloons to 2NM. Empirically hit 480 node.exe / 194 GB commit on this machine 2026-07-06 (128 GB RAM, commit limit 174 GB) — Windows hang.

Enforcement

• Reviewer of any .mcp.json / ~/.config/opencode/opencode.jsonc / ~/.config/kilo/kilo.jsonc edit checks the toolbox entry survives.
• SessionStart hook (or Oriz-SyncAgentConfigs task) may inject an orphan-node kill for cmdline matches: npx-cli, foam-cli, -mcp\b, mcp-server, mcp-doctor.
• Kept-alive exceptions: Raycast backend node, cavemem\dist\index.js worker (long-lived workspace daemon).

Anti-patterns

• ❌ Adding a new stdio MCP directly to mcpServers without checking whether Smithery hosts it (Smithery has one-search-mcp, resend, mermaid, most public MCPs).
• ❌ Running multiple agent sessions with the same stdio MCP list — process count = 2 × servers × sessions.
• ❌ Leaving orphan node.exe from a crashed / force-quit session; kill on next boot.
• ❌ Skipping ENABLE_TOOL_SEARCH=auto in CC because "I only have 8 MCPs" — 8 × 2 nodes × 3 sessions = 48 processes, plus their transitive workers.

Cross-refs

• mcp-orphan-node-army-commit-hang-2026-07-06 — the incident
• agent-mcps-canonical-2026-07-04 — the canonical MCP list
• agent-fleet-parity — every fleet agent gets this
• claude-code-latency-techniques — cache impact of MCP connect/disconnect