Skip to content

Perplexity MCP: set up the server, tools and costs

Set up Perplexity MCP in Claude Code, Cursor, Codex or VS Code.

The words "Perplexity MCP" in large black type above a screenshot of Perplexity's API docs page for the Perplexity API MCP Server.

How a coding agent uses Perplexity MCP

The agent calls a Perplexity tool, Perplexity searches the web, and cited results come back into the session.

  1. Coding agent
  2. MCP client
  3. api.perplexity.ai/mcp
  4. Search or Agent API
  5. Cited results

Better Design

Direct answer

Perplexity MCP is Perplexity's official MCP server. It gives Claude Code, Cursor, Codex, VS Code and other MCP clients four tools: perplexity_search, perplexity_ask, perplexity_research and perplexity_reason. Connect to the hosted server at api.perplexity.ai/mcp, or run the open-source npm package locally. Tool calls bill to a Perplexity API account.

In short

What it is
Perplexity's own MCP server, maintained in the perplexityai/modelcontextprotocol repository under the MIT license.
Easiest setup
The remote server at https://api.perplexity.ai/mcp over Streamable HTTP, with nothing to install.
Local option
npx -y @perplexity-ai/mcp-server, version 1.3.0 on npm (25 September 2026), with Node.js 18.17 or later.
Sign-in
Your Perplexity account through OAuth, or an API key sent as a bearer token.
Tools
Search, ask, research and reason.
Cost
Each tool call bills at Perplexity API prices. A standard search is $0.005, or $0.001 with Fast Search.
Not the same thing
The Perplexity Computer MCP server, and adding your own MCP servers to the Perplexity app.

What is Perplexity MCP?

Perplexity MCP means the Perplexity API MCP Server, a Model Context Protocol server. It lets an AI assistant use Perplexity's web search and research from inside its own session. Your coding agent keeps its model, and calls Perplexity when it needs current facts with sources.

It helps when the model's training data is out of date: a new library version, a changed API, or today's pricing. The agent gets ranked results with URLs and dates instead of guessing.

The words cover three different things. This guide explains each one.

  • The Perplexity API MCP Server puts Perplexity inside Claude Code, Cursor or Codex. Most of this page is about it.
  • The Perplexity Computer MCP Server: hands whole tasks to Perplexity Computer, billed in account credits.
  • MCP connectors in Perplexity: your own MCP servers used inside the Perplexity app.

Read Perplexity's overview of its MCP server.

Remote or local: which Perplexity MCP setup should you use?

Use the remote server unless your client only supports stdio. Perplexity recommends it because Perplexity hosts and updates it, and it supports sign-in without copying a key. The local server runs the same tools on your machine.

Remote
URL https://api.perplexity.ai/mcp, Streamable HTTP, OAuth 2.1 with PKCE or an API key. Nothing to update.
Local
npx -y @perplexity-ai/mcp-server over stdio, API key only. Use it to pin a version or when the client has no remote support.
Self-hosted HTTP
Build the repository and run npm run start:http, or the Dockerfile. It listens on http://localhost:8080/mcp.

The two are alternatives. If you switch, replace the existing perplexity entry rather than adding a second server with the same name.

Do you need a Perplexity API key?

Not for the remote server. You can sign in with your Perplexity account instead. During sign-in you pick the API organization that pays, and you must be an admin of an API organization that can pay for usage. If you have none, the sign-in page links you to create one.

The sign-in grants API usage only. It cannot create keys, view balances or manage the organization. The docs say the local server needs a key, set as PERPLEXITY_API_KEY. Create one in the API portal at console.perplexity.ai.

Create an API key in the Perplexity API portal.

How do you add Perplexity MCP to Claude Code?

The Perplexity MCP setup in Claude Code takes one command and a sign-in.

  1. Run claude mcp add --transport http perplexity https://api.perplexity.ai/mcp in your terminal.
  2. Start Claude Code and run /mcp.
  3. Pick perplexity and follow the sign-in prompt in your browser.
  4. Ask: Use perplexity_search to find the latest Node.js LTS release. Return two source links.

