[FEATURE] Dynamic MCP Server Management Without REPL Restart

Preflight Checklist

• [x] I have searched existing requests and this feature has not been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Problem Statement

When working with Claude Code, adding or modifying MCP servers requires quitting the REPL and restarting it. This creates several pain points:

1. Loss of context - Current conversation and session state are lost
2. Workflow disruption - Interrupts focus when you discover you need an additional tool mid-task
3. Time waste - Restart cycle adds friction, especially with multiple MCP servers that take time to initialize
4. Iterative development friction - When developing/testing MCP servers, constant restarts slow down the feedback loop

Current Behavior

• MCP servers are loaded at REPL startup from configuration
• To add a new MCP server, user must:

1. Exit the REPL (/quit or Ctrl+C)
2. Edit ~/.claude/settings.json or project .mcp.json
3. Restart Claude Code
4. Lose all conversation context and session state

Proposed Solution

Proposed Solution

Add runtime MCP server management commands that allow adding, removing, and refreshing MCP servers without restarting:

New Commands

# Add a new MCP server at runtime
/mcp add <server-name> --command "npx -y @example/mcp-server" --env KEY=value

# Add from a config file
/mcp add --config ./my-mcp-config.json

# Remove an MCP server
/mcp remove <server-name>

# List currently loaded MCP servers
/mcp list

# Refresh/reload a specific server (reconnect)
/mcp reload <server-name>

# Reload all MCP servers from config
/mcp reload --all

Behavior

When /mcp add is executed:

1. Validate configuration - Check command exists and is executable
2. Start MCP server process - Launch the server in background
3. Perform handshake - Initialize MCP protocol connection
4. Register tools - Make new tools available to Claude
5. Confirm success - Display available tools from new server

✓ Added MCP server "my-search"
  Tools available: search, get_document, list_results
  Resources available: none

Configuration Options

# Environment variable to enable hot-reload (if disabled by default)
export CLAUDE_MCP_HOT_RELOAD=true

Benefits

1. Preserved Context

• Continue conversations without losing history
• Maintain session state and working memory
• No need to re-explain context after restart

2. Faster Iteration

• MCP server developers can test changes instantly
• Try new tools without commitment to restart
• Quickly experiment with different server configurations

3. Better User Experience

• Seamless workflow when realizing you need another tool
• Reduced friction for power users with many MCP servers
• More responsive and dynamic tool environment

4. Flexibility

• Add project-specific MCP servers on the fly
• Temporarily add servers for specific tasks
• Remove unused servers to reduce noise

Implementation Notes

Process Management

• Track spawned MCP server processes
• Handle graceful shutdown on /mcp remove
• Detect and report if an MCP server crashes

Tool Registry Updates

• Dynamically update available tools list
• Handle tool name conflicts between servers
• Update tool permissions as needed

State Persistence (Optional)

• Optionally save runtime-added servers to config
• Flag to mark servers as "temporary" vs "persistent"

/mcp add my-server --command "..." --temporary  # Gone after session
/mcp add my-server --command "..." --save       # Persist to config

Error Handling

✗ Failed to add MCP server "broken-server"
  Error: Connection timeout after 30s
  Command: npx -y @example/broken-server
  Suggestion: Check if the package exists and server starts correctly

Use Cases

1. Mid-task tool discovery - Realize you need a database MCP server while working on a data task
2. MCP development - Iterating on a custom MCP server without restart cycles
3. Team collaboration - Teammate shares an MCP server config, add it instantly
4. Temporary tools - Add a specialized MCP server for one task, remove after
5. Debugging - Reload a misbehaving MCP server without full restart

Alternative Solutions

Alternative Approaches Considered

Alternative 1: Automatic Config Watching

• Pros: No new commands needed, just edit config
• Cons: May cause unexpected behavior, harder to control timing
• Note: Could complement explicit commands with opt-in watching

Alternative 2: Separate MCP Manager Process

• Pros: Centralized management, survives REPL restarts
• Cons: Additional complexity, another process to manage
• Note: Could be useful for enterprise/team scenarios

Alternative 3: Session Persistence Across Restarts

• Pros: Solves context loss problem differently
• Cons: Does not address restart time, more complex
• Note: Orthogonal feature, both could be valuable

Priority

High - Significant impact on productivity

Feature Category

CLI commands and flags

Use Case Example

Example Workflow

# Working on a project, realize you need Google Drive access
User: "I need to check something in our team's Google Drive"

Claude: "I don't currently have access to Google Drive. 
        Would you like to add the Google Drive MCP server?"

User: "/mcp add gdrive --command \"npx -y @anthropic/mcp-gdrive\""

# Server starts and connects
✓ Added MCP server "gdrive"
  Tools available: list_files, read_file, search_files
  Authenticating... Please complete OAuth in browser.
✓ Authentication complete

Claude: "I now have access to Google Drive. What would you like me to find?"

# Continue conversation with full context preserved

Additional Context

• Related: MCP protocol supports dynamic tool registration
• Similar patterns exist in other extensible CLIs (e.g., VS Code extensions, vim plugins)
• Could integrate with proposed MCP marketplace/registry for easier discovery