perplexity-web-mcp

Perplexity Web MCP

Search the web and query premium AI models through Perplexity AI.

Quick Reference

Run pwm --ai for comprehensive AI-optimized documentation covering all commands, models, MCP tools, auth flows, and error recovery.

pwm --ai                # Full AI reference (RECOMMENDED first step)
pwm --help              # CLI help
pwm login --check       # Check auth status

Critical Rules

1. Authenticate first: Run pwm login before any queries
2. Tokens last ~30 days: Re-run pwm login on 403 errors
3. Check quota before your first query every session (see protocol below)
4. Default to quick/Sonar 2 — only escalate when the query genuinely needs Pro
5. Never use Deep Research autonomously — only when the user explicitly asks

Quota-Aware Usage Protocol (MANDATORY)

Perplexity has hard quota limits. Wasting Pro queries on simple lookups exhausts the weekly pool fast, leaving nothing for questions that actually need it.

Cost Model

Before Every Session

1. Check quota first: Call pplx_usage() (MCP) or pwm usage (CLI) before your first query.
2. Review the remaining Pro and Research counts and the Subscription line.
3. If Subscription is Pro, exclude Max-only models (gpt56_sol, claude_opus) from model selection and councils.
4. If Pro < 20% remaining, restrict yourself to quick/Sonar 2 for everything except user-requested Pro queries.

Before Every Query: Choose the Lowest Sufficient Tier

Ask yourself: "Can Sonar 2 answer this?" If yes, use quick. Only escalate if the answer is no.

Use quick (Sonar 2 — 1 Pro Search, cheapest option) when the query is:

• A factual lookup: "What is the capital of France?"
• A definition: "What does CORS stand for?"
• A simple current-event check: "Who won the Super Bowl?"
• A quick status/version check: "What is the latest version of React?"
• A straightforward how-to that's well-documented: "How do I create a venv in Python?"
• A single-fact retrieval: "What is the population of Tokyo?"
• A simple translation or conversion: "How many meters in a mile?"

Use standard (1 Pro Search) when the query:

• Needs synthesis across multiple web sources: "Compare Next.js and Remix for SSR"
• Requires very current data from multiple sources: "What happened in AI this week?"
• Asks for a how-to with nuance: "Best practices for PostgreSQL indexing in 2026"
• Needs cited sources for credibility: "What are the side effects of metformin?"
• Involves a real comparison or tradeoff analysis

Use detailed (1 Pro Search, premium model) when the query:

• Requires complex multi-step reasoning: "Analyze the pros/cons of microservices vs monolith for a 10-person startup"
• Demands deep technical analysis: "Explain the differences between Raft and Paxos consensus algorithms"
• Needs authoritative synthesis with reasoning: "What are the economic implications of the new EU AI Act?"

Use research (1 Deep Research — scarce) ONLY when:

• The user explicitly asks for "deep research", "comprehensive report", or similar
• Never use autonomously — always ask the user first
• Falls back to premium Pro Search if research quota is exhausted

Use council (N+1 Pro Searches — expensive) when:

• The user needs high-confidence answers validated across multiple AI providers
• Important decisions, fact-checking, or complex analysis
• BEFORE calling: ASK the user which models and how many (each = 1 Pro Search)
• Available models: sonar, gpt56_terra, gpt56_sol, grok45, claude_sonnet, claude_opus, gemini_pro, nemotron, glm52, kimi_k26
• Max-only models: gpt56_sol, claude_opus. Do not use these for Pro subscriptions.
• Default: 3 Pro-compatible models (GPT-5.6 Terra, Claude Sonnet, Gemini Pro) + synthesis = 4 Pro Searches

Decision Flowchart

You want to query Perplexity...
│
├─ Is this a simple fact, definition, or well-known how-to?
│  └─ YES → intent='quick' (Sonar 2, 1 Pro Search)
│
├─ Does it need multiple current web sources or cited synthesis?
│  └─ YES → intent='standard' (1 Pro Search)
│
├─ Does it need deep reasoning, complex analysis, or premium model quality?
│  └─ YES → intent='detailed' (1 Pro Search, premium model)
│
├─ Does the user need high-confidence answers from multiple AI providers?
│  └─ YES → pplx_council / pwm council (N+1 Pro Searches — ASK USER which models first!)
│
├─ Did the user explicitly request deep research / comprehensive report?
│  └─ YES → intent='research' (1 Deep Research)
│
└─ When in doubt → intent='quick' (Sonar 2, upgrade later if insufficient)

Smart Routing

The tool includes quota-aware routing. Instead of choosing a model manually, use the smart query interface and let it pick the best option:

MCP:  pplx_smart_query(query, intent="quick")       # default for most lookups
MCP:  pplx_smart_query(query, intent="standard")    # when quick isn't enough
CLI:  pwm ask "query"                                # auto routes via smart logic
CLI:  pwm ask "query" --intent quick                 # explicit intent hint

