MCP Server Troubleshooting#

Fix common MCP issues 🔧

Quick Checklist#

• Node.js 18+ installed (node --version)
• MCP server built (npm run build)
• API token starts with moa_
• Config file has correct path to dist/index.js
• Claude Desktop restarted after config changes

Common Issues#

Claude Shows No 🔌 Icon#

Cause: MCP server not loaded

Solutions:

1. Check config file location

   # macOS
   cat ~/Library/Application\ Support/Claude/claude_desktop_config.json
   
   # Windows
   type %APPDATA%\Claude\claude_desktop_config.json

2. Validate JSON

   # macOS/Linux
   cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | jq .
   
   # Should output formatted JSON, not error

3. Check path to server

   # Verify file exists
   ls /path/to/memofai-mcp-server/dist/index.js

4. Restart Claude completely

   • Quit Claude (Cmd+Q / Alt+F4)
   • Wait 5 seconds
   • Reopen Claude

"Invalid API Token"#

Cause: Wrong or malformed token

Solutions:

1. Check token format

   // ✅ Correct
   "MEMOFAI_API_TOKEN": "moa_abc123xyz..."
   
   // ❌ Wrong
   "MEMOFAI_API_TOKEN": "your_token_here"
   "MEMOFAI_API_TOKEN": moa_abc123  // Missing quotes

2. Get fresh token

   • Visit memof.ai
   • Generate new API token
   • Update config

3. Check for whitespace

   // ❌ Has spaces
   "MEMOFAI_API_TOKEN": " moa_token "
   
   // ✅ No spaces
   "MEMOFAI_API_TOKEN": "moa_token"

"Connection Refused"#

Cause: Wrong environment or network issue

Solutions:

1. Check environment

   "MEMOFAI_ENVIRONMENT": "production"  // ✅ Correct
   "MEMOFAI_ENVIRONMENT": "prod"        // ❌ Wrong

2. Test connectivity

   curl https://api.memof.ai/api/workspaces/workspaces \
     -H "Authorization: Bearer moa_your_token"

3. Check proxy/VPN

   • Disable VPN temporarily
   • Check firewall settings

"Module not found"#

Cause: Dependencies not installed or not built

Solutions:

# Navigate to MCP server directory
cd memofai-mcp-server

# Install dependencies
npm install

# Build
npm run build

# Verify dist/ exists
ls dist/index.js

Tools Not Showing in Claude#

Cause: Server loaded but not working

Solutions:

1. Test with inspector

   export MEMOFAI_API_TOKEN="moa_your_token"
   npx @modelcontextprotocol/inspector node dist/index.js

2. Check Claude logs

   # macOS
   tail -f ~/Library/Logs/Claude/mcp*.log
   
   # Look for errors

3. Verify tools load In inspector, should see all memofai_ tools

"Command not found: node"#

Cause: Node not in PATH or wrong path

Solutions:

1. Find node location

   which node
   # Output: /usr/local/bin/node

2. Use full path in config

   {
     "mcpServers": {
       "memofai": {
         "command": "/usr/local/bin/node",  // Full path
         "args": ["..."]
       }
     }
   }

3. Install Node if missing

   # macOS (Homebrew)
   brew install node
   
   # Windows (Chocolatey)
   choco install nodejs
   
   # Or download from nodejs.org

Testing Your Setup#

Step 1: Test Server Directly#

cd memofai-mcp-server

# Set token
export MEMOFAI_API_TOKEN="moa_your_token"

# Run server
node dist/index.js

Should not error immediately.

Step 2: Test with Inspector#

npx @modelcontextprotocol/inspector node dist/index.js

Opens http://localhost:5173. Try calling tools!

Step 3: Test in Claude#

Claude should use memofai_create_workspace tool.

Platform-Specific Issues#

macOS#

Issue: "Cannot read config file"

Fix: Check permissions

ls -la ~/Library/Application\ Support/Claude/
chmod 644 claude_desktop_config.json

Issue: "node: command not found"

Fix: Homebrew node location

which node
# Use output in config: /opt/homebrew/bin/node (M1/M2)
# Or: /usr/local/bin/node (Intel)

Windows#

Issue: Path with spaces

Fix: Use escaped backslashes

"args": ["C:\\Program Files\\memofai-mcp-server\\dist\\index.js"]

Issue: "Cannot find module"

Fix: Use forward slashes or double backslashes

// ✅ Works
"C:/Users/Name/memofai-mcp-server/dist/index.js"
"C:\\Users\\Name\\memofai-mcp-server\\dist\\index.js"

// ❌ Doesn't work
"C:\Users\Name\memofai-mcp-server\dist\index.js"

Linux#

Issue: Claude AppImage not reading config

Fix: Create config directory

mkdir -p ~/.config/Claude
touch ~/.config/Claude/claude_desktop_config.json

Debug Mode#

Enable debug logging:

{
  "mcpServers": {
    "memofai": {
      "command": "node",
      "args": ["/path/to/dist/index.js"],
      "env": {
        "MEMOFAI_API_TOKEN": "moa_token",
        "DEBUG": "true",
        "NODE_ENV": "development"
      }
    }
  }
}

Getting Help#

Information to Include#

When asking for help, provide:

1. Node version

   node --version

2. Config file (redact token!)

   cat ~/.../claude_desktop_config.json | sed 's/moa_[^ ]*/moa_REDACTED/g'

3. Error message

   • From Claude
   • From logs
   • From inspector

4. What you've tried

   • List troubleshooting steps already attempted

Contact#

• 📧 Email: support@memof.ai
• 🐛 GitHub: Issues
• 📚 Docs: You're here!

Solved? → Configuration | Tools Reference