To use an API key instead of sign-in, add --header "Authorization: Bearer YOUR_API_KEY" to the first command. For the local server, export PERPLEXITY_API_KEY first. Then run claude mcp add perplexity --env 'PERPLEXITY_API_KEY=${PERPLEXITY_API_KEY}' -- npx -y @perplexity-ai/mcp-server. The single quotes keep the key out of the saved configuration.

Perplexity also ships a Claude Code plugin for the local server: claude plugin marketplace add perplexityai/modelcontextprotocol, then claude plugin install perplexity@perplexity-mcp-server.

How do you set up Perplexity MCP in Cursor, Codex and VS Code?

Cursor

Add a perplexity entry with "url": "https://api.perplexity.ai/mcp" under mcpServers in ~/.cursor/mcp.json, or %USERPROFILE%\.cursor\mcp.json on Windows. Then open Cursor's MCP settings and connect perplexity to sign in. The Install in Cursor button on the GitHub README adds the remote server with an API key header instead.

Codex

Run codex mcp add perplexity --url https://api.perplexity.ai/mcp and follow the browser sign-in. If it does not start, run codex mcp login perplexity. For a key, export PERPLEXITY_API_KEY and add --bearer-token-env-var PERPLEXITY_API_KEY to the add command.

VS Code

Choose the Copilot harness in a chat, run Chat: Open Customizations, then MCP Servers and Add Server. Enter https://api.perplexity.ai/mcp and pick Global > Copilot Global. The config lands in ~/.copilot/mcp-config.json. Authorize in the browser when asked.

Claude Desktop and claude.ai

Open Customize > Connectors, select + Add, then Add custom connector. Name it Perplexity, enter https://api.perplexity.ai/mcp, set Authentication to Sign in now and select Add. On Team or Enterprise plans, an admin adds it first under Organization settings > Connectors.

Google Antigravity and others

Antigravity reads ~/.gemini/config/mcp_config.json and connects with serverUrl plus an Authorization: Bearer header. Any other client that supports remote MCP over Streamable HTTP can use the same URL. Perplexity's docs warn against putting a literal key in a workspace file that you might commit.

See every client's setup in Perplexity's MCP docs.

How do you run the Perplexity MCP server locally?

  1. Install Node.js 18.17 or later and check that node and npx are on your client's PATH.
  2. Create an API key in the Perplexity API portal.
  3. Add a server that runs npx with the arguments -y and @perplexity-ai/mcp-server.
  4. Pass PERPLEXITY_API_KEY in the server's env block, or read it from your shell.
  5. Restart the client and run the test prompt.

The README lists these optional environment variables for the local configuration:

PERPLEXITY_TIMEOUT_MS
Request timeout. The default is 5 minutes; raise it for long research.
PERPLEXITY_BASE_URL
A custom API base URL. The default is https://api.perplexity.ai.
PERPLEXITY_LOG_LEVEL
DEBUG, INFO, WARN or ERROR. The default is ERROR.
PERPLEXITY_PROXY
A proxy URL for company networks, checked before HTTPS_PROXY and HTTP_PROXY.
PORT, ALLOWED_ORIGINS and ALLOWED_HOSTS
For the self-hosted HTTP mode only.

Read the full option list in the GitHub README.

What tools does Perplexity MCP give your agent?

Four tools. The three answer tools run on Perplexity's Agent API presets, which Perplexity tunes over time.

perplexity_search
Ranked web results with titles, URLs, snippets and dates from the Search API. It takes a recency filter, a domain filter, and search_type: "fast" for lower latency and cost.
perplexity_ask
A quick answer with web search, on the Agent API fast preset.
perplexity_reason
Multi-step reasoning across sources, on the medium preset.
perplexity_research
Deep research with citations, on the high preset. Runs can take minutes.

