Perplexity MCP Server

A production-ready Model Context Protocol (MCP) server that integrates Perplexity AI's powerful search capabilities. Get real-time AI-powered answers with web sources and citations through the StreamableHTTP transport.

Overview

This MCP server provides seamless integration with Perplexity AI's chat API, enabling AI applications to access current web information through the Model Context Protocol. Built with TypeScript, Express, and the MCP SDK StreamableHTTP transport for efficient, scalable communication.

Features

• ✅ Dual Transport Support - Both Stdio (auto-start) and HTTP (standalone) transports
• ✅ Real-time Web Search - Powered by Perplexity's Sonar Pro model
• ✅ Rich Responses - AI-generated answers with citations and related images
• ✅ Flexible Authentication - Supports Authorization header and environment variables
• ✅ Smart Port Management - Automatic port conflict detection with helpful error messages
• ✅ Production Ready - Express-based with proper error handling and session management
• ✅ Universal Compatibility - Works with any MCP client supporting StreamableHTTP or Stdio

Quick Start

Prerequisites

• Node.js 18+
• pnpm package manager
• Perplexity API Key from perplexity.ai

Installation

# Clone or navigate to the project directory
cd perplexity-mcp-server

# Install dependencies
pnpm install

# Build the project
pnpm build

Running the Server

For HTTP Transport:

# Build and start
pnpm build
pnpm start

The server will start on http://127.0.0.1:3001/mcp

For Stdio Transport:

No manual start needed - the MCP client launches it automatically. Just configure your client and restart it.

Get Your API Key

Sign up and get your Perplexity API key from https://www.perplexity.ai/

Client Configuration

This server provides two transport options:

Transport	Use Case	Pros	When to Use
Stdio	Development, Single Client	✅ Auto-starts<br>✅ No port conflicts<br>✅ Simple setup	Cursor IDE, Claude Desktop (single user)
HTTP	Production, Multiple Clients	✅ Serves multiple clients<br>✅ Stays running<br>✅ Better for servers	Production deployments, shared environments

Option 1: Stdio Transport (Auto-Start) ⭐ Recommended

The client launches the server automatically. No manual server start required.

Best for: Cursor IDE, Claude Desktop, single-user development

Cursor IDE (Stdio)

Create or edit ~/.cursor/mcp.json (global) or .cursor/mcp.json (project-specific):

{
  "mcpServers": {
    "perplexity": {
      "command": "node",
      "args": ["/absolute/path/to/perplexity-mcp-server/dist/stdio.js"],
      "env": {
        "PERPLEXITY_API_KEY": "YOUR_PERPLEXITY_API_KEY"
      }
    }
  }
}

Note: Replace /absolute/path/to/perplexity-mcp-server with your actual project path.

Claude Desktop (Stdio)

Same configuration format:

{
  "mcpServers": {
    "perplexity": {
      "command": "node",
      "args": ["/absolute/path/to/perplexity-mcp-server/dist/stdio.js"],
      "env": {
        "PERPLEXITY_API_KEY": "YOUR_PERPLEXITY_API_KEY"
      }
    }
  }
}

Option 2: HTTP Transport (Standalone Server) 🚀 Production

Server runs independently and can serve multiple clients.

Best for: Production deployments, shared environments, multiple concurrent clients

Step 1: Start the server

pnpm build
pnpm start

Step 2: Configure Cursor

Create or edit ~/.cursor/mcp.json (global) or .cursor/mcp.json (project-specific):

{
  "mcpServers": {
    "perplexity": {
      "url": "http://127.0.0.1:3001/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_PERPLEXITY_API_KEY"
      }
    }
  }
}

Step 3: Restart Cursor

The perplexity_search tool will now be available.

Claude Desktop (HTTP)

Same configuration format:

{
  "mcpServers": {
    "perplexity": {
      "url": "http://127.0.0.1:3001/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_PERPLEXITY_API_KEY"
      }
    }
  }
}

