Skip to main content
This guide will help you quickly set up and start using the Perplexity MCP Server with your AI assistant.

​
Setup in 5 Minutes

1

Get Your API Key

Visit the Perplexity API Portal and generate an API key.
2

Configure Your Client

Choose your preferred MCP client and add the configuration:For Cursor (~/.cursor/mcp.json):
{
  "mcpServers": {
    "perplexity": {
      "command": "npx",
      "args": ["-y", "@perplexity-ai/mcp-server"],
      "env": {
        "PERPLEXITY_API_KEY": "your_key_here"
      }
    }
  }
}
For VS Code (.vscode/mcp.json):
{
  "servers": {
    "perplexity": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@perplexity-ai/mcp-server"],
      "env": {
        "PERPLEXITY_API_KEY": "your_key_here"
      }
    }
  }
}
For Claude Code (Terminal):
claude mcp add perplexity --env PERPLEXITY_API_KEY="your_key_here" -- npx -y @perplexity-ai/mcp-server
3

Restart Your Client

Close and reopen your MCP client to load the new configuration.
4

Verify Installation

Check that the four Perplexity tools appear in your client:
  • perplexity_search
  • perplexity_ask
  • perplexity_research
  • perplexity_reason
5

Try Your First Query

Ask a question to test the connection. For example: “What are the latest developments in AI?”
Use the one-click install buttons for Cursor or VS Code for even faster setup!

​
Your First Tool Call

Let’s use the perplexity_ask tool to answer a question with web-grounded AI.

​
Example: Quick Factual Question

The perplexity_ask tool uses the sonar-pro model to provide fast, web-grounded answers with citations: 
{
  "tool": "perplexity_ask",
  "arguments": {
    "messages": [
      {
        "role": "user",
        "content": "What is the current population of Tokyo?"
      }
    ]
  }
}
Response format: 
The current population of Tokyo is approximately 14 million people in the city proper, 
and around 37 million in the Greater Tokyo Area, making it the world's most populous 
metropolitan area.

Citations:
[1] https://www.tokyometro.jp/en/about/statistics.html
[2] https://www.statista.com/statistics/tokyo-population
All responses automatically include numbered citations to sources, making it easy to verify information.

​
Choosing the Right Tool

Each tool is optimized for different use cases: Best for: Finding specific URLs, recent news, verifying facts Example use case: “Find recent articles about climate change policy” 
{
  "tool": "perplexity_search",
  "arguments": {
    "query": "climate change policy 2024",
    "max_results": 5
  }
}
Returns ranked search results with titles, URLs, snippets, and dates.

​
perplexity_ask

Best for: Quick questions, summaries, explanations, general Q&A Example use case: “Explain quantum computing in simple terms” 
{
  "tool": "perplexity_ask",
  "arguments": {
    "messages": [
      {
        "role": "user",
        "content": "Explain quantum computing in simple terms"
      }
    ]
  }
}
Fastest option with web-grounded AI responses and citations.

​
perplexity_research

Best for: Deep analysis, literature reviews, comprehensive overviews Example use case: “Conduct a comprehensive review of renewable energy technologies” 
{
  "tool": "perplexity_research",
  "arguments": {
    "messages": [
      {
        "role": "user",
        "content": "Provide a comprehensive overview of current renewable energy technologies"
      }
    ],
    "reasoning_effort": "high"
  }
}
Significantly slower (30+ seconds) but provides thorough multi-source analysis.

​
perplexity_reason

Best for: Complex logic, mathematical problems, analytical tasks Example use case: “Compare the pros and cons of different database architectures” 
{
  "tool": "perplexity_reason",
  "arguments": {
    "messages": [
      {
        "role": "user",
        "content": "Compare SQL vs NoSQL databases for a high-traffic e-commerce platform"
      }
    ],
    "strip_thinking": false
  }
}
Provides step-by-step reasoning with web grounding and citations.

​
Advanced Features

​
Filtering by Recency

Get the most recent information by filtering results: 
{
  "tool": "perplexity_ask",
  "arguments": {
    "messages": [
      {
        "role": "user",
        "content": "What are the latest AI model releases?"
      }
    ],
    "search_recency_filter": "week"
  }
}
Options: hour, day, week, month, year

​
Domain Restrictions

Limit results to specific domains: 
{
  "tool": "perplexity_ask",
  "arguments": {
    "messages": [
      {
        "role": "user",
        "content": "Latest research on machine learning"
      }
    ],
    "search_domain_filter": ["arxiv.org", "scholar.google.com"]
  }
}
Use - prefix to exclude domains: ["-reddit.com"]

​
Search Context Size

Control how much web context is retrieved: 
{
  "tool": "perplexity_ask",
  "arguments": {
    "messages": [
      {
        "role": "user",
        "content": "Comprehensive analysis of blockchain technology"
      }
    ],
    "search_context_size": "high"
  }
}
Options: low (fastest, default), medium, high (most comprehensive)

​
Stripping Thinking Tokens

Save context tokens by removing internal reasoning: 
{
  "tool": "perplexity_reason",
  "arguments": {
    "messages": [
      {
        "role": "user",
        "content": "Solve this logic puzzle..."
      }
    ],
    "strip_thinking": true
  }
}
Set strip_thinking: true to remove <think>...</think> tags from responses.
Available only for perplexity_reason and perplexity_research tools.

​
Common Patterns

​
Multi-Turn Conversations

Build context with multiple messages: 
{
  "tool": "perplexity_ask",
  "arguments": {
    "messages": [
      {
        "role": "user",
        "content": "What is TypeScript?"
      },
      {
        "role": "assistant",
        "content": "TypeScript is a strongly typed programming language..."
      },
      {
        "role": "user",
        "content": "How does it compare to JavaScript?"
      }
    ]
  }
}

​
Regional Search Results

Get country-specific results with the search tool: 
{
  "tool": "perplexity_search",
  "arguments": {
    "query": "local news",
    "country": "GB"
  }
}
Use ISO 3166-1 alpha-2 country codes (e.g., US, GB, JP).

​
Configuration Examples

​
Extended Timeout for Research

For deep research queries that may take longer: 
{
  "mcpServers": {
    "perplexity": {
      "command": "npx",
      "args": ["-y", "@perplexity-ai/mcp-server"],
      "env": {
        "PERPLEXITY_API_KEY": "your_key_here",
        "PERPLEXITY_TIMEOUT_MS": "600000"
      }
    }
  }
}

​
Debug Logging

Enable detailed logging for troubleshooting: 
{
  "mcpServers": {
    "perplexity": {
      "command": "npx",
      "args": ["-y", "@perplexity-ai/mcp-server"],
      "env": {
        "PERPLEXITY_API_KEY": "your_key_here",
        "PERPLEXITY_LOG_LEVEL": "DEBUG"
      }
    }
  }
}
Log levels: DEBUG, INFO, WARN, ERROR (default)

​
Corporate Proxy

For use behind a corporate firewall: 
{
  "mcpServers": {
    "perplexity": {
      "command": "npx",
      "args": ["-y", "@perplexity-ai/mcp-server"],
      "env": {
        "PERPLEXITY_API_KEY": "your_key_here",
        "PERPLEXITY_PROXY": "https://proxy.company.com:8080"
      }
    }
  }
}

​
Next Steps

Now that you’re up and running, explore more:

Tools Reference

Detailed documentation for all tools and parameters

Advanced Configuration

HTTP server deployment, Docker, and more

Deployment Options

Docker, HTTP server, and cloud deployment

Troubleshooting

Common issues and solutions

​
Getting Help

Need assistance?