modelcontextprotocol

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.

The remote MCP server is hosted by Perplexity and is the easiest way to get started: same tools, nothing to install or update. The Cursor and VS Code buttons at the top of this page connect to it with one click. If your MCP client does not support remote servers yet, skip to the local server setup below. Connect over Streamable HTTP with your Perplexity API key:

https://api.perplexity.ai/mcp

For Claude Code:

claude mcp add --transport http perplexity https://api.perplexity.ai/mcp --header "Authorization: Bearer YOUR_API_KEY"

See the MCP integration docs for manual Cursor/VS Code configuration, usage from the Anthropic API, and setup for other clients.

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 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 mcp add perplexity --env PERPLEXITY_API_KEY="your_key_here" -- npx -y @perplexity-ai/mcp-server

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:

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

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.

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

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

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

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).

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

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.

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

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).

• 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.