Troubleshooting

Common issues and solutions for Pylee MCP server setup and usage

Troubleshooting

Having trouble with Pylee? This guide covers the most common issues and their solutions.

Quick Help: Most setup issues can be resolved by restarting your application completely and checking your API key. If problems persist, try the solutions below.

Common Issues and Solutions

Pylee MCP Server Not Appearing

Symptoms: Claude Desktop or other MCP clients don’t show Pylee as available

Solutions:

1. Verify Configuration File Location

   Ensure your config file is in the correct location:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json
2. Check JSON Syntax

   Validate your JSON configuration:

   {
     "mcpServers": {
       "pylee": {
         "command": "npx",
         "args": ["-y", "@pyleeai/pylee@latest"]
       }
     }
   }
   
3. Restart Application

   Completely quit and restart Claude Desktop (or your MCP client)

4. Check Node.js Installation

   Verify Node.js is installed:

   node --version
   npm --version
   

Connection Timeout Issues

Symptoms: MCP server starts but times out when trying to connect

Solutions:

1. Check Internet Connection

   Ensure you have a stable internet connection

2. Verify Firewall Settings

   Make sure your firewall isn’t blocking the connection:

   • Allow npx and node through your firewall
   • Check corporate firewall settings if applicable
3. Test Network Access

   # Test connection to Pylee API
   curl -I https://api.pyleeai.com/health
   
4. Try Alternative Configuration

   If using npx fails, try installing globally:

   npm install -g @pyleeai/mcp-server
   

   Then update your config to use:

   {
     "command": "pylee-mcp-server"
   }
   

Permission Denied Errors

Symptoms: Errors about file permissions or access denied

Solutions:

1. Check File Permissions

   Ensure you can read/write the configuration file:

   # macOS/Linux
   ls -la "~/Library/Application Support/Claude/"
   # or
   ls -la ~/.config/Claude/
   
2. Create Directory if Missing

   # macOS
   mkdir -p "~/Library/Application Support/Claude"
   
   # Linux
   mkdir -p ~/.config/Claude
   
3. Fix Ownership (macOS/Linux)

   # macOS
   sudo chown -R $(whoami) "~/Library/Application Support/Claude"
   
   # Linux  
   sudo chown -R $(whoami) ~/.config/Claude
   
4. Run as Administrator (Windows)

   Try running your text editor as Administrator when editing the config file

Node.js or NPM Issues

Symptoms: Commands not found or version conflicts

Solutions:

macOS

# Install Node.js via Homebrew
brew install node

# Or use Node Version Manager
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install node
nvm use node

Windows

1. Download Node.js from nodejs.org
2. Run the installer as Administrator
3. Restart your command prompt/PowerShell
4. Verify installation:

node --version
npm --version

Linux

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

# Fedora
sudo dnf install nodejs npm

# Arch Linux
sudo pacman -S nodejs npm

Registry Not Loading

Symptoms: Pylee connects but no registry servers are available

Solutions:

1. Check Registry Status

   1. Log into Pylee Dashboard
   2. Go to “Active Registries”
   3. Verify your registries are activated
2. Refresh Registry

   In your dashboard, click “Refresh” on your active registries

3. Check Permissions

   Ensure you have access to the registries you’re trying to use

4. Test with Different Registry

   Try activating a different registry to isolate the issue

Platform-Specific Issues

macOS

Common macOS Issues

Gatekeeper blocking execution:

# Allow npx to run
sudo spctl --master-disable
# Run your MCP client, then re-enable:
sudo spctl --master-enable

SIP (System Integrity Protection) issues:

• Use Homebrew to install Node.js instead of the system installer
• Avoid modifying system directories

Permission issues with Application Support:

# Fix permissions
sudo chown -R $(whoami) "~/Library/Application Support"

Windows

Common Windows Issues

Execution policy restrictions:

# Run PowerShell as Administrator
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Path issues:

• Add Node.js to your PATH environment variable
• Restart command prompt after installing Node.js

AppData access issues:

• Run text editor as Administrator
• Check that %APPDATA% environment variable is set correctly

Linux

Common Linux Issues

Snap-installed applications:

• Snap packages may have restricted file system access
• Install Node.js via your package manager instead

Permission issues:

# Fix npm permissions
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

SELinux restrictions:

# Temporarily disable SELinux (if applicable)
sudo setenforce 0

WSL

Common WSL Issues

Mixed Windows/Linux paths:

• Keep configuration files in Linux filesystem for better performance
• Use Linux paths in your configuration

Node.js installation:

# Install via package manager, not Windows installer
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

File system permissions:

# Ensure proper permissions
sudo chown -R $(whoami) ~/.config

Getting Debug Information

If you’re still having issues, gather this information before contacting support:

1. System Information

   # Check versions
   node --version
   npm --version
   
   # Check OS
   uname -a  # macOS/Linux
   # or
   systeminfo  # Windows
   
2. Configuration File

   Verify your configuration file exists and has correct content:

   # macOS
   cat "~/Library/Application Support/Claude/claude_desktop_config.json"
   
   # Linux
   cat ~/.config/Claude/claude_desktop_config.json
   
   # Windows (PowerShell)
   Get-Content "$env:APPDATA\Claude\claude_desktop_config.json"
   
3. Test MCP Server Directly

   # Test if the MCP server starts
   npx @pyleeai/pylee@latest
   
4. Check Network Connectivity

   # Test API connectivity
   curl -v https://api.pyleeai.com/health
   

Still Need Help?

Contact Support

Email us with your debug information

Community Discord

Get help from the community

GitHub Issues

Report bugs or request features

Documentation

Review the full documentation

When contacting support, please include:

• Your operating system and version
• Node.js and npm versions
• Your configuration file (with API key redacted)
• Any error messages you’re seeing
• Steps you’ve already tried

Additional Resources

Getting Started Guide

Review the initial setup process

Registry Activation

Learn about managing MCP server registries

Configuration Guide

Advanced configuration options

Community Support

Connect with other Pylee users

Reporting Issues

If you can’t find a solution to your problem:

1. Check our GitHub Issues - Someone may have already reported the same issue
2. Search the documentation - Use the search function to find relevant information
3. Contact support - Include detailed information about your setup and the issue you’re experiencing

When reporting issues, please include your operating system, Node.js version, and any error messages you’re seeing. This helps us provide better support.