Perplexity API Platform MCP Server

     

The official MCP server implementation for the Perplexity API Platform, providing AI assistants with real-time web search, reasoning, and research capabilities through the Agent API and the Search API.

Available Tools

perplexity_search

Direct web search using the Perplexity Search API. Returns ranked search results with metadata, perfect for finding current information. Supports recency filters (search_recency_filter) and domain restrictions (search_domain_filter).

perplexity_ask

General-purpose conversational AI with real-time web search, backed by the Agent API fast preset. Great for quick questions and everyday searches.

perplexity_research

Deep, comprehensive research backed by the Agent API high preset. Ideal for thorough analysis and detailed reports. Runs can take minutes; the server streams the run and reports progress to clients that request it.

perplexity_reason

Advanced reasoning and problem-solving backed by the Agent API medium preset. Perfect for complex analytical tasks.

Note

Presets are managed configurations (model, search setup, step budget) that Perplexity keeps tuned over time; see the presets guide. Earlier versions of this server called the legacy sonar-pro, sonar-reasoning-pro, and sonar-deep-research models and accepted strip_thinking / reasoning_effort parameters. Those parameters are no longer part of the tool schemas and are ignored if sent; the Agent API produces no <think> tags.

Configuration

Get Your API Key

1. Get your Perplexity API Key from the API Portal
2. Replace your_key_here in the configurations below with your API key
3. (Optional) Set timeout: PERPLEXITY_TIMEOUT_MS=600000 (default: 5 minutes)
4. (Optional) Set custom base URL: PERPLEXITY_BASE_URL=https://your-custom-url.com (default: https://api.perplexity.ai)
5. (Optional) Set log level: PERPLEXITY_LOG_LEVEL=DEBUG|INFO|WARN|ERROR (default: ERROR)

Claude Code

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

Or install via plugin:

export PERPLEXITY_API_KEY="your_key_here"
claude
# Then run: /plugin marketplace add perplexityai/modelcontextprotocol
# Then run: /plugin install perplexity

Codex

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

Cursor, Claude Desktop, Kiro, Windsurf, and VS Code

Most clients can be configured manually using the same mcpServers wrapper in their client config (as shown for Cursor). If a client has a different schema, check its docs for the exact wrapper format.

For manual setup, these clients all use the same mcpServers structure:

Client	Config File
Cursor	~/.cursor/mcp.json
Claude Desktop	claude_desktop_config.json
Kiro	.kiro/settings/mcp.json
Windsurf	~/.codeium/windsurf/mcp_config.json
VS Code	.vscode/mcp.json

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

Proxy Setup (For Corporate Networks)

If you are running this server at work—especially behind a company firewall or proxy—you may need to tell the program how to send its internet traffic through your network's proxy. Follow these steps:

1. Get your proxy details

• Ask your IT department for your HTTPS proxy address and port.
• You may also need a username and password.

2. Set the proxy environment variable

The easiest and most reliable way for Perplexity MCP is to use PERPLEXITY_PROXY. For example:

export PERPLEXITY_PROXY=https://your-proxy-host:8080

If your proxy needs a username and password, use:

export PERPLEXITY_PROXY=https://username:password@your-proxy-host:8080

3. Alternate: Standard environment variables

If you'd rather use the standard variables, we support HTTPS_PROXY and HTTP_PROXY.

Note

The server checks proxy settings in this order: PERPLEXITY_PROXY → HTTPS_PROXY → HTTP_PROXY. If none are set, it connects directly to the internet. URLs must include https://. Typical ports are 8080, 3128, and 80.

HTTP Server Deployment

For cloud or shared deployments, run the server in HTTP mode.

Environment Variables

Variable	Description	Default
PERPLEXITY_API_KEY	Your Perplexity API key	Required
PERPLEXITY_BASE_URL	Custom base URL for API requests	https://api.perplexity.ai
PORT	HTTP server port	8080
BIND_ADDRESS	Network interface to bind to. Defaults to loopback. Set to 0.0.0.0 to expose on all interfaces.	127.0.0.1
ALLOWED_ORIGINS	CORS origins (comma-separated). Defaults to empty (no cross-origin browser requests). Set to an explicit allowlist (e.g. https://app.example.com) or to * to allow any origin.	(empty)
ALLOWED_HOSTS	Additional Host header values to accept (comma-separated). Loopback hosts on PORT are always allowed. Add the public hostname when binding to 0.0.0.0.	(loopback only)

Docker

docker build -t perplexity-mcp-server .
docker run -p 8080:8080 -e PERPLEXITY_API_KEY=your_key_here perplexity-mcp-server

Node.js

export PERPLEXITY_API_KEY=your_key_here
npm install && npm run build && npm run start:http

The server will be accessible at http://localhost:8080/mcp

Use as a Library

The package also exports the server factory for embedding in your own Node process:

import { createPerplexityServer } from "@perplexity-ai/mcp-server";

// Single-tenant: reads PERPLEXITY_API_KEY from the environment.
const server = createPerplexityServer("my-service");

// Multi-tenant hosts resolve the key per call instead. When a provider is
// set, the environment variable is never consulted, and a provider that
// returns no key fails the call rather than falling back.
const tenantServer = createPerplexityServer("my-service", {
  apiKey: () => currentRequestApiKey,
});

Mount the returned server on any MCP transport (stdio, streamable HTTP, in-memory).

Troubleshooting

• API Key Issues: Ensure PERPLEXITY_API_KEY is set correctly
• Connection Errors: Check your internet connection and API key validity
• Tool Not Found: Make sure the package is installed and the command path is correct
• Timeout Errors: For very long research queries, set PERPLEXITY_TIMEOUT_MS to a higher value
• Proxy Issues: Verify your PERPLEXITY_PROXY or HTTPS_PROXY setup and ensure api.perplexity.ai isn't blocked by your firewall.
• EOF / Initialize Errors: Some strict MCP clients fail because npx writes installation messages to stdout. Use npx -yq instead of npx -y to suppress this output.

For support, visit community.perplexity.ai or file an issue.

---