HTTP Server Deployment

Deploy Perplexity MCP Server as an HTTP service for cloud and shared environments

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

Variable	Description	Default	Required
PERPLEXITY_API_KEY	Your Perplexity API key	-	Yes
PORT	HTTP server port	8080	No
BIND_ADDRESS	Network interface to bind to	0.0.0.0	No
ALLOWED_ORIGINS	CORS allowed origins (comma-separated)	*	No
PERPLEXITY_TIMEOUT_MS	Request timeout in milliseconds	300000	No
PERPLEXITY_BASE_URL	Custom API base URL	https://api.perplexity.ai	No
PERPLEXITY_LOG_LEVEL	Logging level: DEBUG, INFO, WARN, ERROR	ERROR	No

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:

Single Origin

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:

Standard MCP Client

{
  "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.