In npm version 1.3.0, ask and reason take search_context_size: low, medium or high. The GitHub README already documents max_tokens, up to 120,000, and max_tokens_per_page, up to 20,000, but 1.3.0 does not pass them on. These budgets cap the search content fed to the model, not the answer length. Older versions called the legacy Sonar models; 1.3.0 uses the Agent API, and Fast Search needs 1.3.0 or later locally.

Read the tool notes in the GitHub README.

How much does Perplexity MCP cost?

The server itself is free and open source. Each tool call bills at standard Perplexity API prices to the key or organization you connected, and your organization's rate limits apply. These are the list prices on Perplexity's pricing page, read on 20 November 2026:

perplexity_search
$5 per 1,000 requests, or $0.005 each. With Fast Search: $1 per 1,000, or $0.001.
perplexity_ask, perplexity_reason and perplexity_research
Agent API tokens at the preset model's rates, plus tool fees.
Agent API web search tool
$0.0025 a call, or $0.001 with Fast Search. fetch_url is $0.0005 a call.

Search is the cheapest tool and enough for most coding lookups. Research runs many steps, so it costs the most. Check your usage in the API portal after the first week.

Check current rates on Perplexity's API pricing page.

How do you verify the Perplexity MCP connection?

Send the test prompt from Perplexity's docs: Use perplexity_search to find the latest Node.js LTS release. Return two source links. Then look at the tool call. It should name perplexity_search, not the client's built-in web search.

No tool call
Check that perplexity is connected and enabled in the MCP settings, and finish sign-in.
Local server exits with PERPLEXITY_API_KEY environment variable is required
Set a non-empty key and restart the client.
spawn npx fails
Node.js is missing from the PATH the client uses.
Timeouts on research
Raise PERPLEXITY_TIMEOUT_MS.
Blocked at work
Set PERPLEXITY_PROXY and make sure api.perplexity.ai is reachable.

What is the Perplexity Computer MCP server?

It is a second, separate server. Instead of search tools, it hands whole tasks to Perplexity Computer. That agent browses, runs code in a sandbox, writes files and uses connectors such as GitHub, Linear and Slack.

URL
https://www.perplexity.ai/rest/computer/mcp.
Claude Code
Claude mcp add perplexity-computer --transport http https://www.perplexity.ai/rest/computer/mcp.
Sign-in
OAuth with your Perplexity account; no API key.
Billing
Perplexity account credits, not the API. A low balance returns insufficient_credits.
Long tasks
A call waits up to two minutes, then returns timeout while the task keeps running. Use read_thread with the thread_id to check it.

Read Perplexity's Computer MCP docs.

Can you add a Perplexity MCP connector for your own servers?

Yes, remote ones. Perplexity calls them custom connectors, and each one is an MCP connector inside the Perplexity app. The Mac app does not support your own local, command-based MCP servers.

  1. Open Plugins in the sidebar.
  2. Select Add custom, then Add MCP connector.
  3. Enter a name and the server's https:// URL.
  4. Under Advanced, pick Authentication (OAuth, API Key or None), Transport (Streamable HTTP or SSE) and Network access.
  5. Tick the risk acknowledgement and select Add, then select the connector card to sign in.

In an Enterprise organization, admins add connectors under Organization settings > Connectors, and members can add their own only when an admin allows it. The form has no field for custom headers, so the server cannot require one.

Read the Help Center guide to custom remote connectors.

Should you use a community Perplexity MCP server?

Usually not. Directories list several, such as DaInfernalCoder/perplexity-mcp and jsonallen/perplexity-mcp, and some still name Sonar models in their tools. The official server is maintained by Perplexity, has a hosted version, and follows API changes. Pick a community server only for a feature the official one lacks, and read its code first, since it holds your key.

How does Perplexity MCP help with front-end work?

It keeps an agent's facts current. Before it writes code, ask it to check browser support for a CSS feature or read a UI library's latest release notes. It finds and cites sources; it does not design screens or judge layouts.

For that second part, Better Design gives the same agent a design system and review rules over MCP, next to Perplexity.

Add Better Design to your agent

Frequently asked questions