Troubleshooting

This document provides diagnostic guidance and solutions for common issues encountered when deploying, configuring, or using the Perplexity MCP Server. It covers error classification, resolution steps, and debugging techniques for both STDIO and HTTP deployment modes.

For configuration reference, see Configuration. For deployment options, see Deployment. For client integration setup, see Client Integration.

---

Error Classification System

The server implements structured error handling across multiple layers. Errors are classified by origin and propagated with diagnostic context.

Sources: src/server.ts src/index.ts src/http.ts src/logger.ts README.md170-179

---

API Key Issues

Symptom: 401 Unauthorized

Error Message Pattern:

Error: Unauthorized - Invalid API key
Status: 401

Diagnostic Steps:

Check	Command/File	Expected Value
Environment Variable Set	echo $PERPLEXITY_API_KEY	Non-empty string starting with pplx-
Client Config (STDIO)	Check config file per Client Integration	"env": {"PERPLEXITY_API_KEY": "..."}
HTTP Server Config	docker exec <container> env | grep PERPLEXITY_API_KEY	API key present
Key Validity	Visit Perplexity API Portal	Key active and not revoked

Resolution:

1. STDIO Mode: Update client configuration file with valid key

   • Cursor: ~/.cursor/mcp.json
   • VS Code: .vscode/mcp.json
   • Claude Desktop: claude_desktop_config.json
   • Windsurf: ~/.codeium/windsurf/mcp_config.json

2. HTTP Mode: Set environment variable before server start

3. Docker Mode: Pass via -e flag or .env file

Code Path: The API key is checked at startup in src/index.ts and included as a Bearer token in request headers by proxyAwareFetch in src/server.ts Authentication failures surface as "Perplexity API error: 401 Unauthorized".

Sources: README.md32-38 README.md170-179 src/server.ts60-84

---

Connection and Network Issues

Symptom: ECONNREFUSED or ENOTFOUND

Error Message Patterns:

Error: connect ECONNREFUSED 127.0.0.1:8080
Error: getaddrinfo ENOTFOUND api.perplexity.ai

Diagnostic Commands:

Issue	Command	Expected Output
HTTP Server Running	curl http://localhost:8080/health	{"status":"healthy"}
DNS Resolution	nslookup api.perplexity.ai	IP address returned
Network Connectivity	curl -I https://api.perplexity.ai	HTTP 200 or 401
Proxy Connectivity	curl -x $PERPLEXITY_PROXY https://api.perplexity.ai	Connection successful

Resolution:

1. HTTP Server Not Running (HTTP mode only):

   • Verify server started: Check logs for Server started on http://0.0.0.0:8080/mcp
   • Check port binding: src/http.ts8-12 uses PORT environment variable (default: 8080)
   • Verify network interface: BIND_ADDRESS defaults to 0.0.0.0

2. DNS/Network Issues:

   • Enable debug logging: PERPLEXITY_LOG_LEVEL=DEBUG
   • Review proxy configuration: See Proxy Configuration Issues
   • Check firewall rules: Ensure outbound HTTPS to api.perplexity.ai:443 is allowed

3. Corporate Network:

   • Configure proxy: See README.md109-138 and Configuration

Sources: src/http.ts8-12 README.md140-169 README.md170-179

---

Timeout Configuration

Symptom: AbortError or ETIMEDOUT

Error Message Pattern:

Error: The operation was aborted due to timeout
Error: Request timeout after 300000ms

Default Timeout: 300,000ms (5 minutes) as defined in src/server.ts27

Timeout Hierarchy:

Resolution for Long-Running Queries:

Tool	Typical Duration	Recommended Timeout
perplexity_search	< 10s	30,000ms (30s)
perplexity_ask	10-30s	60,000ms (1m)
perplexity_research	60-300s	600,000ms (10m)
perplexity_reason	30-120s	300,000ms (5m)

Configuration Examples:

1. STDIO Mode - Update client config:

2. HTTP Mode - Set environment variable:

3. Docker Mode:

Code Reference: Timeout is configured at src/server.ts27 and enforced via AbortController in src/server.ts60-84 within proxyAwareFetch.

Sources: README.md36 README.md175 src/server.ts27 src/server.ts60-84

