Overview

This page introduces the @perplexity-ai/mcp-server package: what it is, what tools it exposes, and how to get started. For deeper coverage of architecture and internals, see System Architecture. For individual tool references, see Tools Reference. For configuration details, see Configuration.

---

What It Is

@perplexity-ai/mcp-server is the official Model Context Protocol (MCP) server for the Perplexity API Platform. It acts as a bridge between MCP-compatible AI clients (such as Claude Desktop, Cursor, VS Code, and Codex) and Perplexity's Sonar models and Search API.

The server exposes four MCP tools that give AI assistants access to real-time web search, conversational search, chain-of-thought reasoning, and deep research. Clients communicate with the server over either stdio (for local process-based integrations) or HTTP (for shared or cloud deployments).

Sources: README.md1-10 package.json1-8

---

The Four Tools

Each tool maps to a specific Perplexity model or API endpoint. The table below summarizes them:

Tool	Backing Model / Endpoint	Best For
perplexity_search	Perplexity Search API (/search)	Ranked web results with metadata (title, URL, snippet, date)
perplexity_ask	sonar-pro (/chat/completions)	Quick conversational questions with live web grounding
perplexity_reason	sonar-reasoning-pro (/chat/completions)	Complex analytical tasks requiring chain-of-thought
perplexity_research	sonar-deep-research (/chat/completions, SSE)	Thorough multi-step research reports (30+ seconds)

Sources: README.md11-28

Tool-to-model mapping:

Sources: README.md11-28

---

System Topology

The server sits between MCP clients and the Perplexity API. Both deployment modes share a single server core (createPerplexityServer() in src/server.ts):

Sources: README.md40-107 package.json26-30 server.json1-17

---

Prerequisites

Node.js ≥ 18 is required (see package.json69-71).

A Perplexity API key is required:

1. Obtain a key from the Perplexity API Portal.
2. Set it as the PERPLEXITY_API_KEY environment variable before starting the server.

The server will refuse to start if PERPLEXITY_API_KEY is not set. This check occurs in src/index.ts before any transport is initialized.

Sources: README.md32-38

---

Quick Start

The fastest way to connect the server to a compatible client is via npx:

For clients that parse stdout strictly (and may break on npx install messages), use the -yq flag:

For clients that use a JSON config file (Cursor, Claude Desktop, Windsurf), add the following block:

For VS Code, the wrapper key is servers instead of mcpServers, and a "type": "stdio" field is required. See Client Integration for client-specific snippets.

Sources: README.md40-107

---

Key Configuration Variables

Variable	Required	Default	Purpose
PERPLEXITY_API_KEY	Yes	—	Bearer token for Perplexity API authentication
PERPLEXITY_BASE_URL	No	https://api.perplexity.ai	Override the API base URL
PERPLEXITY_TIMEOUT_MS	No	300000 (5 min)	Request timeout in milliseconds
PERPLEXITY_LOG_LEVEL	No	ERROR	Log verbosity: DEBUG, INFO, WARN, ERROR
PERPLEXITY_PROXY	No	—	HTTPS proxy URL (highest priority)
PORT	No	8080	HTTP server port (HTTP mode only)
ALLOWED_ORIGINS	No	*	CORS allowed origins (HTTP mode only)

For the complete reference, see Environment Variables Reference.

Sources: README.md144-153

---

Deployment Modes

Mode	Entry Point	Transport Class	Typical Use
stdio	src/index.ts	StdioServerTransport	Local AI client integrations
HTTP	src/http.ts	StreamableHTTPServerTransport	Cloud or shared deployments

Both modes call createPerplexityServer() from src/server.ts and differ only in how the MCP transport layer is initialized. See Dual Deployment Architecture for details.

Sources: package.json37-50 server.json8-16

---

Package Identity

Field	Value
npm package name	@perplexity-ai/mcp-server
MCP registry name	ai.perplexity/mcp-server
Binary (bin)	perplexity-mcp → dist/index.js
License	MIT
Minimum Node.js	≥ 18

Sources: package.json1-30 server.json3-5