feat(mcp): smart loading — connect_strategy, tool budget, per-session scoping, meta-tools

Four levers to control MCP server loading, reducing startup time and
context-window bloat for users with many MCP servers.

Lever 1 — connect_strategy (per-server):
  startup (default): connect at Hermes startup, register all tools
  lazy: register tool schemas but defer subprocess spawn until first call
  on_demand: invisible until explicitly loaded via /mcp load or mcp_load_server

Lever 2 — mcp_tool_budget (global):
  Caps the number of MCP tool schemas in the LLM prompt.
  LRU eviction drops least-used servers' tools when budget exceeded.
  Meta-tools (mcp_list_servers, mcp_load_server) always survive eviction.
  Default: 0 (unlimited, backward compatible).

Lever 3 — /mcp slash commands:
  /mcp list              → show all servers, status, tool counts, strategy
  /mcp enable <name>     → activate a lazy/on_demand server now
  /mcp disable <name>    → mark an on_demand server inactive for this session
  /mcp load <name>       → same as enable

Lever 4 — meta-tools (always available):
  mcp_list_servers — returns all configured servers with status/strategy
  mcp_load_server  — activates a lazy or on_demand server mid-session

Bug fixes discovered during audit:
- _activate_lazy_server removed from _lazy_servers before connecting,
  leaving failed connections in limbo (not retryable, not connected)
- /mcp disable called _clear_session_loaded_servers() which cleared ALL
  on_demand servers, not just the named one
- Lazy server stub tools had no toolset alias registered, making them
  invisible to the platform resolver
- Meta-tools registered into toolset 'mcp' which doesn't exist in any
  platform composite — tools were invisible to the LLM

Refs: NousResearch#66473 (umbrella), NousResearch#63626 (lazy MCP), NousResearch#6839 (tool schema deferral),
      NousResearch#45955 (per-session scoping)

Author: prismatic7

cli.py

@@ -8790,6 +8790,8 @@ def process_command(self, command: str) -> bool:
             # The auto-reload path (file watcher) calls _reload_mcp directly
             # without this confirmation.
             self._confirm_and_reload_mcp(cmd_original)
+        elif canonical == "mcp":
+            self._handle_mcp_command(cmd_original)
         elif canonical == "reload-skills":
             with self._busy_command(self._slow_command_status(cmd_original)):
                 self._reload_skills()
@@ -10876,6 +10878,108 @@ def _confirm_and_reload_mcp(self, cmd_original: str = "") -> None:
         with self._busy_command(self._slow_command_status(cmd_original)):
             self._reload_mcp()
 
