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

docker compose up -d
claude mcp add --scope user --transport sse airis-mcp-gateway http://localhost:9400/sse

PROMPT=$(cat | jq -r '.userPrompt // empty' 2>/dev/null)
SETTINGS="$HOME/.claude/settings.json"
if echo "$PROMPT" | grep -qiE 'disable (mcp|server)\s+(\w+)'; then
    SERVER=$(echo "$PROMPT" | grep -oiE 'disable (mcp|server)\s+(\w+)' | awk '{print $NF}')
    if [ -n "$SERVER" ]; then
        jq --arg s "$SERVER" '
            .disabledMcpServers[$s] = .mcpServers[$s] |
            del(.mcpServers[$s])
        ' "$SETTINGS" > "${SETTINGS}.tmp" && mv "${SETTINGS}.tmp" "$SETTINGS"
        jq -n --arg s "$SERVER" '{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":"MCP server disabled: " + $s + ". Restart session for changes to take effect."}}'
        exit 0
    fi
fi
if echo "$PROMPT" | grep -qiE 'enable (mcp|server)\s+(\w+)'; then
    SERVER=$(echo "$PROMPT" | grep -oiE 'enable (mcp|server)\s+(\w+)' | awk '{print $NF}')
    if [ -n "$SERVER" ]; then
        jq --arg s "$SERVER" '
            .mcpServers[$s] = .disabledMcpServers[$s] |
            del(.disabledMcpServers[$s])
        ' "$SETTINGS" > "${SETTINGS}.tmp" && mv "${SETTINGS}.tmp" "$SETTINGS"
        jq -n --arg s "$SERVER" '{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":"MCP server enabled: " + $s + ". Restart session for changes to take effect."}}'
        exit 0
    fi
fi
exit 0

ACTION=$1; SERVER=$2
SETTINGS="$HOME/.claude/settings.json"
case "$ACTION" in
    list)
        echo "Active:" && jq -r '.mcpServers // {} | keys[]' "$SETTINGS"
        echo "Disabled:" && jq -r '.disabledMcpServers // {} | keys[]' "$SETTINGS"
        ;;
    disable)
        jq --arg s "$SERVER" '.disabledMcpServers[$s] = .mcpServers[$s] | del(.mcpServers[$s])' "$SETTINGS" | sponge "$SETTINGS"
        echo "Disabled $SERVER"
        ;;
    enable)
        jq --arg s "$SERVER" '.mcpServers[$s] = .disabledMcpServers[$s] | del(.disabledMcpServers[$s])' "$SETTINGS" | sponge "$SETTINGS"
        echo "Enabled $SERVER"
        ;;
esac

[ ! -f docker-compose.yml ] && ~/bin/mcp-toggle disable database 2>/dev/null