Feature Request: CLI Commands for MCP Server Enable/Disable (Hook Automation Support)

Feature Request: CLI Commands for MCP Server Enable/Disable (Hook Automation Support)

Problem Statement

Claude Code v2.0.10 introduced the ability to enable/disable MCP servers within a session via the @ UI menu. This is excellent for manual control, but there's currently no way to programmatically toggle MCP servers via CLI commands. This prevents automation through hooks and scripts.

Current Limitations:

1. The claude mcp CLI only supports add, remove, list, and get - no enable/disable/toggle
2. MCP servers consume context window even when not actively needed
3. No way to automate MCP lifecycle based on project context, skills, or workflows
4. The @ menu toggle is UI-only with no programmatic equivalent

Use Case: Skill-Based MCP Management

I have several Claude Code skills that require specific MCP servers, but only occasionally:

Example Skills:

• accessibility-compliance-expert skill → Needs Playwright MCP for visual testing
• library-documentation research → Needs Context7 MCP for API docs
• database-analysis tasks → Needs database MCP tools

Current Problem:

• All MCP servers load at session start, consuming 15-20% of context window
• Playwright MCP alone: ~8-10k tokens, but only needed for visual testing tasks
• Context7 MCP: ~5k tokens, but only needed for documentation lookup
• These servers sit idle 90% of the time, wasting valuable context

Desired Workflow:

# SessionStart hook - enable only baseline MCPs
claude mcp disable playwright
claude mcp disable context7

# PreToolUse hook - enable when specific skill triggers
if [[ "$context" =~ "accessibility-compliance-expert" ]]; then
  claude mcp enable playwright
fi

# Stop hook - disable when skill completes to free context
claude mcp disable playwright

Proposed CLI Commands

Add these commands to the claude mcp CLI:

# Enable an MCP server in current session (doesn't modify config files)
claude mcp enable <server-name>

# Disable an MCP server in current session (doesn't modify config files)  
claude mcp disable <server-name>

# Toggle an MCP server's state
claude mcp toggle <server-name>

# Show current enabled/disabled state of all servers
claude mcp status

Example Usage:

$ claude mcp status
✓ pieces-mcp          enabled   (3.2k tokens)
✗ playwright          disabled  
✓ sequential-thinking enabled   (1.8k tokens)
✗ context7            disabled
✓ stripe              enabled   (4.1k tokens)

Total active: 3/5 servers (9.1k tokens)

$ claude mcp disable stripe
✓ Disabled stripe (freed 4.1k tokens)

$ claude mcp enable playwright  
✓ Enabled playwright (loaded 8.3k tokens)

Hook Integration Example

SessionStart Hook (.claude/hooks/session-start.sh):

#!/bin/bash
# Disable rarely-used MCPs at session start

claude mcp disable playwright
claude mcp disable context7

# Enable based on project type
if [[ -f "package.json" ]] && grep -q "@playwright/test" package.json; then
  claude mcp enable playwright
  echo "📊 Enabled Playwright MCP for testing project"
fi

PreToolUse Hook (.claude/hooks/pre-tool-use.sh):

#!/bin/bash
# Enable MCP when specific skill triggers

# Read context from environment
context="$CLAUDE_CONTEXT"

if [[ "$context" =~ "accessibility-compliance-expert" ]]; then
  # Enable Playwright only when accessibility skill is active
  claude mcp enable playwright
fi

SubagentStop Hook (.claude/hooks/subagent-stop.sh):

#!/bin/bash
# Free up context when specialized subagent completes

subagent_name="$CLAUDE_SUBAGENT_NAME"

if [[ "$subagent_name" == "accessibility-compliance-expert" ]]; then
  claude mcp disable playwright
  echo "♻️ Freed context: disabled Playwright MCP"
fi

Benefits

1. Context Window Optimization

• Load MCP servers on-demand instead of all-at-once
• Free context by disabling servers when done
• Optimize for long development sessions with varying needs

1. Skill-Based Automation

• Skills can automatically enable their required MCPs
• Clean up after themselves to avoid context bloat
• Smooth integration with subagent workflows

1. Project-Based Profiles

• SessionStart hooks enable relevant MCPs based on project type
• Testing projects get Playwright, database projects get DB tools
• No manual toggling required

1. Hook Ecosystem Integration

• PreToolUse, Stop, SubagentStop hooks manage MCP lifecycle
• Automated workflows without manual intervention
• ADHD-friendly: reduces decision fatigue

Implementation Considerations

Session-Level Only:

• These commands affect current session only (not config files)
• Changes don't persist across session restarts
• Config files (.mcp.json, settings.json) remain unchanged

Relationship to @ Menu:

• CLI commands should mirror the behavior of the UI @ toggle
• Both methods (UI and CLI) modify the same session state
• claude mcp status should reflect current state regardless of how it was set

Security:

• Respect existing approval workflows for project-scoped servers
• Honor managed-mcp.json enterprise policies
• Enabling a disabled server may still prompt for project approval if not yet granted

Error Handling:

$ claude mcp enable nonexistent-server
❌ Error: MCP server 'nonexistent-server' not found in configuration
   Available servers: pieces-mcp, playwright, sequential-thinking

$ claude mcp disable playwright
✓ Disabled playwright

$ claude mcp disable playwright  
⚠️ Warning: playwright is already disabled

Why This is Different from Existing Issues

While several issues request runtime toggling (#6309, #6638), this request specifically focuses on:

1. CLI automation (not just UI toggle, which already exists)
2. Hook integration (SessionStart, PreToolUse, Stop, SubagentStop)
3. Skill-based workflows (automated MCP lifecycle management)
4. Concrete implementation (specific command syntax and examples)

Alternative Solutions Considered

1. Project-scoped .mcp.json with enabledMcpjsonServers

• Problem: Only works at session start, not mid-session
• Problem: Requires session restart to change

1. PreToolUse hooks blocking MCP tools

• Problem: Doesn't free context, server still loaded
• Problem: Shows confusing errors instead of smooth workflow

1. Multiple Claude Code profiles/sessions

• Problem: Fragments workflow across sessions
• Problem: Loses conversation context when switching

Related Issues

• #6309 - Runtime MCP Server Toggle (general request)
• #6638 - Dynamic loading/unloading (context optimization focus)
• #7328 - Tool-level filtering (related but different scope)
• #3036 - MCP servers eating context window

Priority

High - This enables a powerful automation workflow that significantly improves context management and integrates with Claude Code's existing hook system.

---

Environment:

• Claude Code Version: 2.0.22 (latest)
• MCP Servers: 5-7 servers configured per project
• Context Impact: 15-20k tokens consumed by idle MCP servers