Perplexity Web MCP
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Search the web with Perplexity AI. QUOTA IS LIMITED — read these rules.
COST MODEL (critical):
pplx_sonar / pplx_smart_query(intent='quick'): Sonar 2 (in-house). Still uses your Perplexity session; limits depend on your plan — call pplx_usage() first.
pplx_ask / pplx_query / all model-specific tools: 1 PRO SEARCH each (weekly pool)
pplx_deep_research: 1 DEEP RESEARCH each (small monthly pool, ~5-10 total)
pplx_list_threads / pplx_get_thread: FREE — read-only, zero quota cost
MANDATORY PROTOCOL:
On your FIRST query of the session, call pplx_usage() to check remaining quotas. Read the Subscription line: Pro users must avoid Max-only models.
DEFAULT to pplx_smart_query(intent='quick') for most lookups — it prefers Sonar 2 before premium models when that fits the question.
Only use 'standard' or 'detailed' intent when the question requires synthesis, comparison, multi-step reasoning, or very current data that Sonar 2 can't handle.
Reserve pplx_deep_research for user-requested deep dives only — NEVER use it autonomously without asking the user first. For complex research that might timeout, use pplx_deep_research_start and poll with pplx_research_status instead.
Avoid model-specific tools (pplx_gpt61_sol, pplx_claude_sonnet, etc.) unless the user explicitly requests a specific model. Each call costs 1 Pro Search query.
WHEN TO USE EACH INTENT:
quick: Facts, definitions, 'what is X', current date/weather, simple lookups
standard: How-to questions, comparisons, explanations needing web sources
detailed: Complex analysis, multi-source synthesis, technical deep-dives
research: Comprehensive reports (only when user explicitly asks for research)
THREAD LIBRARY (quota-free):
Use pplx_list_threads() to browse past conversations — zero quota cost. Search with search_term="keyword" before spending a Pro query on something already researched.
Use pplx_get_thread(slug) to load the full history of any past thread.
To resume a past conversation: call pplx_get_thread(slug) to load context, then pass conversation_id=slug to any query tool to continue right where it left off.
All query tools support source_focus: none, web, academic, social, finance, all, or an account connector source ID from pplx_connectors(). Use source_focus='none' for model-only queries without web search.
AUTHENTICATION: If you get a 403 error or 'token expired' message:
pplx_auth_status — check current authentication status
pplx_auth_request_code — send verification code to email
pplx_auth_complete — complete email OTP and any requested TOTP challenge
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tasks | {
"list": {},
"cancel": {},
"requests": {
"tools": {
"call": {}
},
"prompts": {
"get": {}
},
"resources": {
"read": {}
}
}
} |
| tools | {
"listChanged": true
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
| experimental | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| pplx_queryA | Query Perplexity AI with explicit model selection. COSTS 1 PRO SEARCH QUERY per call. Prefer pplx_smart_query for automatic quota-aware routing. Use this only when
you need a specific model or thinking mode. Omitted model, thinking, and
source_focus fall back to saved defaults (set with Args: query: The question to ask model: Model to use - auto, sonar, deep_research, gpt61_sol, gpt6_astra, gemini4_carbon, gemini4_hydrogen, gemini_pro, claude_sonnet, claude_opus, claude_opus55, claude_fable52, grok47, nemotron, glm53, kimi_k3 (any live catalog identifier is also accepted). An unknown name returns an error with close-match suggestions. thinking: Enable extended thinking mode (available for gpt61_sol, gpt6_astra, gemini4_carbon, gemini4_hydrogen, claude_sonnet, claude_opus, claude_opus55, claude_fable52, grok47; always on for glm53 and kimi_k3) source_focus: Source type - none (model only, no search), web, academic, social, finance, all, or connector source ID from pplx_connectors() files: Local file paths to attach (PDF or image). On Free-tier accounts an attachment can make the query count as a Pro Search. |
| pplx_askA | Quick Q&A with auto model. COSTS 1 PRO SEARCH QUERY. Prefer pplx_smart_query(intent='quick') for simple lookups (Sonar 2 first). An omitted source_focus falls back to your saved default (set with |
| pplx_deep_researchB | Deep Research — in-depth reports. COSTS 1 DEEP RESEARCH QUERY (limited monthly pool, typically 5-10 total). Only use when the user explicitly requests deep research. |
| pplx_deep_research_startA | Start a deep research task asynchronously. COSTS 1 DEEP RESEARCH QUERY. Use this instead of pplx_deep_research for complex queries to avoid connection timeouts. Returns a task_id immediately. Poll pplx_research_status with the task_id to get the result. |
| pplx_research_statusA | Check the status of an asynchronous deep research task. Returns 'in_progress' if the task is still running, the final research report if completed, or an error message if it failed. |
| pplx_sonarC | Sonar 2 — Perplexity's latest in-house model. Subject to your plan and Perplexity usage counters (see pplx_usage). |
| pplx_gpt61_solD | GPT-6.1 Sol — OpenAI's versatile model. COSTS 1 PRO SEARCH QUERY. |
| pplx_gpt61_sol_thinkingC | GPT-6.1 Sol Thinking — OpenAI's versatile model with thinking. COSTS 1 PRO SEARCH QUERY. |
| pplx_gpt6_astraC | GPT-6 Astra — OpenAI's most capable model. COSTS 1 PRO SEARCH QUERY. Requires Max subscription. |
| pplx_gpt6_astra_thinkingC | GPT-6 Astra Thinking — OpenAI's most capable model with thinking. COSTS 1 PRO SEARCH QUERY. Requires Max subscription. |
| pplx_gemini4_carbonC | Gemini 4 Carbon — Google's most powerful model. COSTS 1 PRO SEARCH QUERY. Requires Max subscription. |
| pplx_gemini4_carbon_thinkingC | Gemini 4 Carbon Thinking — Google's most powerful model with thinking. COSTS 1 PRO SEARCH QUERY. Requires Max subscription. |
| pplx_gemini4_hydrogenC | Gemini 4 Hydrogen — Google's latest model. COSTS 1 PRO SEARCH QUERY. |
| pplx_gemini4_hydrogen_thinkingD | Gemini 4 Hydrogen Thinking — Google's latest model with thinking. COSTS 1 PRO SEARCH QUERY. |
| pplx_claude_sonnetC | Claude Sonnet 5.5 — Anthropic's fast model. COSTS 1 PRO SEARCH QUERY. |
| pplx_claude_sonnet_thinkD | Claude Sonnet 5.5 Thinking — Anthropic's newest reasoning model. COSTS 1 PRO SEARCH QUERY. |
| pplx_claude_opusC | Claude Opus 5.5 — Anthropic's latest model. COSTS 1 PRO SEARCH QUERY. Requires Max subscription. |
| pplx_claude_opus_thinkC | Claude Opus 5.5 Thinking — Anthropic's latest model with extended thinking. COSTS 1 PRO SEARCH QUERY. Requires Max subscription. |
| pplx_claude_fable52C | Claude Fable 5.2 — Anthropic's most capable model. COSTS 1 PRO SEARCH QUERY. Requires Max subscription. |
| pplx_claude_fable52_thinkC | Claude Fable 5.2 Thinking — Anthropic's most capable model with extended thinking. COSTS 1 PRO SEARCH QUERY. Requires Max subscription. |
| pplx_grok47C | Grok 4.7 — xAI's most advanced model. COSTS 1 PRO SEARCH QUERY. |
| pplx_grok47_thinkingC | Grok 4.7 Thinking — xAI's most advanced model with thinking. COSTS 1 PRO SEARCH QUERY. |
| pplx_nemotronC | Nemotron 3.5 Super VL — NVIDIA's newest Nemotron model. COSTS 1 PRO SEARCH QUERY. |
| pplx_glm53C | GLM 5.3 — Z.ai's newest model with thinking always enabled. COSTS 1 PRO SEARCH QUERY. |
| pplx_kimi_k3C | Kimi K3 — Moonshot's newest model with thinking always enabled. COSTS 1 PRO SEARCH QUERY. |
| pplx_smart_queryA | RECOMMENDED DEFAULT TOOL. Quota-aware query — checks limits and picks the best model automatically. USE THIS FOR EVERY QUERY unless the user explicitly requests a specific model. Default to intent='quick' for most lookups — it routes to Sonar 2 when appropriate. Only escalate intent when the question genuinely requires it. Intent guide (choose the LOWEST sufficient level):
Response includes a metadata block showing the model used, routing reason, and current quota snapshot. Args:
query: The question to ask
intent: Query complexity — quick (default for most), standard, detailed, research
source_focus: Source type — none (model only, no search), web, academic,
social, finance, all, or connector source ID from pplx_connectors().
Omit it to use your saved default (set with |
| pplx_councilA | Model Council — query multiple models in parallel, get synthesized consensus. IMPORTANT — BEFORE calling this tool, you MUST:
Default council: GPT-6.1 Sol, Claude Sonnet 5.5, Gemini 4 Hydrogen (Pro-compatible, 3 diverse providers). Args: query: The question to ask all council models source_focus: Source type for all models (none/web/academic/social/finance/all or connector source ID) models: Comma-separated model names to use as council members. Available: sonar, gpt61_sol, gpt6_astra, gemini4_carbon, gemini4_hydrogen, gemini_pro, claude_sonnet, claude_opus, claude_opus55, claude_fable52, grok47, nemotron, glm53, kimi_k3. Default: "gpt61_sol,claude_sonnet,gemini4_hydrogen" (3 models + synthesis = 4 Pro Searches) Max-only: gpt6_astra, gemini4_carbon, claude_opus, claude_opus55, claude_fable52. Exclude these when pplx_usage shows a Pro subscription. synthesize: Whether to synthesize a consensus from all responses. Set false to get only individual responses (saves 1 Sonar 2 call). thinking: Enable extended thinking for council models (gpt61_sol, gpt6_astra, gemini4_carbon, gemini4_hydrogen, claude_sonnet, claude_opus, claude_opus55, claude_fable52, and grok47 support toggle; glm53 and kimi_k3 are always thinking). chairman: Model to use for synthesis (default: "sonar" / Sonar 2). Non-sonar chairmen cost 1 extra Pro Search query. |
| pplx_list_threadsA | Browse your Perplexity thread library. FREE — zero quota cost. Returns a paginated list of your past Perplexity conversations with their slugs, titles, models used, and answer previews. PRIMARY USE CASES:
Args: limit: Max threads to return (default 20, max 100). offset: Skip this many threads — use for pagination (e.g. offset=20 for page 2). search_term: Optional keyword to filter threads by title or content. |
| pplx_get_threadA | Fetch the full conversation history for a Perplexity thread. FREE — zero quota cost. Returns the complete Q&A turns, sources, and related queries for any past thread. Get the slug from pplx_list_threads, or from the [Conversation ID: ...] footer returned by any pplx_* query tool. RESUME PATTERN — to continue a past conversation:
Args: slug: Thread UUID / slug. Obtain from pplx_list_threads or a previous [Conversation ID: ...] response footer. |
| pplx_usageA | Check current Perplexity usage limits and remaining quotas. CALL THIS AT THE START OF EVERY SESSION before making any queries. Shows remaining Pro Search (weekly), Deep Research (monthly), and other quotas. Use the results to decide whether to conserve Pro quota (e.g. quick intent before premium models). Args: refresh: Force refresh from Perplexity (ignores cache). Default False. |
| pplx_connectorsA | List account connector source IDs that can be passed as source_focus. Returns source IDs from the Perplexity rate-limit API. Use these IDs as source_focus values, for example source_focus="pitchbook_mcp_cashmere". |
| pplx_auth_statusA | Check if Perplexity is authenticated. Returns the current authentication status and subscription tier if authenticated. Use this to check if re-authentication is needed before making queries. |
| pplx_auth_request_codeA | Request a verification code for Perplexity authentication. Sends a 6-digit verification code to the provided email address. After calling this, check the email inbox and use pplx_auth_complete with the code to finish authentication. Args: email: Your Perplexity account email address Returns: Status message indicating if the code was sent successfully |
| pplx_auth_completeA | Complete Perplexity authentication with the verification code. Use the 6-digit code received via email after calling pplx_auth_request_code. On success, the session token is saved and all pplx_* tools will work. Args: email: Your Perplexity account email (same as used in pplx_auth_request_code) code: The 6-digit verification code from your email totp_code: The 6-digit authenticator code when TOTP is enabled Returns: Status message with authentication result and subscription tier |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| library_resource | Your Perplexity thread library — most recent 50 threads. Returns a formatted list of your recent Perplexity conversations. Use perplexity://thread/{slug} to access a specific thread's full history. |
TDQS
Scored across 34 tools
Four general query tools (pplx_query, pplx_ask, pplx_smart_query, pplx_sonar) overlap heavily, and the 19 per-model wrappers (plus their _thinking/_think variants) duplicate exactly what pplx_query's model argument already does. Descriptions do nudge toward pplx_smart_query as the default, which mitigates but does not resolve the misselection risk.
All tools share the pplx_ prefix and snake_case, which is readable, but the thinking suffix is inconsistent: pplx_gpt61_sol_thinking vs pplx_claude_sonnet_think / pplx_claude_opus_think / pplx_grok47_thinking. The naming also bakes model names into tool names, which is inherently unstable.
34 tools is well beyond what this domain needs; roughly 19 of them are thin per-model wrappers that could be a single parameterized tool. The genuinely distinct capabilities (query, deep research, threads, auth, usage) number about a dozen.
Coverage is strong: querying, async deep research with status polling, thread browsing/resumption, connector discovery, usage inspection, and a full auth flow. Minor gaps like thread deletion/renaming or a non-synthesis council-only path exist but are workable.