Skip to main content
Glama
Aakashanil67

perplexity-deep-mcp

by Aakashanil67
OverviewSchemaRelated ServersScoreDiscussions
JavaScript
Remote

perplexity-deep-mcp

An MCP server that makes Perplexity's Sonar Deep Research usable from MCP clients that enforce a request timeout.

No dependencies. One file. Runs on node server.js.

The problem

Perplexity's sonar-deep-research model runs for two to twenty minutes depending on reasoning effort. MCP clients don't wait that long. Claude Desktop cancels the tool call and returns:

MCP error -32001: Request timed out

The official Perplexity MCP server calls the synchronous /chat/completions endpoint, so deep research is effectively unavailable from inside the client. Raising the timeout doesn't help. The limit lives in the client's bundled MCP SDK, which on a packaged install sits inside a signed application bundle you can't edit. Config keys like timeout and MCP_SERVER_REQUEST_TIMEOUT are ignored.

Perplexity solved this on their side with an async API. This server exposes it.

Related MCP server: MCP Perplexity Pro

How it works

The job is split across three requests that each return in under a second:

pplx_deep_research_start   POST /v1/async/sonar        submit, get a job id back
pplx_deep_research_check   GET  /v1/async/sonar/{id}   poll status, fetch result
pplx_deep_research_list    GET  /v1/async/sonar        recover ids, see what's running

Nothing blocks. Research length stops being a constraint. Results stay retrievable for seven days, so a job started in one conversation can be collected in another.

check takes an optional wait_seconds (max 40). The server holds and polls internally, which cuts the number of round trips without going near the client's limit.

Install

Node 18 or later. Nothing else.

git clone https://github.com/Aakashanil67/perplexity-deep-mcp.git

Get an API key from the Perplexity API portal.

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "perplexity-deep": {
      "command": "node",
      "args": ["/absolute/path/to/perplexity-deep-mcp/server.js"],
      "env": {
        "PERPLEXITY_API_KEY": "pplx-your-key-here"
      }
    }
  }
}

On Windows, use "C:\\Program Files\\nodejs\\node.exe" as the command if bare node doesn't resolve. Quit the app fully — from the system tray, not just the window — and reopen.

Claude Code

claude mcp add perplexity-deep --env PERPLEXITY_API_KEY="pplx-your-key-here" -- node /absolute/path/to/server.js

Environment

Variable

Required

Default

PERPLEXITY_API_KEY

yes

—

PERPLEXITY_BASE_URL

no

https://api.perplexity.ai

Tools

pplx_deep_research_start

Submits a job and returns immediately.

Parameter

Type

Notes

query

string, required

Longer and more structured prompts produce noticeably better reports here

reasoning_effort

minimal | low | medium | high

Default medium. high runs many more searches and takes considerably longer

search_mode

web | academic | sec

academic for peer-reviewed sources, sec for US company filings

search_recency_filter

hour | day | week | month | year

search_domain_filter

string[]

Max 10. Prefix with - to exclude, e.g. ["-pinterest.com"]

search_after_date_filter

string

MM/DD/YYYY

system_prompt

string

Shapes tone and structure of the report

pplx_deep_research_check

Parameter

Type

Notes

job_id

string, required

From start

wait_seconds

number, 0–40

Hold and poll internally before reporting back

strip_thinking

boolean

Strips <think> blocks. Default true

Returns the full report with sources and cost once the job reaches COMPLETED. While it's running you get the status and elapsed time. A FAILED job surfaces Perplexity's error message.

pplx_deep_research_list

Optional status and limit. Returns a table of recent jobs.

Known limitation

The async endpoint returns citations: [] and search_results: [] even on jobs that ran many searches, and the model omits inline [n] markers. The synchronous endpoint doesn't have this problem. Verified 25 July 2026 against two jobs that ran eight and four search queries respectively; both came back with empty source arrays. Injecting a system prompt instructing the model to write full URLs into the prose was tried and did not work.

The practical effect is that you get a long, well-organised, unattributed report. That is fine for scoping an unfamiliar topic and not fine for anything you intend to cite.

The server handles this rather than hiding it. If the citation arrays are empty it scans the report body for URLs and lists whatever it finds, labelled as recovered rather than cited. If nothing turns up it says so in plain language at the end of the report. formatCompleted() reads the proper fields first, so if Perplexity ships a fix the correct sources appear with no code change.

This is upstream. There are open reports on the Perplexity community forum describing the same behaviour.

Why there are no dependencies

