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 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 tohttps://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.
- Claude Code
- Codex
- Cursor
- VS Code
- Claude Desktop
- Google Antigravity
- Anthropic API
- Other Clients
/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.
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 existingperplexity registration rather than adding a second entry with the same name.
Prerequisites
Install Node.js 18.17 or later (active LTS recommended). Make surenode and npx are on your MCP client’s PATH:
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.~/.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 fromperplexityai/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:
- Claude Code
- Cursor
- Codex
- VS Code
- Other Clients
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 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 When you first start Claude Code in the project, approve the
PERPLEXITY_API_KEY in the environment that launches Claude Code.On macOS or Linux:.mcp.json in your project root. Claude Code expands PERPLEXITY_API_KEY from its launch environment:.mcp.json server when prompted. If PERPLEXITY_API_KEY is not set, claude mcp list reports it as missing and tool calls cannot authenticate.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:perplexity_search rather than built-in web search.
Troubleshooting
If noperplexity_search call appears:
- Confirm
perplexityis 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
npxare on the client’sPATH. - If the local server logs
Error: PERPLEXITY_API_KEY environment variable is requiredand exits with code1, 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.