beginner⏱️ 22-32 minutes📅 Updated June 2026

Step-by-step guide to integrate Perplexity MCP Server MCP server with Windsurf Editor. Includes web search and conversational ai search.

Perplexity MCP Server + Windsurf Editor: Complete MCP Integration

Perplexity MCP Server is a MCP server that The official MCP server implementation for Perplexity API Platform. Provides real-time web search, deep research, and advanced reasoning capabilities through Sonar AI models and the Search API..

When integrated with Windsurf Editor, you can:

  • Direct web search using Perplexity Search API with ranked results
  • General-purpose AI with real-time web integration for everyday questions
  • Comprehensive research with thorough analysis and citations

This guide provides step-by-step instructions to set up Perplexity MCP Server in Windsurf Editor, including configuration, examples, and troubleshooting.

What You'll Achieve

After completing this setup:

  • Perplexity MCP Server will be fully integrated and operational
  • You can use Perplexity MCP Server tools directly in Windsurf Editor
  • All Perplexity MCP Server capabilities will be available for your workflows
  • Access to 4 different tools

Prerequisites

Before starting, ensure you have:

  • Node.js 18+
  • npm or npx
  • Perplexity API key
  • Your Perplexity API key for authentication with Sonar models
  • Windsurf Editor installed and configured
  • Compatible operating system (Desktop App)

Installation

Step 1: Install Perplexity MCP Server

Install using npm:

npx -y perplexity-mcp

Verify installation:

Server starts and connects to MCP client

Configuration

Step 2: Configure Windsurf Editor

  1. Locate your configuration file:

    • Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json
    • macOS: ~/.codeium/windsurf/mcp_config.json
    • Linux: ~/.codeium/windsurf/mcp_config.json

  2. Add server configuration:

{
  "mcpServers": {
    "perplexity-mcp-server": {
      "command": "npx",
      "args": ["-y", "perplexity-mcp"]
    }
  }
}

Note: If Perplexity MCP Server requires environment variables, add them to the server configuration:
"env": {
  "PERPLEXITY_API_KEY": "pplx-xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "PERPLEXITY_TIMEOUT_MS": "300000",
        "PERPLEXITY_PROXY": "https://username:password@proxy-host:port",
        "PORT": "3000",
        "BIND_ADDRESS": "0.0.0.0",
        "ALLOWED_ORIGINS": "https://yourdomain.com"
}
  1. Restart Windsurf Editor

Completely quit and restart Windsurf Editor to load the new configuration.

Examples

Once configured, you can use Perplexity MCP Server in Windsurf Editor:

Real-Time Web Search

Search the web for current information and get ranked results

Ask Windsurf Editor: "Search for the latest Model Context Protocol updates and announcements"

Expected Result: Ranked search results with titles, URLs, snippets, and metadata about MCP developments

Quick Factual Queries

Get immediate answers to questions with web-backed accuracy

Ask Windsurf Editor: "What are the system requirements for running Claude Desktop?"

Expected Result: Accurate, sourced answer with current system requirements and download links

Deep Technical Research

Comprehensive analysis of complex technical topics

Ask Windsurf Editor: "Research the differences between WebSocket, SSE, and HTTP polling for real-time applications"

Expected Result: Detailed comparison with citations, use cases, performance considerations, and recommendations

Complex Problem Analysis

Advanced reasoning for technical decision-making

Ask Windsurf Editor: "Analyze whether I should use Redis, Memcached, or PostgreSQL for caching in my Node.js application"

Expected Result: Step-by-step reasoning with trade-off analysis, benchmarks, and contextual recommendations

Testing Your Setup

  1. Launch Windsurf Editor
  2. Verify Perplexity MCP Server is available in the tools list
  3. Test basic Perplexity MCP Server functionality

Troubleshooting

Common Issues

API Key Invalid or Missing

Symptoms: 401 Unauthorized errors, Authentication failed messages, API key not found

Cause: PERPLEXITY_API_KEY environment variable not set or invalid

Solution:

  • Verify API key is set: echo $PERPLEXITY_API_KEY
  • Obtain valid key from https://www.perplexity.ai/account/api
  • Ensure key is exported in shell: export PERPLEXITY_API_KEY="pplx-xxx"
  • Check for typos or extra whitespace in key value

Connection Timeout

Symptoms: Request timeout errors, Server not responding, Long delays with no response

Cause: Network issues or timeout too short for deep research queries

Solution:

  • Increase timeout: export PERPLEXITY_TIMEOUT_MS=900000
  • Check internet connectivity
  • Verify firewall allows outbound HTTPS to api.perplexity.ai
  • For deep research, expect longer response times (2-5 minutes)

Proxy Configuration Errors

Symptoms: Connection refused, Proxy authentication failed, Network unreachable in corporate environment

Cause: Incorrect or missing proxy configuration for enterprise networks

Solution:

NPX Installation Fails

Symptoms: npx command not found, Package download errors, Permission denied

Cause: Node.js not installed or npm registry issues

Solution:

  • Install Node.js 18+ from https://nodejs.org
  • Clear npm cache: npm cache clean --force
  • Try with explicit version: npx -y perplexity-mcp@latest
  • Check npm registry connectivity

Strip Thinking Parameter Not Working

Symptoms: Response contains <think>...</think> tags, Excessive context token usage

Cause: strip_thinking parameter not passed correctly

Solution:

  • Include strip_thinking: true in perplexity_reason calls
  • This removes internal reasoning from responses
  • Reduces token usage while preserving final answers

Tools Not Appearing

Symptoms: Cascade does not see new tools, Hammer icon missing

Cause: Configuration syntax error or server failed to start.

Solution:

  • Check the JSON configuration for syntax errors.
  • Verify the command (e.g., npx, python) is in your system PATH.
  • Check Windsurf logs for MCP connection errors.

Environment Variables

Symptoms: Authentication failed, Permission denied

Cause: Missing API keys in configuration.

Solution:

  • Ensure env block is correctly defined inside the server config.
  • Restart Windsurf after changing environment variables.

Perplexity MCP Server not appearing in Windsurf Editor

Symptoms: Server not listed, Tools not available

Cause: Configuration or installation issue

Solution:

  • Verify configuration syntax
  • Check Perplexity MCP Server installation
  • Restart Windsurf Editor
  • Check logs for error messages

Next Steps

Now that Perplexity MCP Server is integrated with Windsurf Editor:

  • Explore all Perplexity MCP Server capabilities through Windsurf Editor
  • Check out other MCP servers that work with Windsurf Editor
  • Join the MCP community for tips and support
  • Consider contributing to Perplexity MCP Server development

Need Help?

Related Resources

More Integrations

Explore other MCP servers that work with Windsurf Editor

Need Help?

Join the MCP community for support and discussions

Perplexity MCP Server + Windsurf Editor: MCP Setup Guide (2026)