Perplexity MCP Server: Research Inside Your Agent

The Perplexity MCP server is Perplexity’s official way to give an AI agent web-grounded answers. It offers four tools: perplexity_search returns ranked web results, perplexity_ask answers a quick question, perplexity_research runs a slow, deep investigation, and perplexity_reason works through an analytical question step by step. The last three come back with numbered citations. Perplexity hosts the server at https://api.perplexity.ai/mcp, where you sign in with your Perplexity account or send an API key, and it also publishes the same server as an npm package you can run locally. Every call is billed to your Perplexity API organization, and every answer is built from web pages you did not write, so both deserve a moment of thought before you connect it.

The four tools

The Perplexity MCP documentation↗ (opens in a new tab) describes the tools, and the server code backs them with Perplexity’s Search API and its Agent API:

• perplexity_search: a direct web search. It returns titles, URLs, snippets and dates with no written answer. You can set a result count, a country, a recency window (hour to year), a list of domains to include or exclude, and a fast search type for routine lookups.
• perplexity_ask: a short answer with web context, backed by the Agent API’s fast preset. The tool describes itself as the fastest and cheapest of the three answer tools.
• perplexity_reason: step-by-step analysis with web grounding, backed by the medium preset. Good for comparisons and questions that chain several facts.
• perplexity_research: deep, multi-source research backed by the high preset. Runs can take minutes, and the server streams progress to clients that ask for it.

The presets are managed by Perplexity. Its presets guide↗ (opens in a new tab) says a preset called by name always resolves to the latest recommended configuration, so the model behind perplexity_ask can change without a new server release. Earlier versions of the server called the Sonar models by name, such as sonar-pro and sonar-deep-research; the project’s README says those parameters are gone from the tool schemas, and Perplexity’s documentation now files Sonar under legacy.

All four tools carry the MCP annotations readOnlyHint and openWorldHint: they read the live web and change nothing. That is useful to a client deciding what to approve automatically, and it is also a reminder that “read-only” describes what the tool does to the world, not what the world can do to your agent through its results.

Signing in or using an API key

The hosted server accepts two kinds of credentials:

• Sign in with Perplexity. Add the server with no credentials, and on first use your client opens a browser. You sign in, choose the API organization to bill and approve the connection. The connection can call the API for that organization, but it cannot create keys, view balances or manage the organization. You must be an admin of an API organization that can pay for usage.
• An API key, sent as Authorization: Bearer in a header. Use it for clients without OAuth support and for server-side setups. Create the key in the Perplexity API console.

Prefer the sign-in where a person is at the keyboard: the client holds a token it can refresh, and you have no long-lived key sitting in a config file. How that browser flow works is in how MCP sign-in works. For an unattended job, give it its own key so you can revoke that one without breaking anything else.

Setup in Claude Code

Perplexity recommends the hosted server for Claude Code. Add it over HTTP, then open /mcp inside Claude Code and follow the sign-in prompt. The flags follow Claude Code’s MCP documentation↗ (opens in a new tab).

# hosted, with browser sign-in (then run /mcp inside Claude Code)
claude mcp add --transport http perplexity https://api.perplexity.ai/mcp

# hosted, with an API key instead
claude mcp add --transport http perplexity https://api.perplexity.ai/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

# local over stdio; single quotes keep the key out of the saved config
claude mcp add perplexity --env 'PERPLEXITY_API_KEY=${PERPLEXITY_API_KEY}' \
  -- npx -y @perplexity-ai/mcp-server

The local form needs PERPLEXITY_API_KEY set in the shell that starts Claude Code. Perplexity also packages the server as a Claude Code plugin from its own marketplace. If the server will not connect, Claude Code MCP not working walks through the checks.

Setup in Cursor

Add the hosted server to ~/.cursor/mcp.json, then open Cursor Settings, go to Tools & MCP and choose Connect next to perplexity to sign in. For an API key instead, Perplexity’s one-click Cursor install adds the header for you.

{
  "mcpServers": {
    "perplexity": {
      "url": "https://api.perplexity.ai/mcp"
    }
  }
}

Setup in Claude Desktop

Claude on the web and in the desktop app can use the hosted server as a custom connector: add a connector with the URL https://api.perplexity.ai/mcp and sign in when asked. If you would rather run it locally, put the npm package in claude_desktop_config.json and restart the app.

{
  "mcpServers": {
    "perplexity": {
      "command": "npx",
      "args": ["-y", "@perplexity-ai/mcp-server"],
      "env": { "PERPLEXITY_API_KEY": "your_key_here" }
    }
  }
}

That file holds the key in plain text on your disk, so keep it out of backups you share and anything you commit. Behind a corporate proxy, the server’s repository↗ (opens in a new tab) documents a PERPLEXITY_PROXY variable, and a PERPLEXITY_TIMEOUT_MS setting for long research runs.

Citations: what comes back

The answer tools return prose with numbered references in the text and a Citations block at the end, one line per source in the form [1] https://.... perplexity_search returns the results themselves: title, URL, snippet and date. That difference decides which tool to ask for:

• When you need to check a claim yourself, use perplexity_search and read the pages. The agent sees the evidence, not a summary of it.
• When you need a quick answer and will spot-check it, perplexity_ask is enough. Ask the agent to keep the citation numbers next to each claim it passes on.
• When you need a report, use perplexity_research, then open the sources behind any number, date or quotation you plan to reuse. A citation shows where a claim came from, not that the page says exactly that.

Narrow the sources when it matters. The domain filter on search, ask and reason takes a list such as ["sec.gov", "ftc.gov"] to stay on primary sources, or ["-example.com"] to drop one.

Cost awareness, in words

Tool calls are billed at Perplexity’s standard API rates to the key you connect with, or to the organization you chose at sign-in, and your organization’s rate limits apply. A few habits keep the bill predictable:

• Default to search or ask. Research is the slowest tool and the one to reach for deliberately, not on every question.
• Tell the agent when to stop. “Use at most three searches, then answer” keeps a curious agent from looping.
• Use a separate key, or a separate organization, for automated jobs, so you can see what each one spends and switch it off on its own.
• Watch context as well as money. Long research reports land in the model’s context in full; MCP token usage explains why that matters.

Prompt injection from web results

Every answer is assembled from pages anyone can publish, and a page can carry text written for a model rather than a reader. With a synthesized answer the risk is quieter than with a raw scrape: an instruction on a page can shape the summary your agent receives, and the agent may treat that summary as trusted. The general mechanics are in indirect prompt injection; for this server, three rules cover most of it:

• Do not give the same session Perplexity and tools that send, publish, deploy or write to production unless each of those calls needs your approval.
• Treat a result as a quotation. Ask for claims with their sources, and act only on what you have checked.
• Use the domain filter for anything that feeds a decision, so the answer comes from sources you chose.

From research to tasks

Research is only useful once someone acts on it. With fenbs connected as a second MCP server at https://fenbs.ai/api/mcp, the agent can turn findings into tasks: a library deprecation becomes an enhancement with the source link in the note, a security advisory becomes a bug with a priority from 1 to 10. Each task has a plan and a test status, and History records who changed what. If a person decides which sources count, such as “primary sources only for anything legal”, record it as a rule on the Decisions and rules page, which every connected assistant reads before it starts. One difference to know: Perplexity marks its tools read-only with annotations, while fenbs sets no tool annotations yet, so your client applies its own defaults to fenbs’s tools.