Claude MCP Server Ecosystem

# Claude Code MCP Configuration Troubleshooting ## 🚨 CRITICAL: Configuration Cleanup Session - May 26, 2025 ### Problem Identified & RESOLVED Multiple redundant and conflicting MCP configuration files were causing: - `memory-simple-user` MCP server to persist despite removal attempts - Conflicting permissions across multiple settings files - Non-standard configuration files that don't follow official Claude Code practices ### ✅ RESOLUTION COMPLETED - May 26, 2025 Session **Status**: Configuration crisis fully resolved through complete file deletion approach **Final State**: Clean, standards-compliant configuration with 11 MCP servers ### Root Cause Analysis **Issue:** Claude Code was using **project-scoped** `.mcp.json` files instead of the intended **user-scoped** configuration, causing persistent connections to unwanted MCP servers. **Evidence Found:** 1. **13 config files** with `memory-simple` references in project directory 2. **Multiple `.mcp.json` files** in different locations 3. **Non-standard `claude_code_config*.json`** files (not in official docs) 4. **Conflicting settings** across `settings.local.json`, `settings.global.json`, etc. ### Files Containing memory-simple References (Found May 26, 2025) ``` /Users/robertlee/GitHubProjects/Claude_MCPServer/mcp_config.json /Users/robertlee/GitHubProjects/Claude_MCPServer/config/claude-code/claude_code_config_absolute.json /Users/robertlee/GitHubProjects/Claude_MCPServer/config/claude-code/claude_code_config_wrapper.json /Users/robertlee/GitHubProjects/Claude_MCPServer/config/claude-code/claude_code_config_fixed.json /Users/robertlee/GitHubProjects/Claude_MCPServer/config/claude-code/claude_code_config_backup.json /Users/robertlee/GitHubProjects/Claude_MCPServer/config/claude-code/claude_code_config_simple.json /Users/robertlee/GitHubProjects/Claude_MCPServer/config/claude-code/claude_code_config.json /Users/robertlee/GitHubProjects/Claude_MCPServer/config/claude-code/claude_code_config_minimal.json /Users/robertlee/GitHubProjects/Claude_MCPServer/config/claude-desktop/claude_desktop_config.json /Users/robertlee/GitHubProjects/Claude_MCPServer/.claude/claude_desktop_config.json /Users/robertlee/GitHubProjects/Claude_MCPServer/.claude/settings.local.json /Users/robertlee/GitHubProjects/Claude_MCPServer/mcp_test_results.json /Users/robertlee/GitHubProjects/Claude_MCPServer/Support/Claude/claude_desktop_config.json ``` ## ✅ SOLUTION IMPLEMENTED ### Phase 1: Global Configuration Cleanup (Completed) 1. **Removed non-standard files**: All `claude_code_config*.json` files (not in official docs) 2. **Consolidated settings**: Single `~/.claude/settings.json` with proper permissions 3. **Eliminated conflicts**: Removed redundant `settings.local.json`, `settings.global.json` ### Phase 2: User-Scoped MCP Configuration (Completed) Used official Claude Code commands to configure MCP servers with **user scope**: ```bash claude mcp add memory-enhanced -s user "node" "/path/to/enhanced-server-stdio.js" -e MEMORY_ID=memory-enhanced claude mcp add sequential-thinking -s user -- npx -y @modelcontextprotocol/server-sequential-thinking claude mcp add data-pipeline -s user "npx" "tsx" "/path/to/data-pipeline.ts" -e DATA_PIPELINE_ID=data-pipeline-server claude mcp add data-governance -s user "npx" "tsx" "/path/to/data-governance.ts" -e DATA_GOVERNANCE_ID=data-governance-server claude mcp add filesystem-standard -s user -- npx -y @modelcontextprotocol/server-filesystem /Users/robertlee ``` ### Phase 3: Project Files Still Causing Issues (IN PROGRESS) **CRITICAL FINDING**: Memory-simple-user still appears because project-level config files override user settings. ## 🔥 IMMEDIATE ACTION REQUIRED ### ✅ FINAL SOLUTION IMPLEMENTED: Complete File Deletion **UPDATE May 26, 2025**: The cleanup script approach was abandoned in favor of complete file deletion for cleaner resolution. **ACTUAL RESOLUTION EXECUTED:** ```bash # Deleted all non-standard configuration files entirely rm /Users/robertlee/GitHubProjects/Claude_MCPServer/mcp_config.json rm -rf /Users/robertlee/GitHubProjects/Claude_MCPServer/config/claude-code/ rm -rf /Users/robertlee/GitHubProjects/Claude_MCPServer/config/claude-desktop/ rm -rf /Users/robertlee/GitHubProjects/Claude_MCPServer/.claude/ rm /Users/robertlee/GitHubProjects/Claude_MCPServer/mcp_test_results.json rm -rf /Users/robertlee/GitHubProjects/Claude_MCPServer/Support/Claude/ rm ~/.claude/settings.local.json # Result: Zero project configuration files, clean user-scoped setup ``` **What this script does:** 1. **Backs up all files** before making changes 2. **Removes memory-simple references** from all 13 identified files 3. **Verifies the cleanup** was successful 4. **Shows exact MCP status** before and after 5. **Provides rollback instructions** if needed ### Expected Output After Running Script: **BEFORE (current broken state):** ```bash $ mcp MCP Server Status • data-governance: connected • data-pipeline: connected • filesystem-standard: connected • memory-enhanced: connected • memory-simple-user: connected ← THIS SHOULD BE GONE • sequential-thinking: connected ``` **AFTER (expected clean state):** ```bash $ mcp MCP Server Status • data-governance: connected • data-pipeline: connected • filesystem-standard: connected • memory-enhanced: connected • sequential-thinking: connected ``` ### Manual Steps (if script fails): **Step 1: Identify problematic files** ```bash find . -name "*.json" -not -path "./node_modules/*" | xargs grep -l "memory-simple" ``` **Step 2: Clean each file** For each file found, remove the memory-simple-user server block: **Example - Before cleanup (`mcp_config.json`):** ```json { "mcpServers": { "memory-simple-user": { "command": "node", "args": ["/path/to/simple-server.js"] }, "other-server": { "command": "node", "args": ["/path/to/other.js"] } } } ``` **Example - After cleanup:** ```json { "mcpServers": { "other-server": { "command": "node", "args": ["/path/to/other.js"] } } } ``` **Step 3: Verify cleanup** ```bash # Should show NO memory-simple references find . -name "*.json" -not -path "./node_modules/*" | xargs grep "memory-simple" # Should show clean MCP status (no memory-simple-user) mcp ``` ## 📋 CONFIGURATION BEST PRACTICES (Based on Research) ### Official Claude Code MCP Scopes 1. **`local`** (default): Available only in current project 2. **`user`** (recommended): Available across all projects on your machine 3. **`project`**: Shared with team via `.mcp.json` (checked into git) ### Configuration Hierarchy (Precedence Order) 1. Enterprise policies 2. Command line arguments 3. **Local project settings** (`.mcp.json` - THIS WAS OVERRIDING OUR USER CONFIG) 4. Shared project settings 5. User settings ### Why User Scope is Recommended - ✅ **Works reliably** (global scope has known bugs in Claude Code) - ✅ **Available everywhere** without custom config files - ✅ **Standards compliant** with official documentation - ✅ **Persistent** across Claude Code restarts ## 🚫 ANTI-PATTERNS TO AVOID ### Non-Standard Configuration Files - ❌ `claude_code_config*.json` (not in official docs) - ❌ Multiple conflicting `settings*.json` files - ❌ Custom config file paths passed to `--mcp-config` ### Configuration Conflicts - ❌ Mixing project-scoped and user-scoped servers with same names - ❌ Having multiple `.mcp.json` files in different locations - ❌ Relying on non-standard startup commands ## 🎯 FINAL SOLUTION VERIFICATION ### Expected State After Complete Cleanup ```bash # This should show only desired servers, NO memory-simple-user mcp # This should show user-scoped servers claude mcp list # This should start cleanly without custom config claude ``` ### Clean Directory Structure ``` ~/.claude/ ├── settings.json (single, clean file) └── todos/ (normal operation files) # NO OTHER CONFIG FILES ``` ## 📝 LESSONS LEARNED ### Why This Happened 1. **Incremental configuration** led to multiple config files 2. **Project-scope overrides** user-scope in hierarchy 3. **Non-standard practices** created confusion 4. **Insufficient cleanup** of legacy config files ### Prevention Strategy 1. **Always use user-scoped MCP configuration** for personal servers 2. **Avoid custom config files** unless absolutely necessary 3. **Regular config audits** to prevent accumulation 4. **Follow official documentation strictly** ## ✅ RESOLUTION STATUS - May 26, 2025 ### COMPLETED ACTIONS 1. ✅ **Complete project file cleanup** - ALL 13 non-standard files deleted entirely 2. ✅ **Added 11 MCP servers** - Complete production-ready MCP server configuration 3. ✅ **Verified clean state** - Single settings.json file, user-scoped configuration 4. ✅ **Updated permissions** - All 11 servers have proper permissions in settings.json ### FINAL CONFIGURATION STATE **MCP Servers (11 total):** 1. memory-enhanced 2. data-pipeline 3. data-governance 4. sequential-thinking 5. filesystem-standard 6. realtime-analytics 7. data-warehouse 8. ml-deployment 9. security-vulnerability 10. optimization 11. ui-design **Configuration Files:** - ✅ `~/.claude/settings.json` (ONLY config file) - ✅ Zero project configuration files - ✅ Standards-compliant user-scoped setup ### STARTUP COMMAND ```bash claude # Standard startup, no custom configs needed ``` ### Future Prevention (IMPLEMENTED) 1. ✅ **Documentation created** - Complete troubleshooting and reference guides 2. ✅ **Standards established** - User-scoped configuration only 3. ✅ **Anti-patterns documented** - What never to do again --- **Last Updated**: May 26, 2025 - RESOLUTION COMPLETE **Status**: ✅ RESOLVED - Configuration crisis fully addressed **Next Action**: Resume Week 12 development with clean 11-server MCP setup