Skip to main content

​
Common Issues

This guide helps you resolve common problems when using the Perplexity MCP Server.
Symptoms:
  • Error: “PERPLEXITY_API_KEY environment variable is required”
  • 401 Unauthorized errors
  • Authentication failures
Solutions:
  1. Verify your API key is set correctly in your configuration file
  2. Check that there are no extra spaces or quotes around the key
  3. Ensure you’re using a valid API key from the Perplexity API Portal
  4. Try regenerating your API key if it may have been revoked
Test your API key:
# Check if the environment variable is set
echo $PERPLEXITY_API_KEY

# Test with curl
curl -X POST https://api.perplexity.ai/chat/completions \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"sonar-pro","messages":[{"role":"user","content":"test"}]}'
Symptoms:
  • “Network error while calling Perplexity API”
  • Connection timeout
  • DNS resolution failures
Solutions:
  1. Check your internet connection
  2. Verify that api.perplexity.ai is accessible from your network
  3. If behind a corporate firewall, configure proxy settings (see Proxy Issues)
  4. Check if your firewall or antivirus is blocking the connection
  5. Verify DNS resolution: nslookup api.perplexity.ai
Try accessing https://api.perplexity.ai directly in your browser to verify connectivity.
Symptoms:
  • MCP client reports “Tool not found” or “Server not available”
  • Perplexity tools don’t appear in your client
Solutions:
  1. Verify the package is installed correctly: 
    npx @perplexity-ai/mcp-server --version
  2. Check that the command path in your configuration is correct
  3. Ensure npx is available in your PATH
  4. Try clearing the npx cache: 
    npx clear-npx-cache
  5. Restart your MCP client after making configuration changes
For Cursor, Claude Desktop, and similar clients, the configuration file must be valid JSON with no syntax errors.
Symptoms:
  • “Request timeout: Perplexity API did not respond within Xms”
  • Long-running research queries fail
Solutions:
  1. Increase the timeout value by setting PERPLEXITY_TIMEOUT_MS (default: 300000ms / 5 minutes): 
    {
  "mcpServers": {
    "perplexity": {
      "command": "npx",
      "args": ["-y", "@perplexity-ai/mcp-server"],
      "env": {
        "PERPLEXITY_API_KEY": "your_key_here",
        "PERPLEXITY_TIMEOUT_MS": "600000"
      }
    }
  }
}
  2. For perplexity_research, consider setting timeout to 10+ minutes (600000ms)
  3. Check your network stability - intermittent connections can cause timeouts
The perplexity_research tool using sonar-deep-research model typically takes 30+ seconds to complete.
Symptoms:
  • Connection errors when behind a corporate firewall
  • Proxy authentication failures
  • SSL/TLS certificate errors
Solutions:
  1. Set the PERPLEXITY_PROXY environment variable: 
    {
  "mcpServers": {
    "perplexity": {
      "command": "npx",
      "args": ["-y", "@perplexity-ai/mcp-server"],
      "env": {
        "PERPLEXITY_API_KEY": "your_key_here",
        "PERPLEXITY_PROXY": "https://proxy.example.com:8080"
      }
    }
  }
}
  2. For authenticated proxies, include credentials: 
    PERPLEXITY_PROXY=https://username:password@proxy.example.com:8080
  3. Alternatively, use standard proxy environment variables: HTTPS_PROXY or HTTP_PROXY
  4. Ensure api.perplexity.ai is not blocked by your firewall
  5. Verify your proxy settings with your IT department
The server checks proxy settings in this order: PERPLEXITY_PROXY → HTTPS_PROXY → HTTP_PROXY. URLs must include the protocol (https://).
Symptoms:
  • “Unexpected EOF” during server initialization
  • “Failed to initialize” errors
  • MCP client can’t connect to server
Solutions:
  1. Some strict MCP clients fail because npx writes installation messages to stdout
  2. Use npx -yq (quiet mode) instead of npx -y: 
    {
  "mcpServers": {
    "perplexity": {
      "command": "npx",
      "args": ["-yq", "@perplexity-ai/mcp-server"],
      "env": {
        "PERPLEXITY_API_KEY": "your_key_here"
      }
    }
  }
}
  3. Clear the npx cache: npx clear-npx-cache
  4. Ensure you have the latest version of Node.js and npm
The -q flag suppresses npx installation output, which can interfere with MCP protocol initialization.

​
Debugging Tips

​
Enable Debug Logging

Set the log level to see detailed error information: 
{
  "mcpServers": {
    "perplexity": {
      "command": "npx",
      "args": ["-y", "@perplexity-ai/mcp-server"],
      "env": {
        "PERPLEXITY_API_KEY": "your_key_here",
        "PERPLEXITY_LOG_LEVEL": "DEBUG"
      }
    }
  }
}
Available log levels: DEBUG, INFO, WARN, ERROR (default: ERROR)

​
Check Server Logs

Most MCP clients store server logs in a specific location:
  • Cursor: Check the output panel or logs directory
  • Claude Desktop: ~/Library/Logs/Claude/ (macOS) or %APPDATA%\Claude\logs\ (Windows)
  • VS Code: Check the MCP extension output panel

​
Verify API Connectivity

Test the Perplexity API directly: 
curl -X POST https://api.perplexity.ai/chat/completions \
  -H "Authorization: Bearer your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sonar-pro",
    "messages": [
      {"role": "user", "content": "Hello"}
    ]
  }'

​
Check Network Configuration

Verify your network setup: 
# Test DNS resolution
nslookup api.perplexity.ai

# Test HTTPS connectivity
curl -v https://api.perplexity.ai

# Check proxy settings
echo $HTTPS_PROXY
echo $HTTP_PROXY
echo $PERPLEXITY_PROXY

​
Getting Help

If you’re still experiencing issues:
  1. Community Support: Visit community.perplexity.ai to ask questions and share solutions
  2. GitHub Issues: Report a bug or search for existing issues
  3. Documentation: Review the Configuration and Tools sections
When reporting issues, please include:
  • Your MCP client name and version
  • Your configuration (with API key redacted)
  • Error messages and logs
  • Steps to reproduce the issue