Remote MCP Server
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.
Local MCP Server
Get Your API Key
- Get your Perplexity API Key from the API Portal
- Replace
your_key_here in the configurations below with your API key
- (Optional) Set timeout:
PERPLEXITY_TIMEOUT_MS=600000 (default: 5 minutes)
- (Optional) Set custom base URL:
PERPLEXITY_BASE_URL=https://your-custom-url.com (default: https://api.perplexity.ai)
- (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
Agent Plugins
This repository is packaged as an Agent Plugin, so clients that support the standard can install it directly from this repository. The Agent Plugins format does not carry secrets, so set the PERPLEXITY_API_KEY environment variable through your client's plugin or MCP settings.
Other MCP Clients
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.
Self-Hosted HTTP Mode
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