Automatic Quota Protection

The smart router automatically protects you:

• Healthy quota: Uses the ideal model for your intent
• Low quota (<20% pro remaining): Response footer warns you to conserve
• Critical quota (<10% pro remaining): Downgrades detailed→auto to conserve
• Exhausted quota: Falls back to Sonar 2 for everything except research (Sonar 2 is forced to concise mode to ensure grounded responses using search results)
• Research exhausted: Falls back to premium Pro Search
• Response metadata shows what model was used, why, and remaining quota

When to Use Explicit Models Instead

Only use model-specific tools (pplx_gpt56_terra, pplx_claude_sonnet, etc.) when:

• The user explicitly requests a specific model
• You're comparing outputs across models
• The smart router's choice isn't working for the specific use case

Each explicit model call costs 1 Pro Search query — there is no free tier for these.

Tool Detection

Check which interface is available before proceeding:

has_mcp = check for tools starting with "pplx_"
has_cli = can run "pwm" commands via shell

if has_mcp and has_cli:
    Ask user which they prefer, or use MCP for programmatic access
elif has_mcp:
    Use pplx_* MCP tools directly
else:
    Use pwm CLI via shell

Workflow Decision Tree

User wants to...
|
+-- Search the web / ask a question (RECOMMENDED: smart routing)
|   +-- CLI:  pwm ask "query"                    # smart routing (default)
|   +-- MCP:  pplx_smart_query(query)            # smart routing (default)
|   +-- Explicit model: pwm ask "query" -m gpt56_terra  or  pplx_query(query, model="gpt56_terra")
|
+-- Browse past conversations (FREE, no quota)
|   +-- CLI:  pwm threads                        # list recent threads
|   +-- CLI:  pwm threads --search "topic"       # search threads
|   +-- MCP:  pplx_list_threads()               # list threads
|   +-- MCP:  pplx_list_threads(search_term="X") # search threads
|
+-- Read or resume a past conversation (FREE, no quota)
|   +-- CLI:  pwm threads --search "topic"       # find slug
|   +-- MCP:  pplx_get_thread(slug)             # read full history
|   +-- MCP:  pplx_smart_query(query, conversation_id=slug) # resume
|
+-- Export full library to JSON (FREE, no quota)
|   +-- CLI:  pwm export                        # all threads → pplx-export-<date>.json
|   +-- CLI:  pwm export --search "ai"          # filtered export
|
+-- Query multiple models at once (Model Council)
|   +-- CLI:  pwm council "query"                         # default 3 models
|   +-- CLI:  pwm council "query" -m gpt56_terra,claude_sonnet  # custom models
|   +-- MCP:  pplx_council(query)                         # ASK USER which models first!
|
+-- Deep research on a topic
|   +-- CLI:  pwm research "query"
|   +-- MCP:  pplx_deep_research(query)
|
+-- Use a specific model
|   +-- CLI:  pwm ask "query" -m gpt56_terra --thinking
|   +-- MCP:  pplx_gpt56_terra_thinking(query)  or  pplx_query(query, model="gpt56_terra", thinking=True)
|
+-- Check remaining quotas
|   +-- CLI:  pwm usage
|   +-- MCP:  pplx_usage()
|
+-- Authenticate / re-authenticate
|   +-- Interactive:      pwm login
|   +-- Non-interactive:  pwm login --email EMAIL  then  pwm login --email EMAIL --code CODE
|   +-- MCP (no shell):   pplx_auth_request_code(email)  then  pplx_auth_complete(email, code)
|
+-- Start MCP server
|   +-- pwm-mcp
|
+-- Start API server (for Claude Code / OpenAI SDK)
|   +-- pwm api [--port PORT]

CLI Commands

Querying

pwm ask "What is quantum computing?"

Choose a specific model with -m:

pwm ask "Compare React and Vue" -m gpt56_terra
pwm ask "Explain attention mechanism" -m claude_sonnet

Enable extended thinking with -t:

pwm ask "Prove sqrt(2) is irrational" -m claude_sonnet --thinking

Focus on specific sources with -s:

pwm ask "review this code for bugs" -s none            # Model only, no web search
pwm ask "transformer improvements 2025" -s academic   # Scholarly papers
pwm ask "best mechanical keyboard" -s social           # Reddit/Twitter
pwm ask "Apple revenue Q4 2025" -s finance             # SEC EDGAR filings
pwm ask "latest AI news" -s all                        # All sources
pwm connectors list                                    # List connector source IDs
pwm ask "private company funding" -s pitchbook_mcp_cashmere

Connector source IDs:

• CLI: run pwm connectors list, then pass the source ID with -s.
• MCP: call pplx_connectors(), then pass the source ID as source_focus.
• Do not guess connector IDs. If no connector is listed, use normal source focus values.
• Connector access depends on the authenticated Perplexity account; free accounts may show none.
• Unknown source values fail instead of falling back to web search.

