Perplexity MCP Server
This server provides Perplexity-powered web search with persistent domain/recency filters and manual model selection.
Run web searches with specific queries and get cited sources with summaries; optionally stream responses.
Allow or block up to 20 domains, with filters persisting across searches until cleared.
Set a persistent recency window (
hour,day,week,month, ornone) for time-sensitive results.Clear domain filters or inspect the current allowed/blocked domains and active recency setting.
View available Perplexity models and override automatic model selection for deep research, reasoning, or general search.
Provides web search capabilities using Perplexity's API with automatic model selection based on query intent, supporting various Perplexity models like sonar, sonar-pro, sonar-reasoning, sonar-reasoning-pro, and sonar-deep-research
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Perplexity MCP Server what are the latest developments in quantum computing?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Perplexity MCP Server
An MCP server that gives Claude (and any other MCP client) access to Perplexity: AI-synthesized web search, raw ranked results, the multi-step Agent API, background research jobs, the Decisions API and embeddings. It exposes 22 tools; 6 of them are deprecated and kept for compatibility.
Sonar end of support. Perplexity's Sonar Chat Completions API reached end of support on 2026-09-27.
searchandasync_research_submitnow run on the Perplexity Agent API by default. See Howsearchworks and Migration and breaking changes.
Contents
Related MCP server: Perplexity MCP Server
Prerequisites
Node.js 20 or newer (
enginesinpackage.json; required by MCP SDK v2)A Perplexity API key from https://www.perplexity.ai/settings/api
An MCP client: Claude Code, Claude Desktop, or any other
Setup
Clone, install and build:
git clone https://github.com/RossH121/perplexity-mcp.git
cd perplexity-mcp
npm install
npm run buildClaude Code
Add it with the CLI (use --scope project to write a shared .mcp.json instead of your user config):
claude mcp add perplexity -e PERPLEXITY_API_KEY=your-api-key -- node /absolute/path/to/perplexity-mcp/build/index.jsOr add it to .mcp.json in your project root. Claude Code expands ${VAR} references, so the key can stay in your shell environment:
{
"mcpServers": {
"perplexity": {
"type": "stdio",
"command": "node",
"args": ["/absolute/path/to/perplexity-mcp/build/index.js"],
"env": {
"PERPLEXITY_API_KEY": "${PERPLEXITY_API_KEY}"
}
}
}
}Tools then appear as mcp__perplexity__search, mcp__perplexity__agent, and so on. If you pin tool names in agent or permission allowlists, see the renamed tools.
Claude Desktop
Add the same entry under mcpServers in ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows), with the key written in directly, then restart Claude Desktop.
Install via MCPB (Claude Desktop, macOS/Windows)
Build the bundle (requires Node.js 20+):
npm install
npm run pack:mcpb # -> dist/mcpb/perplexity-mcp-<version>.mcpbTo install it, double-click the .mcpb file or drag it onto Claude Desktop (Settings > Extensions). Claude Desktop then asks for these settings:
Setting | Env var | Default | Notes |
Perplexity API key (required) |
| none | Stored in the OS keychain |
Default Sonar model |
|
|
|
Search backend |
|
|
|
Debug logging |
| empty | Set to |
Claude Desktop isn't available on Linux. There, use the Claude Code .mcp.json setup, pointing node at build/index.js.
Configuration
Variable | Required | Default | Description |
| yes | Your Perplexity API key. The server exits at startup without it. | |
| no |
| Default Sonar model for |
| no |
| Backend for |
| no | unset | Any non-empty value turns on verbose diagnostics on stderr. stdout carries only MCP JSON-RPC. |
Pricing: https://docs.perplexity.ai/docs/getting-started/pricing
Tools
At a glance
Purpose | Tool | Billed | Notes |
Answer a question |
| yes | One AI-synthesized answer with cited sources. The default choice. |
Find sources |
| yes | Ranked URLs, titles and snippets with no LLM. Up to 5 queries per call. |
Multi-step agent |
| yes | Agent API loop: built-in tools, remote MCP servers, skills, file and image input, third-party models. |
| Poll a background | ||
| Cancel an in-progress run. | ||
| List or download files a run shared. | ||
Background research |
| yes | Start a long research job and get an id back. |
| Poll a job. Returns the report when done. | ||
| Jobs submitted by this server process. | ||
Probabilities |
| yes | Calibrated yes/no, choice and rubric-score probabilities. |
Embeddings |
| yes | Text embeddings. |
| yes | Chunk embeddings that share per-document context. | |
Discovery |
| Model ids usable by | |
| Custom skill ids usable by | ||
Search model state |
| local | Current Sonar model selection for |
| local | Pin a model for later | |
Deprecated |
| yes (submit) | Alias, removed next release. Use |
| local | Alias, removed next release. Use | |
| local | Use the per-call | |
| local | Use the per-call | |
| local | Only clears the deprecated stateful filters. | |
| local | Only lists the deprecated stateful filters. |
"local" tools change or read this server's in-memory state and make no API call. Unbilled tools without "local" read existing results from the API.
Every tool is annotated with MCP read-only, destructive, idempotent and open-world hints, so clients such as Claude Code can run the read-only ones in parallel and retry them safely. Data tools also return structuredContent matching a declared outputSchema, alongside the markdown text: search, raw_search, agent, agent_retrieve, agent_files, async_research_status, async_research_list, get_model_info, list_models, list_filters, list_skills, decisions, embeddings and contextualized_embeddings.
search
Returns one synthesized answer with numbered sources. It uses only the query text, not your conversation, so write a specific query. Keyword routing picks the depth (see How search works).
Parameter | Options | Description |
| string | The question. Required. |
|
| Agent effort level for this call. Bypasses keyword routing and |
| string[], max 20 | Allow only these domains, or exclude them with a |
|
| Time window for this call. Dropped, with a note, if |
|
| Published-date filter |
|
| Last-updated filter |
|
|
|
|
| How much retrieved context the model gets |
|
|
|
|
| Sent as |
| boolean | Adds the |
| string[] | Restrict images (first 10 domains; bmp, gif, jpeg, png, webp, svg) |
| Localize results | |
| ISO 639-1 | Response language |
| boolean | Answer with |
| JSON schema | Structured output |
| number | Sampling and length controls ( |
| boolean | Append a request-cost footer |
| boolean | Remove |
| boolean | Legacy backend only. The result is the same either way. |
| Legacy Sonar backend only. Ignored on the agent backend, with a line under "Backend notes". |
Examples:
"What's the latest Node.js LTS?" routes to
sonar-pro, effortfast."Deep research analysis of CRISPR gene editing advances" routes to
sonar-deep-research, efforthigh.search { query: "...", effort: "medium", search_domain_filter: ["nodejs.org"] }sets the depth and sources directly.
raw_search
Ranked results straight from the Search API, with no LLM. Cheaper and faster than search. Useful for URL discovery, source lists and fact-checking pipelines.
Parameter | Options | Description |
| string or up to 5 strings | Each query counts separately against the rate limit. |
| 1-20, or 1-50 with | Default 10 |
| number | Content budget overall and per result |
|
| Content extracted per page (default |
|
|
|
| string[], max 20 | Allow, or exclude with |
| Time filters | |
|
| Source languages |
| ISO 3166-1 alpha-2 | Localize results |
raw_search has no search_mode: the /search endpoint rejects it. To narrow it to a corpus, use search_domain_filter, for example ["arxiv.org", "pubmed.ncbi.nlm.nih.gov"] or ["sec.gov"].
agent
The Perplexity Agent API: a multi-step loop that can call built-in tools, remote MCP servers and skills, and can run third-party models. With no effort, model or profile, it runs effort low.
Parameter | Options | Description |
| string | The task. Required. May be empty only with |
|
| A configuration bundle (model, tools, steps, search type). Default |
| Deprecated alias of | |
|
| A saved configuration from the API Portal. Request fields override it, except |
| e.g. | A provider-qualified model, or a fallback chain. Call |
| string | System prompt |
|
| Built-in tools |
| object |
|
|
| Whether the model may, must or must not call tools |
| 1-500 | Agentic steps. A direct |
| number | Output cap |
|
| How hard the model reasons. Separate from |
| JSON schema | Structured output |
| string[] |
|
|
| PDF, DOC, DOCX, TXT or RTF input, max 30. Not available to ZDR organizations. |
| object[] | Remote MCP servers (see below) |
|
| Answer approval-gated MCP calls. Needs |
| object[], max 16 |
|
| boolean | Queue the run. Poll with |
| Continue a prior run. | |
| Response language and sampling | |
|
|
|
| string | Override the automatic prompt cache key |
The output header reads [Agent model: X | effort: name@version | service_tier: Y]. Approval requests, MCP activity, images and shared files get their own sections.
Remote MCP servers. Streamable HTTP endpoints only (no SSE):
{
"server_label": "docs",
"server_url": "https://example.com/mcp",
"authorization": "<bearer token>",
"allowed_tools": ["search_docs"],
"require_approval": "always"
}By default every MCP call runs automatically. require_approval takes always, never, or {always?, never?: {tool_names?, read_only?}}. A gated call pauses the run and is listed with an approval_request_id. To continue, call agent again with previous_response_id, approval_responses and the same mcp_servers. A single unreachable server fails the whole run with HTTP 424, so configure only servers you trust and expect to be up.
Skills. Selecting any skill enables the sandbox:
{ "type": "builtin", "name": "office/pdf" }
{ "type": "inline", "name": "house-style", "description": "Our formatting rules.", "instructions": "..." }
{ "type": "custom", "id": "skill_..." }Builtin names are office (all four), office/docx, office/pdf, office/pptx and office/xlsx. Use list_skills to find custom ids.
agent_retrieve, agent_cancel
agent_retrieve { response_id } returns a background run's status, and its full output once it completes. agent_cancel { response_id } stops a run. Cancellation is asynchronous, so poll agent_retrieve to see the final status.
agent_files
Lists (action: "list") or downloads (action: "content", with file_id) the files a run delivered with its share_file tool. The office/* skills do this, and such files also appear under "Shared files" in the agent output. Files the agent merely wrote to disk during code execution are not listed, so ask it to share the file.
agent_files { action: "list", response_id: "resp_..." }
agent_files { action: "content", response_id: "resp_...", file_id: "file_..." }Shared files are also MCP resources at perplexity-agent-file://{response_id}/{file_id}. list returns resource links; content (or resources/read) returns the bytes as an embedded resource, as text for UTF-8 text types and as a base64 blob otherwise. Files over 5 MB are reported, not inlined. resources/list shows the files seen in the current session.
async_research_submit, async_research_status, async_research_list
Long research as a background Agent API run, so the call doesn't block.
Tool | Parameters | Description |
|
| Returns a |
|
| Read-only. Says "not ready yet" until the run completes. Bare-UUID ids from the old async Sonar API are still polled through the legacy endpoint while it answers. |
| Ids submitted by this server process (kept in memory, lost on restart), plus any legacy async jobs. |
The id also works with agent_retrieve and agent_cancel. For full control (tools, models, structured output), use agent with background: true.
decisions
Ask named questions about some content and get calibrated probabilities back instead of prose. No rationale text is returned.
Parameter | Options | Description |
| string / object / array | The content the questions refer to. It may embed OpenAI-style |
| object | Name → |
| string | Default |
|
| One web search per question (max 100 questions). A URL-only |
| integer (seconds) | Max age of the fetched page copy (web grounding with a URL state only) |
Pricing: $0.02 per million input tokens ($0.01 for flash), output free, plus $0.001 per web search or fetch. The output shows an estimated cost, because the API returns token counts but no cost.
decisions({
state: "The headphones sound great, but the battery stopped charging after two weeks.",
questions: {
defect: { type: "noul", instructions: "Does the review report a product defect?" },
sentiment: { type: "choice", criteria: { positive: "Mostly satisfied", mixed: null, negative: "Mostly dissatisfied" } },
severity: { type: "score", instructions: "How severe?", criteria: ["Cosmetic", "Inconvenient", "Unusable"] }
}
})embeddings, contextualized_embeddings
Parameter |
|
|
| string or string[] (max 512) | string[][]: one array of chunks per document (max 512 documents, 16,000 chunks) |
|
|
|
| 128-1024 (0.6b) or 128-2560 (4b) | same |
|
| same |
| Include the raw base64 vectors (default: summary only) | same |
The two model families are not interchangeable. Contextualized embeddings let chunks from the same document share context, which improves RAG retrieval.
list_models, list_skills
list_models { provider? } lists the models available to your account from the live GET /v1/models endpoint, grouped by provider. These are the provider-qualified ids for agent's model / models (e.g. anthropic/claude-sonnet-5-5, openai/gpt-6-sol, perplexity/sonar). It doesn't list the Sonar models search routes between; get_model_info shows those.
list_skills lists your project's uploaded custom skills (limit, page_token), or describes one by skill_id (with an optional revision). Pass the id to agent as skills: [{ type: "custom", id }]. Uploading and deleting skills are not exposed.
get_model_info, set_model
get_model_info shows the current Sonar selection for search, the default model and the routing keywords. set_model { model } pins sonar, sonar-pro, sonar-reasoning-pro or sonar-deep-research for every later search call in this server process, or "auto" restores keyword routing. A query that strongly matches another model's keywords still overrides a pinned model. For a single call, use search's effort instead, which doesn't touch shared state.
Deprecated tools
These still work. Each alias's result ends with a deprecation note.
Tool | Replacement | Status |
|
| Removed next release |
|
| Removed next release |
|
| Deprecated, no removal date |
| Not needed with per-call params | Deprecated, no removal date |
The stateful filters apply to every later search in the server process, including parallel ones. Per-call params override them for that call without changing them.
How search works
search and async_research_submit run on the Perplexity Agent API unless PERPLEXITY_SEARCH_BACKEND=sonar.
Routing. Keywords in the query pick a Sonar model, unless
set_modelpinned one.Effort mapping. That model maps to an Agent effort level, following Perplexity's Sonar migration guide:
Keywords (examples) | Sonar model | Agent effort |
|
|
|
|
|
|
|
|
|
anything else |
|
|
Override. A per-call
effortskips both steps.Request. Filters, location and
search_context_sizego on theweb_searchtool.return_imagesaddsimage_search, andsearch_modebecomes domain filters or tools.
The header line shows what ran, for example [Using model: sonar-pro -> Agent effort fast (ran fast@<version> on <model>) - ...], or [Using effort override: medium (ran ...)]. Parameters with no Agent equivalent are listed under "Backend notes" at the end of the result.
On a live comparison of six queries (2026-11-12), the agent backend gave equivalent answers at the same latency, cost 2-3x less on text queries, and returned images where the legacy backend returned none. Academic mode is only approximated: it returned 10 sources to Sonar's 20.
Rollback. PERPLEXITY_SEARCH_BACKEND=sonar restores the legacy Sonar Chat Completions and async paths for as long as Perplexity still answers them. On that backend effort is ignored, the Sonar-only params work again, and async_research_submit accepts only sonar-deep-research. Legacy Sonar docs: https://docs.perplexity.ai/docs/legacy/sonar/.
Migration and breaking changes
Renamed and deprecated tools
New tools:
async_research_submit,async_research_status,async_research_list,get_model_info,set_model,decisions,list_skills.async_researchandmodel_infoare deprecated aliases, removed in the next release. Their results end with a deprecation note.domain_filter,recency_filter,clear_filtersandlist_filtersare deprecated in favour of per-call params.Clients that pin an exact tool list (for example a
.claude/agents/*.mdallowlist containingmcp__perplexity__model_info) need the new names added.set_modelrequiresmodel; pass"auto"to reset. Undermodel_info, calling with no arguments reset the selection.
search
The header line now names the effort level and the version that ran. On the legacy backend it reads
[Using model: X (legacy Sonar backend) - ...].At effort
lowand above, inline citations look like[web:N]. Sources are still numbered[N].These params have no effect on the default backend and are reported under "Backend notes":
search_language_filter,stream_mode,image_results_enhanced_relevance,return_related_questions,search_type: "auto",stop,enable_search_classifier.return_imagesnow actually returns images, billed at about $0.0025 per image search.disable_searchanswers withperplexity/sonar, and the domain, recency and date filters are ignored.A recency filter (stateful or per-call) combined with
search_after_date/search_before_dateis dropped, with a note.A per-call
search_domain_filterthat mixes allow and-entries, has more than 20 entries or has empty entries is rejected, as is a malformedeffort.
Background research
async_research_submitreturnsresp_...ids, which also work withagent_retrieveandagent_cancel.Status values are lowercase (
queued,in_progress,completed,failed,incomplete,cancelled) instead ofCOMPLETED/FAILED. The 7-day expiry line is gone.listshows only runs submitted since the server process started, plus legacy async jobs.On the agent backend all four Sonar models are accepted and mapped to an effort level.
agent
presetis replaced byeffort, which takes the same level names.presetstill works as an alias, andeffortwins if both are set.wide-researchnow runsxhigh.max_stepsgoes up to 500 (was 100).The output header now includes the effort version and service tier.
raw_search
More than 5 queries, empty strings in a query array, and
max_resultsover 20 (over 50 forpeople) are now rejected client-side. The API rejected them anyway.
Embeddings
Omitting
encoding_formatgivesbase64_int8. There never was a full-precision float output.
Results
Data tools return
structuredContentalongside the text. Clients that validate results againstoutputSchemaget typed data.agent_files contentreturnstext, not a base64blob, for UTF-8 text types.resources/readfor an unknown or malformedperplexity-agent-file://URI, or one the API answers with 400/404, now returns JSON-RPC error-32602(Invalid Params) instead of-32002. The message still startsResource not found:.
Runtime
The server is built on MCP SDK v2 (
@modelcontextprotocol/server). Node.js versions before 20 are no longer supported.Over stdio it serves both protocol eras: the initialize handshake for 2024-10-07, 2024-11-05, 2025-03-26, 2025-06-18 and 2025-11-25 (Claude Code negotiates 2025-11-25), and the stateless 2026-07-28 era, which starts with
server/discover. In 2026-07-28, instructions come back onserver/discover, and resourcelist_changednotifications go out only on asubscriptions/listenstream the client opens.Install and run commands, the
build/index.jsentrypoint, env vars, tool names and result shapes are unchanged.
Development
npm run build # compile TypeScript to build/
npm start # run the built server on stdio
npm test # build, then run the node:test suite (no network)The unit tests use fakes and never call the API. A separate script checks every request parameter against the live API, because the SDK's types are not reliable enough to catch a misnamed field:
PERPLEXITY_API_KEY=... node scripts/validate-params.mjs # cheap checks
PERPLEXITY_API_KEY=... node scripts/validate-params.mjs --include-costly # adds priority tier, sandbox file round-trip, legacy async submitIt prints PASS, FAIL or SKIP per check. Legacy Sonar canaries print OK or LOST, which is informational. The MCP approval round-trip runs against a public server by default; set PROBE_APPROVAL_MCP_URL=skip to skip it.
Packaging:
npm run pack:mcpbbuilds the MCPB bundle intodist/mcpb/(gitignored). The script does a production-only install, runsmcpb validateandmcpb pack, then unpacks the bundle and runs a smoke test.npm run mcpb:manifestregenerates theversionandtoolsfields ofmanifest.jsonfrompackage.jsonand the built server'stools/list(--checkfails if they are stale). Don't hand-edit those two fields.
Source is in src/. After editing, rebuild and restart your MCP client to load the changes.
License
MIT
Available Tools
6 toolsclear_filtersA
Remove all domain filters (both allowed and blocked). Use when switching search contexts or starting fresh. Does not affect recency filter.
Inputs: no named parameters.
domain_filterA
Configure domain filtering for search results. Use 'allow' to prioritize trusted sources (e.g., documentation sites, academic domains) or 'block' to exclude unreliable sources. Maximum 20 domains total. Filters persist across searches until cleared.
Inputs: domain (required), action (required).
list_filtersA
Display current filter configuration including allowed domains, blocked domains, and active recency setting. Useful for debugging search behavior.
Inputs: no named parameters.
model_infoA
View available Perplexity models and their specializations, or manually override model selection. By default, models are auto-selected based on query intent (research, reasoning, general search).
Inputs: model.
recency_filterA
Control the time window for search results. Essential for time-sensitive queries like news, updates, or recent developments. Filter persists until changed.
Inputs: filter (required).
searchA
Web search via Perplexity AI with automatic model selection. Returns cited sources with summaries. The search uses only the query text (not conversation history). Best for: current events, factual research, technical documentation, comparative analysis.
Inputs: query (required), stream.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool has a clearly distinct purpose with no overlap: clear_filters removes filters, domain_filter configures domains, list_filters displays current settings, model_info shows models, recency_filter controls time windows, and search performs web searches. The descriptions reinforce these unique roles, making misselection unlikely.
All tool names follow a consistent verb_noun pattern with snake_case (e.g., clear_filters, domain_filter, list_filters, model_info, recency_filter, search). The naming is predictable and readable throughout, with no deviations or mixed conventions.
With 6 tools, this server is well-scoped for its purpose of configuring and executing Perplexity AI searches. Each tool earns its place by covering essential aspects like filtering, model selection, and search execution, without being overly sparse or bloated.
The tool set provides complete coverage for the domain of Perplexity AI search configuration and execution. It includes setup (filters, model info), control (recency, domain filters), status (list_filters), and core functionality (search), with no obvious gaps that would cause agent failures.
Maintenance
Related MCP Connectors
Hosted Web Crawler MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Web search API and MCP server for developers building AI agents.
Docs: https://docs.keenable.ai/mcp-server Keenable is a free, remote MCP server that gives agents access to the web index. Search the web with ranked results and date/site filters, then fetch any indexed page as clean markdown. Works out of the box with no account or API key.
Related MCP Servers
AlicenseAqualityBmaintenanceAn MCP server that integrates Kagi search capabilities with Claude AI, enabling Claude to perform real-time web searches when answering questions that require up-to-date information.2566MIT- AlicenseAqualityDmaintenanceMCP server that enables Claude to request chat completions with citations from the Perplexity API.1MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that integrates with Sonar API to provide Claude with real-time web search capabilities for comprehensive research.MIT
- AlicenseAqualityDmaintenanceAn MCP server that enables AI assistants to perform web searches on Perplexity.ai using browser automation instead of an official API. It supports persistent authenticated sessions and returns search results along with cited sources directly to the client.346 npm14MIT