+    def _handle_mcp_command(self, cmd_original: str) -> None:
+        """Handle /mcp list|enable|disable|load <name>."""
+        parts = cmd_original.strip().split(None, 2)
+        subcmd = parts[1].lower() if len(parts) > 1 else "list"
+        arg = parts[2] if len(parts) > 2 else ""
+
+        from tools.mcp_tool import (
+            _load_mcp_config, _servers, _lock,
+            _is_lazy_server, _is_on_demand_server,
+            _is_server_loaded_in_session, _mark_server_loaded_in_session,
+            _activate_lazy_server, _activate_on_demand_server,
+            _get_connect_strategy, _parse_boolish,
+            _remove_session_loaded_server,
+        )
+
+        if subcmd == "list":
+            servers = _load_mcp_config()
+            if not servers:
+                print("  No MCP servers configured.")
+                return
+
+            print(f"  MCP servers ({len(servers)} configured):")
+            for name, cfg in sorted(servers.items()):
+                enabled = _parse_boolish(cfg.get("enabled", True), default=True)
+                if not enabled:
+                    print(f"    {name}: disabled")
+                    continue
+
+                strategy = _get_connect_strategy(cfg)
+                transport = "http" if "url" in cfg else "stdio"
+
+                with _lock:
+                    server = _servers.get(name)
+                    connected = server is not None and server.session is not None
+                    tool_count = len(getattr(server, "_registered_tool_names", [])) if server else 0
+
+                is_lazy = _is_lazy_server(name)
+                is_ondemand = _is_on_demand_server(name)
+                loaded = _is_server_loaded_in_session(name) if is_ondemand else True
+
+                status = "connected" if connected else "lazy" if is_lazy else "on_demand" if is_ondemand else "disconnected"
+                active = "active" if (connected or (is_lazy and not is_ondemand) or loaded) else "inactive"
+                print(f"    {name}: {status} ({transport}, {tool_count} tools, {active})")
+
+        elif subcmd == "enable":
+            if not arg:
+                print("  Usage: /mcp enable <server-name>")
+                return
+            servers = _load_mcp_config()
+            if arg not in servers:
+                print(f"  Unknown MCP server '{arg}'. Use /mcp list to see available servers.")
+                return
+            strategy = _get_connect_strategy(servers[arg])
+            if strategy == "on_demand":
+                if _activate_on_demand_server(arg):
+                    print(f"  ✅ MCP server '{arg}' loaded and activated.")
+                else:
+                    print(f"  ❌ Failed to load MCP server '{arg}'.")
+            elif strategy == "lazy":
+                if _activate_lazy_server(arg):
+                    print(f"  ✅ MCP server '{arg}' activated.")
+                else:
+                    print(f"  ❌ Failed to activate MCP server '{arg}'.")
+            else:
+                print(f"  MCP server '{arg}' is already configured as 'startup' (always connected).")
+
+        elif subcmd == "disable":
+            if not arg:
+                print("  Usage: /mcp disable <server-name>")
+                return
+            # For on_demand servers, mark as not loaded in this session
+            if _is_on_demand_server(arg):
+                _remove_session_loaded_server(arg)
+                print(f"  MCP server '{arg}' disabled for this session.")
+            else:
+                print(f"  MCP server '{arg}' cannot be disabled mid-session. Use /reload-mcp to restart all servers.")
+
+        elif subcmd == "load":
+            if not arg:
+                print("  Usage: /mcp load <server-name>")
+                return
+            servers = _load_mcp_config()
+            if arg not in servers:
+                print(f"  Unknown MCP server '{arg}'. Use /mcp list to see available servers.")
+                return
+            strategy = _get_connect_strategy(servers[arg])
+            if strategy == "on_demand":
+                if _activate_on_demand_server(arg):
+                    print(f"  ✅ MCP server '{arg}' loaded and activated.")
+                else:
+                    print(f"  ❌ Failed to load MCP server '{arg}'.")
+            elif strategy == "lazy":
+                if _activate_lazy_server(arg):
+                    print(f"  ✅ MCP server '{arg}' activated.")
+                else:
+                    print(f"  ❌ Failed to activate MCP server '{arg}'.")
+            else:
+                print(f"  MCP server '{arg}' is already connected (startup strategy).")
+
+        else:
+            print(f"  Unknown subcommand '{subcmd}'. Use: list, enable <name>, disable <name>, load <name>")
+
     def _reload_mcp(self):
         """Reload MCP servers: disconnect all, re-read config.yaml, reconnect.
 

hermes_cli/commands.py

@@ -214,6 +214,9 @@ class CommandDef:
                cli_only=True),
     CommandDef("reload-mcp", "Reload MCP servers from config", "Tools & Skills",
                aliases=("reload_mcp",)),
+    CommandDef("mcp", "Manage MCP servers: list, enable, disable, load", "Tools & Skills",
+               args_hint="[list|enable <name>|disable <name>|load <name>]",
+               subcommands=("list", "enable", "disable", "load")),
     CommandDef("reload-skills", "Re-scan ~/.hermes/skills/ for newly installed or removed skills",
                "Tools & Skills", aliases=("reload_skills",)),
     CommandDef("browser", "Connect browser tools to your live Chromium-family browser via CDP", "Tools & Skills",

hermes_cli/config.py

@@ -1381,6 +1381,12 @@ def _ensure_hermes_home_managed(home: Path):
     # small so a slow/dead server adds little to first-response latency.
     "mcp_discovery_timeout": 1.5,
 
+    # MCP tool schema budget: max MCP tool schemas to inject into the
+    # LLM system prompt. When the total MCP tools exceed this budget,
+    # least-recently-used servers' tools are dropped. 0 = unlimited
+    # (current default, backward compatible).
+    "mcp_tool_budget": 0,
+
     # Tool-output truncation thresholds. When terminal output or a
     # single read_file page exceeds these limits, Hermes truncates the
     # payload sent to the model (keeping head + tail for terminal,

model_tools.py

@@ -38,6 +38,35 @@
 # advisory (#33924) is logged once per name, not on every tool recompute.
 _WARNED_DISABLED_BUNDLES: set = set()
 
+# MCP tool budget tracking: LRU timestamps for MCP tool calls.
+# Keyed by tool name, value is monotonic time of last use.
+_mcp_tool_last_used: Dict[str, float] = {}
+_mcp_tool_last_used_lock = threading.Lock()
+
+
+def _resolve_mcp_tool_budget() -> int:
+    """Read the MCP tool budget from config. 0 = unlimited."""
+    try:
+        from hermes_cli.config import load_config
+        cfg = load_config() or {}
+        return int(cfg.get("mcp_tool_budget", 0))
+    except Exception:
+        return 0
+
+
+def _get_mcp_tool_last_used(tool_name: str) -> float:
+    """Return the last-used timestamp for an MCP tool (0 if never used)."""
+    with _mcp_tool_last_used_lock:
+        return _mcp_tool_last_used.get(tool_name, 0.0)
+
+
+def _mark_mcp_tool_used(tool_name: str) -> None:
+    """Record that an MCP tool was just used (for LRU eviction)."""
+    if not tool_name.startswith("mcp__"):
+        return
+    with _mcp_tool_last_used_lock:
+        _mcp_tool_last_used[tool_name] = time.monotonic()
+
 
 # =============================================================================
 # Async Bridging  (single source of truth -- used by registry.dispatch too)
@@ -450,6 +479,38 @@ def _compute_tool_definitions(
     # descriptions that don't actually exist, and hallucinates calls to them.
     available_tool_names = {t["function"]["name"] for t in filtered_tools}
 
+    # Apply MCP tool budget: if configured, cap the number of MCP tool
+    # schemas in the prompt. Meta-tools (mcp_list_servers, mcp_load_server)
+    # are always included. When the budget is exceeded, tools from
+    # least-recently-used servers are dropped first.
+    _mcp_tool_budget = _resolve_mcp_tool_budget()
+    if _mcp_tool_budget > 0:
+        mcp_tools = [
+            t for t in filtered_tools
+            if t.get("function", {}).get("name", "").startswith("mcp__")
+            and t.get("function", {}).get("name", "") not in ("mcp_list_servers", "mcp_load_server")
+        ]
+        if len(mcp_tools) > _mcp_tool_budget:
+            # Keep meta-tools, drop excess MCP tools
+            non_mcp_tools = [
+                t for t in filtered_tools
+                if not t.get("function", {}).get("name", "").startswith("mcp__")
+                or t.get("function", {}).get("name", "") in ("mcp_list_servers", "mcp_load_server")
+            ]
+            # Sort MCP tools by LRU: keep the most recently used ones
+            mcp_tools.sort(
+                key=lambda t: _get_mcp_tool_last_used(t.get("function", {}).get("name", "")),
+                reverse=True,
+            )
+            filtered_tools = non_mcp_tools + mcp_tools[:_mcp_tool_budget]
+            # Recompute available_tool_names
+            available_tool_names = {t["function"]["name"] for t in filtered_tools}
+            logger.debug(
+                "MCP tool budget: capped %d MCP tools to %d (dropped %d)",
+                len(mcp_tools), _mcp_tool_budget,
+                len(mcp_tools) - _mcp_tool_budget,
+            )
+
     # Rebuild execute_code schema to only list sandbox tools that are actually
     # available.  Without this, the model sees "web_search is available in
     # execute_code" even when the API key isn't configured or the toolset is
@@ -1289,6 +1350,9 @@ def _dispatch(next_args: Dict[str, Any]) -> Any:
                 turn_id=turn_id or "",
                 api_request_id=api_request_id or "",
             )
+
+            # Track MCP tool usage for LRU eviction
+            _mark_mcp_tool_used(function_name)
         finally:
             if _approval_tokens is not None and reset_current_observability_context is not None:
                 try: