MCP Configuration Inconsistency: CLI-managed vs File-based configs

Problem

There's an architectural inconsistency in how MCP server configurations are managed in Claude Code:

1. CLI-managed configs (claude mcp add) are stored internally and not visible in file system
2. File-based configs (.mcp.json) are documented but create separate configuration system
3. This creates confusion and breaks discoverability/editability expectations

Current Behavior

When using claude mcp add:

claude mcp add task-master-ai npx -y --package=task-master-ai task-master-ai
claude mcp list  # Shows the server

• Server appears in claude mcp list
• No configuration file is created in standard locations:
• ~/.claude/mcp.json (user-global)
• .claude/mcp.json (project-local)
• .mcp.json (project root)

Expected Behavior

CLI-managed MCP servers should be stored in discoverable configuration files following the same pattern as other Claude Code settings:

• Global servers: ~/.claude/mcp.json
• Project servers: .claude/mcp.json or .claude/mcp.local.json

This would align with the existing settings hierarchy:

• ~/.claude/settings.json (user settings)
• .claude/settings.json (project settings)
• .claude/settings.local.json (local project settings)

Benefits of Unified Approach

1. Discoverability: Users can see what MCP servers are configured
2. Editability: Manual editing of configurations when needed
3. Consistency: Same pattern as other Claude Code settings
4. Transparency: No hidden internal storage
5. Version Control: Project-scoped configs can be committed/shared

Environment

• Claude Code CLI version: [current]
• Platform: Linux
• Configuration locations checked:
• ~/.claude/ (contains settings.json, config.json, but no mcp.json)
• Project .claude/ directory
• Project .mcp.json

Related Documentation

The MCP documentation mentions .mcp.json for project-scoped configs, but doesn't clarify the relationship with CLI-managed configs.