Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/perplexityai/modelcontextprotocol/llms.txt

Use this file to discover all available pages before exploring further.

The Perplexity MCP Server supports HTTP mode for cloud deployments, containerized environments, and scenarios where STDIO transport is not suitable.

​
HTTP Mode vs STDIO Mode

HTTP Mode

  • Cloud deployments
  • Docker containers
  • Shared server environments
  • Browser-based MCP clients
  • Remote access

STDIO Mode

  • Local development
  • Desktop MCP clients (Cursor, Claude Desktop)
  • Direct process communication
  • Single-user environments

​
Node.js Deployment

1

Set environment variables

Configure the required environment variables:
export PERPLEXITY_API_KEY=your_key_here
export PORT=8080
export BIND_ADDRESS=0.0.0.0
export ALLOWED_ORIGINS=https://your-app.com
2

Install dependencies

Install the required packages:
npm install
3

Build the project

Compile TypeScript to JavaScript:
npm run build
4

Start the HTTP server

Launch the server:
npm run start:http
The server will be accessible at http://localhost:8080/mcp

​
Environment Variables

VariableDescriptionDefaultRequired
PERPLEXITY_API_KEYYour Perplexity API key-Yes
PORTHTTP server port8080No
BIND_ADDRESSNetwork interface to bind to0.0.0.0No
ALLOWED_ORIGINSCORS allowed origins (comma-separated)*No
PERPLEXITY_TIMEOUT_MSRequest timeout in milliseconds300000No
PERPLEXITY_BASE_URLCustom API base URLhttps://api.perplexity.aiNo
PERPLEXITY_LOG_LEVELLogging level: DEBUG, INFO, WARN, ERRORERRORNo
Setting BIND_ADDRESS to 0.0.0.0 allows the server to accept connections from any network interface. For local-only access, use 127.0.0.1.

​
CORS Configuration

The HTTP server implements CORS middleware to control cross-origin access from browser-based clients.

​
Default Configuration

By default, all origins are allowed (ALLOWED_ORIGINS=*). This is suitable for development but should be restricted in production.

​
Production Configuration

For production deployments, specify allowed origins explicitly: 
export ALLOWED_ORIGINS=https://your-app.com
The CORS configuration (from src/http.ts:21-37) includes:
  • Dynamic origin validation
  • Exposed headers: Mcp-Session-Id, mcp-protocol-version
  • Allowed headers: Content-Type, mcp-session-id
Using ALLOWED_ORIGINS=* in production exposes your server to any origin. Always restrict origins to trusted domains.

​
Health Check Endpoint

The server exposes a health check endpoint at /health for monitoring and load balancer integration. 
curl http://localhost:8080/health
Response: 
{
  "status": "ok",
  "service": "perplexity-mcp-server"
}
This endpoint is defined in src/http.ts:69-71 and always returns a 200 status code when the server is running.

​
MCP Endpoint

The main MCP protocol endpoint is available at /mcp and handles all MCP protocol requests: 
http://localhost:8080/mcp
The endpoint:
  • Accepts all HTTP methods (GET, POST, etc.)
  • Uses MCP Streamable HTTP transport
  • Generates session IDs automatically
  • Returns JSON-RPC 2.0 formatted responses
  • Handles errors with standard error codes

​
Client Connection Configuration

Configure your MCP client to connect to the HTTP endpoint: 
{
  "mcpServers": {
    "perplexity": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

​
Real Deployment Examples

​
Development Server

# Local development with debug logging
export PERPLEXITY_API_KEY=your_key_here
export PERPLEXITY_LOG_LEVEL=DEBUG
export PORT=8080
export BIND_ADDRESS=127.0.0.1
npm run start:http

​
Production Server

# Production deployment with restricted CORS
export PERPLEXITY_API_KEY=your_production_key
export PERPLEXITY_LOG_LEVEL=ERROR
export PORT=8080
export BIND_ADDRESS=0.0.0.0
export ALLOWED_ORIGINS=https://app.example.com,https://api.example.com
export PERPLEXITY_TIMEOUT_MS=600000
npm run start:http

​
Behind Reverse Proxy

# Running behind nginx or similar
export PERPLEXITY_API_KEY=your_key_here
export PORT=8080
export BIND_ADDRESS=127.0.0.1  # Only accept local connections
export ALLOWED_ORIGINS=https://your-domain.com
npm run start:http
When running behind a reverse proxy like nginx or Apache, bind to 127.0.0.1 and let the proxy handle external connections and SSL termination.

​
Process Management

For production deployments, use a process manager to keep the server running:

​
PM2 Example

npm install -g pm2
pm2 start dist/http.js --name perplexity-mcp
pm2 save
pm2 startup

​
systemd Example

Create /etc/systemd/system/perplexity-mcp.service: 
[Unit]
Description=Perplexity MCP Server
After=network.target

[Service]
Type=simple
User=nodejs
WorkingDirectory=/opt/perplexity-mcp-server
Environment="PERPLEXITY_API_KEY=your_key_here"
Environment="PORT=8080"
Environment="BIND_ADDRESS=0.0.0.0"
ExecStart=/usr/bin/node dist/http.js
Restart=on-failure

[Install]
WantedBy=multi-user.target
Always store sensitive environment variables like PERPLEXITY_API_KEY securely. Consider using environment files with restricted permissions or secret management services.

Build docs developers (and LLMs) love

Get started for freeTalk to us