---

STDIO Transport Issues (npx Output Pollution)

Symptom: EOF Error or Initialize Failure

Error Message Pattern:

Error: Unexpected EOF
Error: Failed to initialize MCP connection
Error: Invalid JSON at position 0

Root Cause: npx writes package installation messages to stdout, which strict MCP clients interpret as protocol data, causing JSON parsing failures.

Resolution:

Replace npx -y with npx -yq in client configuration:

Client	Config File	Fix
Cursor	~/.cursor/mcp.json	"args": ["-yq", "@perplexity-ai/mcp-server"]
VS Code	.vscode/mcp.json	"args": ["-yq", "@perplexity-ai/mcp-server"]
Claude Desktop	claude_desktop_config.json	"args": ["-yq", "@perplexity-ai/mcp-server"]
Windsurf	~/.codeium/windsurf/mcp_config.json	"args": ["-yq", "@perplexity-ai/mcp-server"]

Example Configuration:

Alternative: Pre-install package globally to avoid npx caching checks:

Then use direct invocation:

Code Reference: The STDIO transport is initialized in src/index.ts9-34 using StdioServerTransport from the MCP SDK.

Sources: README.md177 src/index.ts9-34 package.json8-10

---

HTTP Server Issues

CORS Configuration Errors

Symptom: Browser console shows CORS policy errors

Error Message Pattern:

Access to fetch at 'http://localhost:8080/mcp' from origin 'http://localhost:3000' 
has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present

Resolution:

Configure ALLOWED_ORIGINS environment variable:

CORS Middleware Configuration: src/http.ts14-21 implements CORS using the cors package with origin validation.

Health Check Endpoint

Diagnostic Endpoint: GET /health

Expected Response:

Usage:

If health check fails:

1. Verify server process is running
2. Check PORT and BIND_ADDRESS configuration
3. Review startup logs with PERPLEXITY_LOG_LEVEL=DEBUG

Code Reference: Health endpoint defined at src/http.ts56-58

Sources: src/http.ts14-21 src/http.ts56-58 README.md140-169

---

Proxy Configuration Issues

Symptom: Connection Failures in Corporate Networks

Error Patterns:

Error: connect ETIMEDOUT
Error: Proxy connection failed
Error: tunneling socket could not be established

Proxy Resolution Chain:

Configuration Examples:

Scenario	Environment Variable	Example Value
Unauthenticated Proxy	PERPLEXITY_PROXY	https://proxy.company.com:8080
Authenticated Proxy	PERPLEXITY_PROXY	https://user:pass@proxy.company.com:8080
Standard HTTPS Proxy	HTTPS_PROXY	https://proxy.company.com:3128
Standard HTTP Proxy	HTTP_PROXY	http://proxy.company.com:80

Diagnostic Steps:

1. Test Proxy Connectivity:

2. Verify Proxy Environment Variables:

3. Enable Debug Logging:

4. Check Firewall Rules:

   • Ensure proxy server allows connections to api.perplexity.ai:443
   • Verify proxy authentication credentials if required

Common Issues:

Issue	Cause	Solution
SSL/TLS Errors	Corporate SSL inspection	Configure proxy with SSL pass-through or add corporate CA certificate
Authentication Failures	Invalid credentials	URL-encode special characters in username/password
Port Blocked	Firewall restricts proxy port	Confirm proxy port with IT, typically 8080, 3128, or 80
Protocol Mismatch	HTTP proxy for HTTPS traffic	Use https:// prefix in proxy URL, not http://

Code Reference: Proxy resolution logic is implemented in src/server.ts60-84 within the proxyAwareFetch function. The undici package's ProxyAgent is used for proxy support.

Sources: README.md109-138 src/server.ts60-84

---

Client Integration Issues

Tool Not Found Error

Symptom: Client reports that Perplexity tools are unavailable

Error Pattern:

Error: Tool 'perplexity_search' not found
Error: No MCP servers available

Diagnostic Steps:

1. Verify Package Installation:

2. Check Client Configuration File Syntax:

   • Validate JSON syntax (trailing commas, missing quotes)
   • Verify command and args fields match client's required format
   • Ensure file is in correct location per client documentation

