Perplexity API MCP Server

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, 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 any credentials. On first use your client opens a browser where you sign in to your Perplexity account, choose the API organization to bill, and approve the connection. Works with any client that supports OAuth for remote MCP servers, including Claude Code, Cursor, VS Code, and claude.ai (add it as a custom connector using the URL above).
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.

Authorization: Bearer YOUR_API_KEY

Generate API Key

Navigate to the API Portal and generate a new key.

claude mcp add --transport http perplexity https://api.perplexity.ai/mcp

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.

Add the server to ~/.cursor/mcp.json, then open Cursor Settings > Tools & MCP and click Connect next to perplexity to sign in:

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

To use an API key instead, install in Cursor with one click and replace YOUR_API_KEY with your key.

Add the server to .vscode/mcp.json. VS Code opens a browser to sign in the first time the server starts:

{
  "servers": {
    "perplexity": {
      "type": "http",
      "url": "https://api.perplexity.ai/mcp"
    }
  }
}

To use an API key instead, install in VS Code with one click and VS Code prompts for your key.

Configure the hosted Perplexity server in your global ~/.gemini/config/mcp_config.json file. Antigravity connects through serverUrl and sends your Perplexity API key as a bearer token:

{
  "mcpServers": {
    "perplexity": {
      "serverUrl": "https://api.perplexity.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_PERPLEXITY_API_KEY"
      }
    }
  }
}

Replace YOUR_PERPLEXITY_API_KEY with the key you generated in the API Portal. If Antigravity is already running, reopen it after saving the file.

Never commit or share API keys. Keep the key in the global configuration file, and do not put a literal key in a workspace .agents/mcp_config.json file because workspace configuration may be committed or shared.

Setup is complete when Antigravity shows perplexity_search, perplexity_ask, perplexity_research, and perplexity_reason. Antigravity runs unconfigured MCP tools in Ask permission mode by default, so it requests your approval before execution.

Google’s documentation currently lists Perplexity Ask in the Antigravity MCP Store. That Store listing has not been independently verified here; the configuration above connects Antigravity specifically to Perplexity’s hosted remote server.

This MCP configuration gives Antigravity’s agent access to Perplexity tools. It does not add Perplexity API calls to the application you are building; for application code, use the API quickstart. See Google’s Antigravity MCP configuration reference for other supported settings.

Use Perplexity’s tools in a Messages API request with the MCP connector:

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-client-2025-11-20" \
  -d '{
    "model": "claude-opus-5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "What happened in AI this week?"}],
    "mcp_servers": [{
      "type": "url",
      "url": "https://api.perplexity.ai/mcp",
      "name": "perplexity",
      "authorization_token": "YOUR_PERPLEXITY_API_KEY"
    }],
    "tools": [{
      "type": "mcp_toolset",
      "mcp_server_name": "perplexity"
    }]
  }'

authorization_token accepts your Perplexity API key directly (no OAuth needed); it is sent to our server as a bearer token. Anthropic bills the Messages request as usual; Perplexity tool calls are billed to your Perplexity API key.To restrict which tools the model can call, disable tools by default and enable the ones you want:

"tools": [{
  "type": "mcp_toolset",
  "mcp_server_name": "perplexity",
  "default_config": {"enabled": false},
  "configs": {
    "perplexity_search": {"enabled": true}
  }
}]

Any client that supports remote MCP servers over Streamable HTTP can connect with:

Setting	Value
URL	`https://api.perplexity.ai/mcp`
Transport	Streamable HTTP
Sign in	OAuth 2.1 with PKCE and dynamic client registration
API key	Header `Authorization: Bearer YOUR_API_KEY`

If your client only supports stdio servers, use the local MCP server below.

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.

One-Click Install

Install in Cursor

Automatically configure the Perplexity MCP server in Cursor with one click.

Install in VS Code

Automatically configure the Perplexity MCP server in VS Code with one click.

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

Get Your API Key

Generate API Key

Navigate to the API Portal and generate a new key.

Configure Your Client

Add the MCP server to your client configuration:

Claude Code
Cursor
Codex
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 PERPLEXITY_API_KEY in the environment that launches Claude Code:

export PERPLEXITY_API_KEY="your_api_key_here"

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:

claude mcp add perplexity --env 'PERPLEXITY_API_KEY=${PERPLEXITY_API_KEY}' -- npx -y @perplexity-ai/mcp-server

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:

claude plugin marketplace add perplexityai/modelcontextprotocol
claude plugin install perplexity@perplexity-mcp-server
claude

Option 3: Manual ConfigurationAdd this configuration to .mcp.json in your project root. Claude Code expands PERPLEXITY_API_KEY from its launch environment:

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

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.

We recommend using the one-click install above for setting up the MCP server in Cursor.If you prefer to configure it manually, add the following to your mcp.json:

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

codex mcp add perplexity --env PERPLEXITY_API_KEY="your_key_here" -- npx -y @perplexity-ai/mcp-server

Most MCP-compatible clients (including Claude Desktop, VS Code, and Windsurf) use the mcpServers format. Configuration file locations:

Client	Config File
Cursor	`~/.cursor/mcp.json`
VS Code	`.vscode/mcp.json`
Claude Desktop	`claude_desktop_config.json`
Windsurf	`~/.codeium/windsurf/mcp_config.json`
Google Antigravity	`~/.gemini/config/mcp_config.json`

Standard mcpServers format:

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

VS Code uses a slightly different format:

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

If your client doesn’t work with these formats, check its documentation for the correct wrapper format.

Start Using

Restart your MCP client and start using Perplexity’s tools in your AI workflows.

Available Tools

perplexity_search

Direct web search using the Perplexity Search API. Returns ranked search results with titles, URLs, snippets, and metadata.Best for: Finding current information, news, facts, or specific web content.

perplexity_ask

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

perplexity_research

Deep, comprehensive research backed by the Agent API high preset. 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 backed by the Agent API medium preset.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.

Getting Started

Router API

Agent API

Search API

Search SDK

Embeddings API

Perplexity SDK

Admin & Management

Resources

Legacy API

Perplexity API MCP Server

Overview

Remote MCP Server

Generate API Key

Signing in with Perplexity

Local MCP Server

One-Click Install

Install in Cursor

Install in VS Code

Agent Plugin Install

Manual Setup

Generate API Key

Available Tools

perplexity_search

perplexity_ask

perplexity_research

perplexity_reason

​Overview

​Remote MCP Server

Generate API Key

​Signing in with Perplexity

​Local MCP Server

​One-Click Install

Install in Cursor

Install in VS Code

​Agent Plugin Install

​Manual Setup

Generate API Key

​Available Tools

perplexity_search

perplexity_ask

perplexity_research

perplexity_reason

Overview

Remote MCP Server

Signing in with Perplexity

Local MCP Server

One-Click Install

Agent Plugin Install

Manual Setup

Available Tools