The MCP TypeScript SDK is the normal way to build one of these. It's a good SDK. It also means a build step, a node_modules tree, and a lockfile to keep current, all to wrap a protocol that is JSON-RPC 2.0 over newline-delimited stdio.

For a server with three tools and two endpoints that trade wasn't worth making. server.js implements the protocol directly: initialize echoes the client's requested version, tools/list returns the schemas, tools/call dispatches, and resources/list and prompts/list return empty rather than erroring, which keeps stricter clients happy. Notifications get no reply. Unknown methods return -32601.

Two details worth knowing if you adapt this:

Everything written to stdout has to be a JSON-RPC frame. A stray console.log corrupts the stream and the client drops the connection with no useful error. All logging here goes to stderr.

The process tracks in flight requests and won't exit on stdin close while a call is still awaiting the API. Without that guard a closing client can drop a reply that was about to be written.

Errors

Failures return isError: true with a message aimed at whoever has to fix it, not a stack trace. A 401 says the key was rejected. A 404 on a job lookup mentions the seven-day expiry. A 429 says to wait. Network timeouts distinguish themselves from research timeouts, because the two look identical from the client side and the fix is different.

Development

node --check server.js

Drive it by hand over stdio:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{}}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | PERPLEXITY_API_KEY=your-key node server.js

Or use the official inspector:

npx @modelcontextprotocol/inspector node server.js

Cost

Billed by Perplexity per request. Observed on short test jobs: $0.08 for four search queries, $0.13 for eight. Real research runs at high effort cost substantially more. Each result reports its own cost.

License

MIT. See LICENSE.

Available Tools

3 tools
pplx_deep_research_checkA
Read-onlyIdempotent

Check a deep research job and retrieve the full report once it is finished. Returns immediately with the current status. If the job is still running, call again. Results stay retrievable for 7 days.

ParametersJSON Schema
NameRequiredDescriptionDefault
job_idYesThe id returned by pplx_deep_research_start.
wait_secondsNoOptionally hold for up to 40 seconds before reporting, polling internally. Reduces the number of tool calls needed. Default 0.
strip_thinkingNoRemove <think> reasoning blocks from the report. Default true.

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, openWorld, and non-destructive behavior. The description adds valuable context beyond annotations: it returns immediately with current status, supports polling, and results remain retrievable for 7 days. This enriches understanding without contradicting the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is four short sentences, each carrying distinct information: purpose, immediate return, polling behavior, and 7-day retention. It is front-loaded with the primary action and contains no filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 3 parameters and no output schema, the description covers the main behavioral aspects: what it does, when to call, and how long results persist. It does not detail the exact return format, but 'full report' and 'current status' give reasonable guidance. With sibling context, this is sufficiently complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already provides 100% coverage with descriptions for all three parameters (job_id, wait_seconds, strip_thinking). The tool description itself adds no additional parameter-specific meaning, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: checking a deep research job and retrieving the full report once finished. It uses specific verbs ('check', 'retrieve') and identifies the resource ('deep research job'), distinguishing it from siblings like pplx_deep_research_start (starts jobs) and pplx_deep_research_list (lists jobs).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear usage context: it is for checking a job started via pplx_deep_research_start, and explicitly advises 'If the job is still running, call again.' It also mentions the 7-day retention period. However, it does not explicitly state when not to use it or compare it to list alternatives, so it falls short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

pplx_deep_research_listA
Read-onlyIdempotent

List recent deep research jobs with their ids, models and statuses. Use this to recover a job_id you lost, or to see what is still running.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMax jobs to show, newest first. Default 20.
statusNoOptionally show only jobs with this status.

TDQS

A4.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds that it lists 'recent' jobs, implying a temporal ordering, and that it returns ids, models, and statuses, but it does not disclose additional behavioral traits such as pagination or error conditions. This is consistent with the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences: the first defines the action and output, the second gives practical use cases. It is front-loaded with the verb and resource, with zero filler words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple with two optional parameters, and the schema plus annotations already provide the necessary context. The description explicitly lists the returned fields (ids, models, statuses), which compensates for the lack of an output schema, and the use cases make the tool's purpose clear. This is complete for a list-style tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema coverage is 100%, with descriptions for both 'limit' and 'status', so the baseline is 3. The description does not add any extra explanation of the parameters beyond the schema; it only references the returned 'ids' which are not a parameter. Therefore no additional credit is warranted.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('List') and identifies the resource ('deep research jobs') plus the returned attributes ('ids, models and statuses'). It also distinguishes itself from siblings by explaining the use case of recovering a lost job_id, which differs from starting or checking specific jobs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says 'Use this to recover a job_id you lost, or to see what is still running,' providing clear scenarios for when to invoke this tool. It does not name the sibling alternatives or state when not to use it, so it falls short of full exclusion guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