Note: The server must be running before connecting.

Other MCP Clients

Any MCP client supporting StreamableHTTP can connect using:

• Server URL: http://127.0.0.1:3001/mcp
• Authentication: Authorization: Bearer YOUR_PERPLEXITY_API_KEY header
• Transport: StreamableHTTP (SSE-based)

Refer to your MCP client's documentation for specific configuration steps.

MCP SDK Integration

For direct SDK usage:

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const client = new Client(
  {
    name: "my-client",
    version: "1.0.0",
  },
  {
    capabilities: {},
  }
);

const transport = new StreamableHTTPClientTransport(
  new URL("http://127.0.0.1:3001/mcp"),
  {
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
    },
  }
);

await client.connect(transport);

const result = await client.callTool({
  name: "perplexity_search",
  arguments: {
    query: "What are the latest developments in quantum computing?",
  },
});

console.log(result);

Available Tools

perplexity_search

Search and get AI-powered answers with real-time web data, citations, and images.

Parameters:

• query (string, required): Your search query or question

Example:

{
  "query": "What are the latest developments in AI agents?"
}

Response includes:

• AI-generated answer based on current web data
• Sources: Citations with URLs
• Related Images: Relevant images with titles and URLs

Model Configuration:

• Model: sonar-pro (Perplexity's premier advanced search model)
• Search Recency: month (configurable)
• Streaming: Enabled (from Perplexity API, processed server-side)
• Citations: Included
• Images: Included when relevant

Configuration

Environment Variables

• PERPLEXITY_API_KEY: Your Perplexity API key (optional if using Authorization header)
• PORT: Server port (default: 3001)

API Key Priority

The server accepts API keys from two sources with the following priority:

1. Authorization Header (Recommended)

   • Format: Authorization: Bearer YOUR_API_KEY
   • Sent per-request via HTTP headers
   • More secure for multi-user scenarios

2. Environment Variable (Fallback)

   • Set PERPLEXITY_API_KEY when starting the server
   • Shared across all requests

Usage Examples

With environment variable:

PERPLEXITY_API_KEY=pplx-abc123 PORT=8080 pnpm start

With header authentication:

pnpm start
# Client sends: Authorization: Bearer pplx-abc123

Development

Build

pnpm build

Development Mode (with auto-reload)

HTTP Server:

pnpm dev

Stdio Server:

pnpm dev:stdio

Watch TypeScript Compilation

pnpm watch

Test with MCP Inspector

HTTP Server:

pnpm inspector

Stdio Server:

pnpm inspector:stdio

Health Check

Verify the server is running:

curl http://127.0.0.1:3001/health

Expected response:

{ "status": "ok", "service": "perplexity-mcp-server" }

Architecture

StreamableHTTP Transport

This server uses the MCP StreamableHTTP transport providing:

• HTTP/HTTPS - Standard protocols for web communication
• Server-Sent Events (SSE) - Real-time server-to-client messages
• Session Management - Stateful sessions with UUID-based IDs
• Scalability - Multiple concurrent connections
• Infrastructure Compatibility - Works with proxies, load balancers, and CDNs

Request Flow

1. Client sends HTTP POST to /mcp endpoint
2. Express extracts Authorization header → API key
3. Request forwarded to MCP transport
4. Tool handler receives request with API key
5. Server calls Perplexity API with streaming
6. Response parsed and formatted with citations/images
7. Complete response returned via MCP protocol

Technology Stack

• Runtime: Node.js 18+
• Language: TypeScript 5.3+
• Framework: Express 5
• MCP SDK: @modelcontextprotocol/sdk
• HTTP Client: node-fetch 3
• Validation: Zod 3

Production Deployment

Security Best Practices

1. API Key Security

   • Use environment variables or secure vaults
   • Never commit API keys to version control
   • Rotate keys regularly

2. Network Security

   • Server binds to 127.0.0.1 (localhost) by default
   • Use reverse proxy (nginx, Caddy) with SSL/TLS for production
   • Configure firewall rules appropriately

3. Input Validation

   • All inputs validated with Zod schemas
   • Query length limits enforced

4. Rate Limiting

   • Consider adding rate limiting middleware
   • Monitor Perplexity API usage

Reverse Proxy Example (nginx)

server {
    listen 443 ssl http2;
    server_name mcp.yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location /mcp {
        proxy_pass http://127.0.0.1:3001;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Process Management (PM2)

# Install PM2
npm install -g pm2

# Start server
pm2 start dist/server.js --name perplexity-mcp

# With environment variables
pm2 start dist/server.js --name perplexity-mcp \
  --env PERPLEXITY_API_KEY=your-key \
  --env PORT=3001

# Save process list
pm2 save

# Setup startup script
pm2 startup

Docker Deployment

FROM node:18-alpine

WORKDIR /app

COPY package.json pnpm-lock.yaml ./
RUN npm install -g pnpm && pnpm install --frozen-lockfile

COPY . .
RUN pnpm build

EXPOSE 3001

CMD ["node", "dist/server.js"]

Troubleshooting

Common Issues

Error: "PERPLEXITY_API_KEY is required"

• Ensure API key is provided via Authorization header or environment variable
• Check header format: Authorization: Bearer YOUR_KEY
• Verify the server receives the header (check logs)

Connection Refused

• Verify server is running: curl http://127.0.0.1:3001/health
• Check port matches configuration
• Ensure no firewall is blocking the port

Citations or Images showing as "Untitled" or broken links

• This should be fixed in the latest version
• Rebuild: pnpm build && pnpm start
• Verify you're running the latest code

Error: "Port 3001 is already in use"

The server automatically detects port conflicts and provides helpful solutions:

❌ ERROR: Port 3001 is already in use!
   Process: PID 12345: node dist/server.js

💡 To fix this, you can:
   1. Stop the existing server (Ctrl+C in its terminal)
   2. Use a different port: PORT=3002 pnpm start
   3. Kill the process: kill -9 $(lsof -ti:3001)
   4. Find and stop it: lsof -ti:3001 | xargs ps -p

Cursor IDE not finding server (HTTP)

• Ensure server is running before starting Cursor: pnpm start
• Check ~/.cursor/mcp.json syntax is valid JSON
• Fully restart Cursor (Cmd+Q / Ctrl+Q, then relaunch)
• Verify server is running: curl http://127.0.0.1:3001/health
• Check Cursor's MCP panel for connection status

Cursor IDE - Stdio vs HTTP

• Stdio (Recommended): Auto-starts, no manual server needed
• HTTP: Requires pnpm start running in a separate terminal
• If HTTP not connecting, try Stdio instead for simplicity

API Reference

Perplexity API

• Documentation: https://docs.perplexity.ai/
• API Reference: https://docs.perplexity.ai/api-reference/chat-completions
• Model Cards: https://docs.perplexity.ai/guides/model-cards

Model Context Protocol

• MCP Docs: https://modelcontextprotocol.io/
• Specification: https://spec.modelcontextprotocol.io/
• TypeScript SDK: https://github.com/modelcontextprotocol/typescript-sdk

Project Structure

perplexity-mcp-server/
├── src/
│   ├── server.ts          # HTTP transport server (StreamableHTTP)
│   └── stdio.ts           # Stdio transport server (auto-start)
├── dist/                  # Compiled JavaScript output
│   ├── server.js          # HTTP server executable
│   └── stdio.js           # Stdio server executable
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
├── mcp.json.example     # Example MCP client config
└── README.md            # This file

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

License

MIT

Acknowledgments

Built with:

• Model Context Protocol by Anthropic
• Perplexity AI
• Express
• TypeScript

---

Made with ❤️ using the Model Context Protocol

Support

• 📖 Documentation
• 🐛 Report Issues
• 🌟 Star this repo if you find it useful!