Perplexity Web MCP Bridge

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, claude_opus55) 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, gpt6_sol, grok45, grok47, claude_sonnet, claude_opus, claude_opus55, gemini_pro, gemini38, nemotron, glm52, glm53, kimi_k26, kimi_k3
• Max-only models: gpt56_sol, claude_opus, claude_opus55. Do not use these for Pro subscriptions.
• The catalog is server-driven: pwm models prints the live list (free, no query quota) and every identifier it shows works with -m.
• 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")
|
+-- Chat interactively in the terminal (one thread per session)
|   +-- CLI:  pwm chat                              # sonar default; /model switches, /new resets, /exit quits
|
+-- 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 [--totp-code CODE]
|   +-- MCP (no shell):   pplx_auth_request_code(email), then pplx_auth_complete(email, code[, totp_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 inherits the authenticated Perplexity account's permissions and may expose private data to the calling agent.
• Set PWM_CONNECTORS_ENABLED=0 to disable connector queries, or use PWM_CONNECTOR_ALLOWLIST with exact comma-separated connector IDs.
• When local connector policy is unset, reported connectors remain available for backward compatibility.
• 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

Read long prompts from stdin or a file, and attach files:

pwm ask - < question.txt              # prompt from stdin
pwm ask --prompt-file question.txt    # prompt from a UTF-8 file
pwm ask "Summarize the key risks" --file report.pdf   # attachment (repeatable)

Attachments are validated before the query is sent; on Free accounts an attachment may count as a Pro Search.

Interactive Chat

Keep one Perplexity thread across turns in the terminal:

pwm chat                              # defaults to Sonar 2 (free-tier friendly)
pwm chat -m auto                      # quota-aware routing per message
pwm chat -m claude_sonnet --thinking  # pin a model for the session

In-session commands: /new starts a new thread, /model [NAME] shows or switches the model (auto = quota-aware routing), /exit (or /quit, or Ctrl-D) quits. The thread continues across model switches.

Saved Defaults

Store a preferred model, thinking mode, and source once:

pwm config set --model grok47 --thinking --source web
pwm config show
pwm config clear                # or clear one key: pwm config clear model

Defaults apply to pwm ask, pwm chat, and MCP pplx_query whenever the matching option is omitted; explicit flags always win (--no-thinking overrides a saved thinking default).

Shared MCP daemon

Use the shared daemon when multiple MCP clients or Codex sessions should connect to one local MCP process:

pwm serve-mcp --transport streamable-http  # HTTP MCP on 127.0.0.1:8000/mcp
pwm serve-mcp --status                # Check the daemon
pwm serve-mcp --stop                  # Stop the daemon
pwm setup add codex --http            # Configure Codex for Streamable HTTP
pwm serve-mcp --transport sse         # Start the legacy SSE transport

The HTTP transports bind to loopback by default. Keep the daemon on a loopback address unless you put an authenticated reverse proxy in front of it.