pplx_deep_research_startA
Read-only

Start a Perplexity Sonar Deep Research job. Returns a job_id immediately (does not wait for the research to finish). Use this for exhaustive multi-source investigation: literature reviews, market and competitor analysis, regulatory landscapes. After calling this, poll pplx_deep_research_check with the returned job_id. Jobs typically take 2-20 minutes. For quick factual lookups this is overkill and expensive - use a normal web search instead.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesThe research question. Be specific and state exactly what you want covered, including any sub-questions, sectors, date ranges, or types of evidence required. Longer, more structured prompts produce far better results here.
search_modeNoCorpus to search. Use "academic" for peer-reviewed literature (best for thesis work), "sec" for US company filings, "web" for everything else. Default web.
system_promptNoOptional system instruction shaping tone, structure, or output format of the final report.
reasoning_effortNoHow much effort the model spends. minimal/low finish faster and cost less; high runs many more searches and takes much longer. Default medium.
search_domain_filterNoRestrict or exclude domains, max 10. Plain domain to allow (e.g. "sars.gov.za"); prefix with "-" to exclude (e.g. "-pinterest.com"). Use this to force high-quality sources and shut out content farms.
search_recency_filterNoOnly use sources published within this window. Omit for no recency limit.
search_after_date_filterNoOnly sources published after this date, format MM/DD/YYYY.

TDQS

A3.9/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotation contradiction: The annotations declare readOnlyHint=true, but the description says 'Start a ... job' and 'Returns a job_id', implying a state-changing operation (creating an async job). This directly contradicts the readOnlyHint. The description does add useful timing info (2-20 minutes) and polling instruction, but the contradiction forces a score of 1 per rules.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences, front-loaded with the core action, then usage context, then follow-up and caveats. Every sentence earns its place with no fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (async job, polling, duration, cost), the description covers all essential operational context: immediate return, polling with job_id, typical duration, and cost/overkill warning. It also distinguishes from normal web search. The contradictory annotation is a separate issue, but the description itself is complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all 7 parameters. The tool description adds no parameter-level guidance beyond the schema. Per the baseline rule, score is 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states 'Start a Perplexity Sonar Deep Research job' with the specific verb 'start' and resource. It distinguishes from sibling tools by noting 'After calling this, poll pplx_deep_research_check with the returned job_id' and implies listing via 'start' vs 'list'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit use cases: 'exhaustive multi-source investigation: literature reviews, market and competitor analysis, regulatory landscapes.' It also tells when NOT to use it: 'For quick factual lookups this is overkill and expensive - use a normal web search instead.' This is clear guidance with alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 3 tool updatesv1.0.0
    • First observedpplx_deep_research_check
    • First observedpplx_deep_research_list
    • First observedpplx_deep_research_start
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.2/5.0
Disambiguation5/5

Each tool has a clearly distinct role: start initiates a job, check polls/retrieves results, and list enumerates existing jobs. There is no overlap or ambiguity between them.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern with the pplx_deep_research_ prefix (start, check, list). The naming is uniform and predictable.

Tool Count5/5

Three tools are perfectly scoped for the deep research job lifecycle: initiate, monitor, and list. Each tool serves a necessary function with no redundancy.

Completeness4/5

The core workflow (start, check, list) is fully covered. A minor gap is the lack of a cancel/delete operation for long-running jobs, but this is not essential for the primary use case.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • MCP Perplexity Pro

    cfdude
    A
    license
    Not graded
    quality
    D
    maintenance
    A comprehensive MCP server that provides intelligent access to Perplexity AI's search and reasoning models with automatic model selection, conversation management, and project-aware storage. Supports real-time search, deep research, chat sessions, and async operations for complex queries.
    29
    3
    MIT

  • Perplexity Ask OpenRouter

    elct9620
    A
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that connects to OpenRouter's API to provide Perplexity's models (Sonar, Sonar Deep Research, Sonar Reasoning) for use with any MCP-compatible client.
    8
    MIT

  • perplexity-mcp-server

    cyanheads
    A
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that enables AI agents to perform search-augmented queries and deep multi-source research using the Perplexity API.
    75
    25
    Apache 2.0

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Aakashanil67/perplexity-deep-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server