Skip to main content

Overview

The Perplexity MCP Server enables AI assistants to access Perplexity’s powerful search and reasoning capabilities directly within their workflows. Using the Model Context Protocol (MCP), you can integrate real-time web search, conversational AI, and advanced reasoning into any MCP-compatible client. There are two ways to connect:
  • Remote MCP server (recommended): hosted by Perplexity at https://api.perplexity.ai/mcp. No installation, nothing to update, works with any client that supports remote MCP servers. Sign in with your Perplexity account or use an API key.
  • Local MCP server: run the open-source server on your machine over stdio. Use this if your client only supports stdio servers or you need to pin a version.
The hosted and local options are intended to expose the same Perplexity tools, but transport, authentication, release timing, and client behavior can differ.
The Model Context Protocol (MCP) is an open standard that connects AI assistants with external data sources and tools. Learn more at modelcontextprotocol.io.
This page is for adding Perplexity as an MCP tool inside clients such as Google Antigravity, Claude Code, Codex, Cursor, VS Code, and Claude Desktop. To call the Perplexity API from application code, start with the Quickstart. To select Claude models through the Agent API, use Anthropic model IDs from Agent API models.

Remote MCP Server

Connect to https://api.perplexity.ai/mcp over Streamable HTTP. There are two ways to authenticate:
  • Sign in with Perplexity (OAuth): add the server without credentials and start sign-in from your client. In your browser, sign in to Perplexity, choose the API organization to bill, and approve the connection. See the client tabs below for where to start sign-in.
  • API key: send your key as a bearer token. Use this for clients that do not support OAuth, or for server-side setups such as the Anthropic API MCP connector.

Generate API Key

Navigate to the API Portal and generate a new key.
Run /mcp inside Claude Code and follow the sign-in prompt for perplexity. To use an API key instead, add --header "Authorization: Bearer YOUR_API_KEY" to the command.
Tool calls are billed at standard API pricing to the API key you connect with, or to the organization you chose when signing in. Your organization’s rate limits apply.
After connecting an interactive MCP client, verify your connection with a test prompt. If you’re using the Anthropic API, follow the verification instructions in its tab.

Signing in with Perplexity

Signing in uses your regular Perplexity account. During sign-in you choose which API organization the connection bills to.
  • API usage only. The connection can call the Perplexity API on behalf of that organization. It cannot create API keys, view balances, or manage the organization.
  • Needs an API organization. You must be an admin of an API organization that can pay for usage. If you do not have one, the sign-in page links you to create one in the console. Then restart the connection from your client.

Local MCP Server

Run the same server locally over stdio. The remote and local instructions are alternatives. If you switch setups, replace the existing perplexity registration rather than adding a second entry with the same name.

Prerequisites

Install Node.js 18.17 or later (active LTS recommended). Make sure node and npx are on your MCP client’s PATH:
Generate a Perplexity API key before configuring the local server.

Generate API Key

Navigate to the API Portal and generate a new key.

One-Click Install

Install in Cursor

Add the local MCP server in Cursor, then set PERPLEXITY_API_KEY in your global Cursor config before starting it.
After clicking Install in Cursor, open ~/.cursor/mcp.json on macOS or Linux, or %USERPROFILE%\.cursor\mcp.json on Windows. Replace the empty PERPLEXITY_API_KEY value with your API key. Enable or restart the server in Cursor’s MCP settings. Do not store a literal key in a shared workspace .cursor/mcp.json file. For VS Code Copilot, open the VS Code tab under Manual Setup. Do not use .vscode/mcp.json input prompts.

Agent Plugin Install

The open-source repository includes an Agent Plugins 1.0 declaration for the local stdio server. If your client supports Agent Plugins, install it from perplexityai/modelcontextprotocol, then set PERPLEXITY_API_KEY in the environment that starts the plugin. The plugin does not include credentials, and installation steps vary by client.

Manual Setup

1

Configure Your Client

Add the MCP server to your client configuration:
The remote server is the recommended Claude Code setup. Use one of these options only when you need to run the local stdio server.Every local option requires PERPLEXITY_API_KEY in the environment that launches Claude Code.On macOS or Linux:
On Windows (PowerShell):
Option 1: CLI CommandAdd the server to Claude Code’s private configuration for the current project. Single quotes preserve the environment variable reference instead of saving the key value in the configuration:
Option 2: Claude Code PluginAdd the repository as a Claude Code marketplace, install the fully qualified plugin, then start Claude Code from the same environment:
Option 3: Manual ConfigurationAdd this configuration to .mcp.json in your project root. Claude Code expands PERPLEXITY_API_KEY from its launch environment:
When you first start Claude Code in the project, approve the .mcp.json server when prompted. If PERPLEXITY_API_KEY is not set, claude mcp list reports it as missing and tool calls cannot authenticate.
Do not replace the environment variable reference with your actual API key or commit a key to source control.
2

Start Using

Restart your MCP client and verify your connection.

Verify Your Connection

Restart or reload your MCP client if required, then send this prompt:
Inspect the tool call and confirm that your client invokes perplexity_search rather than built-in web search.

Troubleshooting

If no perplexity_search call appears:
  • Confirm perplexity is connected and enabled in your client’s MCP settings. Complete OAuth sign-in if prompted.
  • For local setups, confirm Node.js 18.17 or later and npx are on the client’s PATH.
  • If the local server logs Error: PERPLEXITY_API_KEY environment variable is required and exits with code 1, set a non-empty key in the config or launch shell, then restart the client.

Available Tools

perplexity_search

Direct web search using the Perplexity Search API. Returns ranked search results with titles, URLs, snippets, and metadata. Set search_type: "fast" to use Fast Search for lower latency and cost. Omit it to keep standard web search. Requires local server version 1.3.0 or later; the hosted server already supports it.Best for: Finding current information, news, facts, or specific web content.

perplexity_ask

General-purpose conversational AI with real-time web search. Uses the Agent API’s fast configuration.Best for: Quick questions, everyday searches, and conversational queries that benefit from web context.

perplexity_research

Deep, comprehensive research. Uses the Agent API’s high configuration. Provides thorough analysis with citations.Best for: Complex topics requiring detailed investigation, comprehensive reports, and in-depth analysis.

perplexity_reason

Advanced reasoning and problem-solving. Uses the Agent API’s medium configuration.Best for: Logical problems, complex analysis, decision-making, and tasks requiring step-by-step reasoning.
For detailed setup instructions, troubleshooting, and proxy configuration, visit our GitHub repository.