MCP Server Management: Interactive config, validation, and transparency

Problem

Managing MCP servers in Claude Code is confusing and error-prone. There are multiple valid configuration locations, no visibility into what's actually loaded, and no way to validate config before restarting. Users encounter silent failures with no feedback.

Issues Encountered

1. Silent config ignore with no feedback — A .claude/mcp.json in a project directory was silently ignored because the directory wasn't a git repository. No warning, no error, no indication that a config file was found but skipped. Users are left guessing why their server doesn't appear.

1. Multiple config locations with unclear precedence — There are at least three valid locations (~/.claude/mcp.json, .claude/mcp.json, .mcp.json), but it's not transparent which ones are active, which are ignored, and what takes precedence when there are conflicts or overlapping server names.

1. No visibility into loaded servers and their source — /mcp shows servers but doesn't indicate which config file each server was loaded from. When debugging, this is the first thing you need to know.

1. Restart-to-discover cycle — You edit a config file, restart Claude Code, and only then find out if it worked. There's no pre-validation step.

1. settings.local.json confusion — Users naturally try to put mcpServers in settings.local.json (since other settings go there), but it's silently ignored. This is a common pitfall.

Proposed Solution

1. Interactive MCP Server Management (/mcp manage or /mcp config)

A menu-driven interface for managing MCP servers:

MCP Server Management
━━━━━━━━━━━━━━━━━━━━━

Loaded servers:
  ✅ playwright          ~/.claude/mcp.json (global)
  ✅ billing             ~/.claude/mcp.json (global)
  ✅ mongodb             ~/.claude/mcp.json (global)
  ⚠️  staging_mongodb    .claude/mcp.json (project) — SKIPPED: not a git repo

Actions:
  [1] Add a new MCP server
  [2] Edit an existing server
  [3] Remove a server
  [4] Move server between config files
  [5] Validate all config files
  [6] Reload MCP servers

2. Config Validation Before Restart

When a config file is created or modified, validate:

• JSON syntax is correct
• Required fields (command, args) are present
• The command binary exists and is executable (npx, uvx, etc.)
• Environment variables reference valid patterns
• Warn about duplicate server names across config files

Display validation results immediately:

Validating .mcp.json...
  ✅ JSON syntax valid
  ✅ staging_mongodb: command "npx" found
  ✅ staging_mongodb: required fields present
  ⚠️  staging_mongodb: env var MDB_MCP_CONNECTION_STRING contains credentials — consider using a secrets manager

Ready to load. Restart Claude Code or run /mcp reload.

3. Transparent Server Source Display

Enhance /mcp output to always show the source config file:

MCP Servers
━━━━━━━━━━━

  playwright              ✅ connected    ~/.claude/mcp.json
  billing                 ✅ connected    ~/.claude/mcp.json
  mongodb                 ✅ connected    ~/.claude/mcp.json
  staging_mongodb         ✅ connected    .mcp.json

Skipped configs:
  .claude/mcp.json        ⚠️  project not a git repo (1 server defined)

4. Warnings for Common Pitfalls

Proactively warn when:

• An mcpServers block is found in settings.local.json (invalid location)
• A .claude/mcp.json exists in a non-git directory
• A config file has valid JSON but no servers would be loaded from it
• Duplicate server names exist across config files (which one wins?)

5. Hot Reload Support

Allow /mcp reload to pick up config changes without a full Claude Code restart. If hot reload isn't feasible for all cases, at least validate the new config and confirm it will work before the user restarts.

Why This Matters

MCP servers are a core extensibility mechanism. The current UX assumes users already know the config file hierarchy, precedence rules, and project-detection requirements. Every minute spent debugging "why isn't my MCP server loading" is a minute not spent on actual work. A more guided, transparent experience would significantly reduce friction — especially for new users setting up their first MCP server.