"Perplexity MCP" means one of two things. Perplexity runs its own MCP (Model Context Protocol) server, so Claude, Cursor or Codex can search the web through Perplexity. And Perplexity can use other MCP servers as connectors, so it can act in your apps. This guide covers both, from Perplexity's MCP documentation, the server's README and its help center, checked October 26, 2026.
The short version: to use Perplexity from another agent, connect its hosted server at https://api.perplexity.ai/mcp and sign in with your Perplexity account or send an API key; tool calls are billed to your Perplexity API organization. Run it locally with npx -y @perplexity-ai/mcp-server and PERPLEXITY_API_KEY only when your client cannot use remote servers. To give Perplexity new tools, open Plugins, choose Add custom › Connector › Add MCP connector, pick Remote and paste an HTTPS server URL.
What does Perplexity's official MCP server do?
It gives another agent four tools. Each one now runs on a preset of Perplexity's Agent API, which Perplexity keeps tuned, rather than on a model you choose:
| Tool | What it returns | Runs on |
|---|---|---|
perplexity_search |
Ranked web results with titles, URLs, snippets and dates; filters for recency and domains, and a faster, cheaper search type | Search API |
perplexity_ask |
A conversational answer with live web search | Agent API, fast preset |
perplexity_reason |
Step-by-step reasoning on a problem | Agent API, medium preset |
perplexity_research |
Deep research with citations; a run can take minutes | Agent API, high preset |
Older versions of the server called the sonar-pro, sonar-reasoning-pro and sonar-deep-research models and took reasoning_effort and strip_thinking. Those parameters are now ignored, so a guide that tells you to pick a Sonar model in the MCP config describes the old server. perplexity_ask and perplexity_reason accept max_tokens (search context up to 120,000 tokens) and max_tokens_per_page (up to 20,000), which limit how much web content is read, not how long the answer is.
How do I add the Perplexity MCP server to Claude Code, Cursor or Codex?
The hosted server needs no install. In Claude Code:
claude mcp add --transport http perplexity https://api.perplexity.ai/mcp
Then run /mcp inside Claude Code and follow the sign-in prompt. To use an API key instead, add --header "Authorization: Bearer YOUR_API_KEY" to the command. In Cursor, add it to ~/.cursor/mcp.json, then open Cursor Settings › Tools & MCP and click Connect next to it:
{
"mcpServers": {
"perplexity": { "url": "https://api.perplexity.ai/mcp" }
}
}
Codex runs the local server: codex mcp add perplexity --env PERPLEXITY_API_KEY="your_key_here" -- npx -y @perplexity-ai/mcp-server. Where every client keeps its settings:
| Client | How to connect |
|---|---|
| Claude Code |
claude mcp add --transport http, then /mcp to sign in |
| Cursor |
~/.cursor/mcp.json, then Connect in Tools & MCP |
| Claude Desktop |
claude_desktop_config.json (local server, below) |
| claude.ai | a custom connector with the hosted URL |
| Windsurf | ~/.codeium/windsurf/mcp_config.json |
| Google Antigravity |
~/.gemini/config/mcp_config.json with serverUrl and an API key header |
| Anthropic API | the MCP connector with your Perplexity key as authorization_token
|
Our guides to Claude Code MCP, Cursor MCP, Codex MCP and Antigravity and Gemini CLI cover scopes, sign-in and timeouts for each.
How do I run the Perplexity MCP server locally, in Claude Desktop or Docker?
Get an API key from the API Portal (console.perplexity.ai). Claude Desktop, Windsurf and most other clients take the same mcpServers block, which starts the server with Node's npx:
{
"mcpServers": {
"perplexity": {
"command": "npx",
"args": ["-y", "@perplexity-ai/mcp-server"],
"env": { "PERPLEXITY_API_KEY": "your_key_here" }
}
}
}
In a shared Claude Code project, keep the key out of .mcp.json by writing "PERPLEXITY_API_KEY": "${PERPLEXITY_API_KEY}" and exporting the variable before you start claude; claude mcp list reports the server as missing its key if you forget. For a shared or cloud setup, the server also runs over HTTP: build the image from the repository with docker build -t perplexity-mcp-server ., then docker run -p 8080:8080 -e PERPLEXITY_API_KEY=your_key_here perplexity-mcp-server, and point clients at http://localhost:8080/mcp. It listens only on the machine itself until you set BIND_ADDRESS=0.0.0.0 and ALLOWED_HOSTS.
How much does the Perplexity MCP server cost?
The server is free; each tool call is billed at Perplexity's standard API prices, to the API key you connect or to the organization you choose when signing in, and that organization's rate limits apply. Signing in needs a Perplexity account that is an admin of an API organization able to pay for usage. The sign-in can call the API for that organization but cannot create keys, read balances or manage it.
Why is the Perplexity MCP server not working?
-
Research calls time out.
perplexity_researchcan run for minutes. The local server waits five minutes by default; raise it withPERPLEXITY_TIMEOUT_MS=600000, and check your client's own tool timeout too. -
Calls fail at work. Behind a company proxy, set
PERPLEXITY_PROXY=https://your-proxy-host:8080; the server also readsHTTPS_PROXYandHTTP_PROXY, in that order. - Sign-in stops at choosing an organization. Your account is not an admin of an API organization; the sign-in page links to the console to create one, then restart the connection from your client.
-
You need more detail. Set
PERPLEXITY_LOG_LEVEL=DEBUGon the local server.
How do I add an MCP connector to Perplexity?
For a remote server, which runs on the internet:
- Open Plugins in the sidebar (or Customize › Connectors if Plugins is not there yet).
- Choose Add custom › Connector › Add MCP connector and select Remote.
- Enter a name and the MCP server URL, which must start with
https://. - Optionally set the authentication (OAuth, API key or none) and the transport (Streamable HTTP or SSE).
- Tick the box acknowledging the risks of custom connectors, click Add, then click the connector's card to sign in and turn it on.
The three-dot menu on the card edits or removes it later. Perplexity does not verify third-party servers, so add only ones you trust.
Can Perplexity use local MCP servers?
Only in the Mac app from the Mac App Store. Install the helper app PerplexityXPC from Plugins, then choose Add custom, give the server a name and the command that starts it, and save. When its status shows Running, turn it on under Sources on the Perplexity home page. Perplexity notes that local servers are not reviewed by Perplexity or Apple, so read an open-source server's code before you install it.
Can my whole team use a connector?
On Enterprise, members can add their own custom connectors only after an admin turns on Allow members to add custom connectors under Enterprise settings › Connectors; it is off by default. Only admins can share a connector with the organization, from the Permissions screen, and for OAuth connectors an admin can sign in once for everyone or let each member sign in.
A worked example: posting from Perplexity
Skryvo is a remote MCP server for social media, so it shows the connector flow. Add a remote connector named Skryvo with the URL https://api.skryvo.ai/mcp and OAuth, then sign in. Ask Perplexity to research a topic and "turn the three main points into a LinkedIn post for Tuesday at 9am": it drafts the post in your brand's voice, and Skryvo schedules it only after you approve. The Perplexity setup page has the details, and the agents page lists every other agent the same server works in.
Use Perplexity's server where you want sourced answers inside your coding agent, and Perplexity's connectors where you want its research to end in an action.
Originally published at skryvo.ai.
Top comments (0)