3. Test Server Directly:

   Should start STDIO server without errors.

4. Review Client Logs:

   • Cursor: View MCP logs in developer console
   • VS Code: Check Output panel → MCP
   • Claude Desktop: Review application logs

Client-Specific Configuration Validation:

Client	Config Format	Wrapper Key
Cursor, Claude Desktop, Windsurf	JSON with mcpServers object	"mcpServers"
VS Code	JSON with servers object	"servers"
Generic MCP Clients	Varies by client	Check client documentation

Resolution:

If configuration is correct but tools still unavailable:

1. Restart the client application completely
2. Clear client cache (location varies by client)
3. Verify package version matches expected: package.json3
4. Try manual installation instead of npx

Sources: README.md54-107 README.md174 package.json3

---

Debugging Tools and Techniques

Logging Configuration

Enable detailed logging with PERPLEXITY_LOG_LEVEL:

Level	Verbosity	Use Case
ERROR	Minimal (default)	Production deployments
WARN	Warnings + Errors	Monitoring potential issues
INFO	Informational + Warnings + Errors	General diagnostics
DEBUG	Maximum verbosity	Development and troubleshooting

Example:

Logger Implementation: src/logger.ts provides structured logging with configurable levels.

Request Tracing

Enable debug logs to trace request flow:

Sources: src/logger.ts src/server.ts

Environment Variable Verification

Complete Checklist:

Testing Individual Tools

Direct Tool Invocation via MCP Client:

1. perplexity_search:

2. perplexity_ask:

3. perplexity_research:

4. perplexity_reason:

Sources: src/server.ts23-324 README.md11-28

---

Malformed API Response Errors

Symptom: Validation Errors from the API Response

The server validates the structure of every API response using Zod schemas (src/validation.ts). If the Perplexity API returns an unexpected shape, one of the following errors is thrown:

Error Message	Trigger Condition
missing or empty choices array	choices field is absent, null, or an empty array
missing message content	choices[0].message is null, missing, or content is not a string
Failed to parse JSON response	response.json() throws, or the response schema fails Zod validation
Unable to parse error response	Non-2xx response and response.text() also fails
Perplexity API error: <STATUS> <TEXT>	Non-2xx HTTP status from the Perplexity API (e.g., 401 Unauthorized, 500 Internal Server Error)

Resolution:

1. missing or empty choices array / missing message content: These indicate an API-side issue. Enable debug logging and retry. If persistent, file an issue with the response body.
2. Failed to parse JSON response: Transient network truncation or API schema change. Set PERPLEXITY_LOG_LEVEL=DEBUG to capture the raw response.
3. Perplexity API error: 401 Unauthorized: API key is invalid or revoked. See API Key Issues
4. Perplexity API error: 500 ...: Perplexity API side error. Retry after a short delay.

Code Reference: Response parsing and Zod validation occur in src/server.ts and src/validation.ts The validateMessages helper in src/server.ts validates the messages array before the API call is made and throws structured errors such as "Invalid arguments for <tool>: 'messages' must be an array" and "Invalid message at index <N>: ...".

Sources: src/validation.ts src/server.ts src/index.test.ts288-401

---

Getting Help

Information to Include in Bug Reports

When filing an issue at https://github.com/perplexityai/modelcontextprotocol/issues, include:

1. Environment:

   • Operating System and version
   • Node.js version (node --version)
   • Package version (npm list @perplexity-ai/mcp-server)
   • Deployment mode (STDIO or HTTP)
   • Client application and version

2. Configuration:

   • Sanitized configuration file (remove API key)
   • Relevant environment variables (sanitize sensitive values)
   • Proxy configuration if applicable

3. Error Details:

   • Complete error message and stack trace
   • Debug logs (PERPLEXITY_LOG_LEVEL=DEBUG)
   • Steps to reproduce the issue
   • Expected vs actual behavior

4. Diagnostic Output:

   • Output from npx @perplexity-ai/mcp-server --version
   • Network diagnostics if connection-related
   • Client logs if available

Community Resources

• Community Forum: https://community.perplexity.ai
• GitHub Issues: https://github.com/perplexityai/modelcontextprotocol/issues
• API Documentation: https://docs.perplexity.ai

Sources: README.md179