Output options:

pwm ask "What is Rust?" --json            # JSON (for piping)
pwm ask "What is Rust?" --no-citations    # Answer only, no URLs

Combine flags:

pwm ask "protein folding advances" -m gemini_pro -s academic --json

Model Council

Query multiple models in parallel and get a synthesized consensus. Each model in the council costs 1 Pro Search, plus 1 for Sonar 2 synthesis. Default: 3 Pro-compatible models + synthesis = 4 Pro Searches. Before selecting models, check pplx_usage() or pwm usage. If the subscription is Pro, exclude Max-only models (gpt56_sol, claude_opus).

pwm council "What are the best practices for microservices?"           # default 3 models
pwm council "Compare Rust and Go for backend" -m gpt56_terra,claude_sonnet  # custom 2 models
pwm council "Explain quantum computing" -s academic                   # with source focus
pwm council "Prove the Pythagorean theorem" --thinking                # extended thinking
pwm council "AI trends 2026" --chairman claude_sonnet                 # premium synthesis (+1 Pro)
pwm council "Is React or Vue better?" --no-synthesis                  # skip synthesis
pwm council "AI trends 2026" --json                                   # JSON output

Thread Library (FREE — no quota)

Browse and export past Perplexity conversations:

pwm threads                          # list most recent 20 threads
pwm threads --limit 50              # get 50 threads
pwm threads --search "quantum"      # filter threads by keyword
pwm threads --offset 20             # page 2 (skip first 20)
pwm threads --json                  # JSON output (for piping)

Export full library to a JSON file (no browser required):

pwm export                              # all threads → pplx-export-<date>.json
pwm export --output ./my-backup.json   # custom path
pwm export --search "ai"               # filtered export
pwm export --limit 50                  # cap at 50 threads

Deep Research

Uses a separate monthly quota. Produces in-depth reports with extensive sources.

pwm research "agentic AI trends 2026"
pwm research "climate policy impact" -s academic
pwm research "NVIDIA competitive landscape" -s finance --json

Authentication

pwm login                                                # Interactive
pwm login --check                                        # Check status
pwm login --email user@example.com                       # Send code
pwm login --email user@example.com --code 123456         # Complete

Usage

pwm usage                   # Cached limits
pwm usage --refresh         # Force-refresh from server

MCP Tools Summary

All query tools accept source_focus: "none", "web", "academic", "social", "finance", "all", or a connector source ID from pplx_connectors(). Use source_focus="none" for model-only queries without web search.

Multi-Turn Conversations: All query tools accept an optional conversation_id parameter. The server returns [Conversation ID: <uuid>] at the end of each response. Extract this UUID and pass it to the next query to maintain context across multiple turns.

For full MCP tool parameters: See references/mcp-tools.md

Models

For full model details: See references/models.md

Source Focus Options

Error Recovery

Common Patterns

Thread Library & Conversation Resumption

# List recent threads
pwm threads

# Search before spending quota
pwm threads --search "python packaging"

# Export full library to JSON (no browser needed)
pwm export

MCP — quota-free thread browsing:

pplx_list_threads()                        # recent 20 threads
pplx_list_threads(search_term="topic")     # search first
pplx_get_thread("<slug>")                  # read full history

Resume pattern — continue any past conversation:

# 1. Find the thread
pplx_list_threads(search_term="quantum")
# → returns slug: "f1f6562c-91be-47e9-..."

# 2. Read it for context (optional)
pplx_get_thread("f1f6562c-91be-47e9-...")

# 3. Continue right where it left off
pplx_smart_query("follow-up question", conversation_id="f1f6562c-91be-47e9-...")

MCP Resources (if your MCP client supports resources):

perplexity://library                        # your thread library
perplexity://thread/<slug>                  # a specific thread

Quick web search

pwm ask "What happened in AI today?"

Model-only query (no web search)

pwm ask "Explain the visitor pattern in OOP" -s none
pwm ask "Write a Python decorator for retry logic" -m claude_sonnet -s none

Specific model

pwm ask "Compare React and Vue" -m gpt56_terra

Model with thinking

pwm ask "Prove sqrt(2) is irrational" -m claude_sonnet -t

Academic research

pwm ask "transformer improvements 2025" -m gemini_pro -s academic

Financial analysis

pwm ask "Apple revenue Q4 2025" -s finance

Launch Claude Code seamlessly (Integration)

pwm hack claude

Deep research pipeline

pwm research "quantum computing breakthroughs 2026" --json > research.json

Check everything before heavy use

pwm login --check && pwm usage

Re-authenticate (non-interactive, for AI agents)

pwm login --email user@example.com
# wait for email, then:
pwm login --email user@example.com --code 123456

API Server

For API server setup and model name mapping, see references/api-endpoints.md.