@perplexity-ai/mcp-server 0.5.2 → 0.6.0

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Official Perplexity AI plugin providing real-time web search, reasoning, and research capabilities",
-    "version": "0.5.2"
+    "version": "0.6.0"
   },
   "plugins": [
     {
       "name": "perplexity",
       "source": "./",
       "description": "Real-time web search, reasoning, and research through Perplexity's API",
-      "version": "0.5.2",
+      "version": "0.6.0",
       "author": {
         "name": "Perplexity AI",
         "email": "api@perplexity.ai"

package/README.md

@@ -13,7 +13,7 @@ The official MCP server implementation for the Perplexity API Platform, providin
 ### **perplexity_search**
 Direct web search using the Perplexity Search API. Returns ranked search results with metadata, perfect for finding current information.
 
-### **perplexity_ask** 
+### **perplexity_ask**
 General-purpose conversational AI with real-time web search using the `sonar-pro` model. Great for quick questions and everyday searches.
 
 ### **perplexity_research**
@@ -30,61 +30,37 @@ Advanced reasoning and problem-solving using the `sonar-reasoning-pro` model. Pe
 ## Configuration
 
 ### Get Your API Key
+
 1. Get your Perplexity API Key from the [API Portal](https://www.perplexity.ai/account/api/group)
-2. Set it as an environment variable: `PERPLEXITY_API_KEY=your_key_here`
-3. (Optional) Set a timeout for requests: `PERPLEXITY_TIMEOUT_MS=600000`. The default is 5 minutes.
-4. (Optional) Set log level for debugging: `PERPLEXITY_LOG_LEVEL=DEBUG|INFO|WARN|ERROR`. The default is ERROR.
+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 log level: `PERPLEXITY_LOG_LEVEL=DEBUG|INFO|WARN|ERROR` (default: ERROR)
 
 ### Claude Code
 
-#### Option 1: Install via Plugin (Recommended)
-
-The easiest way to get started with Perplexity in Claude Code, set your API key:
 ```bash
-export PERPLEXITY_API_KEY="your_key_here"
+claude mcp add perplexity --env PERPLEXITY_API_KEY="your_key_here" -- npx -y @perplexity-ai/mcp-server
 ```
-Then:
+
+Or install via plugin:
 ```bash
-# Open Claude Code
+export PERPLEXITY_API_KEY="your_key_here"
 claude
-
-# Add the Perplexity marketplace
-/plugin marketplace add perplexityai/modelcontextprotocol
-
-# Install the plugin
-/plugin install perplexity
+# Then run: /plugin marketplace add perplexityai/modelcontextprotocol
+# Then run: /plugin install perplexity
 ```
 
-#### Option 2: Manual Configuration
+### Cursor, Claude Desktop & Windsurf
 
-Run in your terminal:
+We recommend using the one-click install badge at the top of this README for Cursor.
 
-```bash
-claude mcp add perplexity --transport stdio --env PERPLEXITY_API_KEY=your_key_here -- npx -y perplexity-mcp
-```
+For manual setup, all these clients use the same `mcpServers` format:
 
-Or add to your `claude.json`:
-
-```json
-"mcpServers": {
-  "perplexity": {
-    "type": "stdio",
-    "command": "npx",
-    "args": [
-      "-y",
-      "perplexity-mcp"
-    ],
-    "env": {
-      "PERPLEXITY_API_KEY": "your_key_here",
-      "PERPLEXITY_TIMEOUT_MS": "600000"
-    }
-  }
-}
-```
-
-### Cursor
-
-Add to your `mcp.json` (Cursor):
+| Client | Config File |
+|--------|-------------|
+| Cursor | `~/.cursor/mcp.json` |
+| Claude Desktop | `claude_desktop_config.json` |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
 
 ```json
 {
@@ -102,63 +78,33 @@ Add to your `mcp.json` (Cursor):
 
 ### VS Code
 
-Add to your `.vscode/mcp.json` (VS Code):
+We recommend using the one-click install badge at the top of this README for VS Code, or for manual setup, add to `.vscode/mcp.json`:
 
 ```json
 {
-	"servers": {
-		"perplexity": {
-			"type": "stdio",
-			"command": "npx",
-			"args": [
-				"-y",
-				"@perplexity-ai/mcp-server"
-			],
-			"env": {
-				"PERPLEXITY_API_KEY": "your_key_here"
-			}
-		}
-	}
-}
-```
-
-Or use the one-click install badges at the top of this README.
-
-### Codex
-
-Run in your terminal:
-
-```bash
-codex mcp add perplexity --env PERPLEXITY_API_KEY=your_key_here -- npx -y @perplexity-ai/mcp-server
-```
-
-### Claude Desktop
-
-Add to your `claude_desktop_config.json`:
-
-```json
-{
-  "mcpServers": {
+  "servers": {
     "perplexity": {
+      "type": "stdio",
       "command": "npx",
       "args": ["-y", "@perplexity-ai/mcp-server"],
       "env": {
-        "PERPLEXITY_API_KEY": "your_key_here",
-        "PERPLEXITY_TIMEOUT_MS": "600000"
+        "PERPLEXITY_API_KEY": "your_key_here"
       }
     }
   }
 }
 ```
 
-### Other MCP Clients
-
-For any MCP-compatible client, use:
+### Codex
 
 ```bash
-npx @perplexity-ai/mcp-server
+codex mcp add perplexity --env PERPLEXITY_API_KEY="your_key_here" -- npx -y @perplexity-ai/mcp-server
 ```
 
+### Other MCP Clients
+
+Most clients can be manually configured to use the `mcpServers` wrapper in their configuration file (like Cursor). If your client doesn't work, check its documentation for the correct wrapper format.
+
 ### 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:
@@ -190,39 +136,34 @@ If you'd rather use the standard variables, we support `HTTPS_PROXY` and `HTTP_P
 > 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`.
 
-
 ### HTTP Server Deployment
 
-For cloud or shared deployments, you can run the server in HTTP mode:
+For cloud or shared deployments, run the server in HTTP mode.
 
 #### Environment Variables
 
-The HTTP server supports these configuration options:
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `PERPLEXITY_API_KEY` | Your Perplexity API key | *Required* |
+| `PORT` | HTTP server port | `8080` |
+| `BIND_ADDRESS` | Network interface to bind to | `0.0.0.0` |
+| `ALLOWED_ORIGINS` | CORS origins (comma-separated) | `*` |
 
-- **`PORT`** - HTTP server port (default: `8080`)
-- **`BIND_ADDRESS`** - Network interface to bind to (default: `127.0.0.1` for local, use `0.0.0.0` for hosted)
-- **`ALLOWED_ORIGINS`** - Comma-separated list of allowed CORS origins (default: `http://localhost:3000,http://127.0.0.1:3000`, use `*` for public service)
-- **`PERPLEXITY_API_KEY`** - Your Perplexity API key (required)
-
-#### Using Docker
+#### Docker
 
 ```bash
 docker build -t perplexity-mcp-server .
 docker run -p 8080:8080 -e PERPLEXITY_API_KEY=your_key_here perplexity-mcp-server
 ```
 
-The server will be accessible at `http://localhost:8080/mcp`
-
-#### Using Node.js Directly
+#### Node.js
 
 ```bash
-npm install
-npm run build
-npm run start:http
+export PERPLEXITY_API_KEY=your_key_here
+npm install && npm run build && npm run start:http
 ```
 
-Connect your MCP client to: `http://localhost:8080/mcp`
-
+The server will be accessible at `http://localhost:8080/mcp`
 
 ## Troubleshooting
 
@@ -231,6 +172,7 @@ Connect your MCP client to: `http://localhost:8080/mcp`
 - **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](https://community.perplexity.ai) or [file an issue](https://github.com/perplexityai/modelcontextprotocol/issues).
 

package/dist/http.js

@@ -4,7 +4,6 @@ import cors from "cors";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { createPerplexityServer } from "./server.js";
 import { logger } from "./logger.js";
-// Check for required API key
 const PERPLEXITY_API_KEY = process.env.PERPLEXITY_API_KEY;
 if (!PERPLEXITY_API_KEY) {
     logger.error("PERPLEXITY_API_KEY environment variable is required");
@@ -12,11 +11,8 @@ if (!PERPLEXITY_API_KEY) {
 }
 const app = express();
 const PORT = parseInt(process.env.PORT || "8080", 10);
-const BIND_ADDRESS = process.env.BIND_ADDRESS || "127.0.0.1";
-const ALLOWED_ORIGINS = process.env.ALLOWED_ORIGINS?.split(",") || [
-    "http://localhost:3000",
-    "http://127.0.0.1:3000",
-];
+const BIND_ADDRESS = process.env.BIND_ADDRESS || "0.0.0.0";
+const ALLOWED_ORIGINS = process.env.ALLOWED_ORIGINS?.split(",") || ["*"];
 // CORS configuration for browser-based MCP clients
 app.use(cors({
     origin: (origin, callback) => {
@@ -37,10 +33,6 @@ app.use(cors({
 }));
 app.use(express.json());
 const mcpServer = createPerplexityServer();
-/**
- * POST: client-to-server messages (requests, responses, notifications)
- * GET: SSE stream for server-to-client messages (notifications, requests)
- */
 app.all("/mcp", async (req, res) => {
     try {
         const transport = new StreamableHTTPServerTransport({
@@ -64,15 +56,9 @@ app.all("/mcp", async (req, res) => {
         }
     }
 });
-/**
- * Health check endpoint
- */
 app.get("/health", (req, res) => {
     res.json({ status: "ok", service: "perplexity-mcp-server" });
 });
-/**
- * Start the HTTP server
- */
 app.listen(PORT, BIND_ADDRESS, () => {
     logger.info(`Perplexity MCP Server listening on http://${BIND_ADDRESS}:${PORT}/mcp`);
     logger.info(`Allowed origins: ${ALLOWED_ORIGINS.join(", ")}`);

package/dist/index.js

@@ -1,19 +1,14 @@
 #!/usr/bin/env node
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { createPerplexityServer } from "./server.js";
-// Check for required API key
 const PERPLEXITY_API_KEY = process.env.PERPLEXITY_API_KEY;
 if (!PERPLEXITY_API_KEY) {
     console.error("Error: PERPLEXITY_API_KEY environment variable is required");
     process.exit(1);
 }
-/**
- * Initializes and runs the server using standard I/O for communication.
- * Logs an error and exits if the server fails to start.
- */
 async function main() {
     try {
-        const server = createPerplexityServer();
+        const server = createPerplexityServer("local-mcp");
         const transport = new StdioServerTransport();
         await server.connect(transport);
     }
@@ -22,7 +17,6 @@ async function main() {
         process.exit(1);
     }
 }
-// Start the server and catch any startup errors
 main().catch((error) => {
     console.error("Fatal error running server:", error);
     process.exit(1);

package/dist/server.js

@@ -2,52 +2,26 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { fetch as undiciFetch, ProxyAgent } from "undici";
 import { ChatCompletionResponseSchema, SearchResponseSchema } from "./validation.js";
-// Retrieve the Perplexity API key from environment variables
 const PERPLEXITY_API_KEY = process.env.PERPLEXITY_API_KEY;
-/**
- * Gets the proxy URL from environment variables.
- * Checks PERPLEXITY_PROXY, HTTPS_PROXY, HTTP_PROXY in order.
- *
- * @returns {string | undefined} The proxy URL if configured, undefined otherwise
- */
 export function getProxyUrl() {
     return process.env.PERPLEXITY_PROXY ||
         process.env.HTTPS_PROXY ||
         process.env.HTTP_PROXY ||
         undefined;
 }
-/**
- * Creates a proxy-aware fetch function.
- * Uses undici with ProxyAgent when a proxy is configured, otherwise uses native fetch.
- *
- * @param {string} url - The URL to fetch
- * @param {RequestInit} options - Fetch options
- * @returns {Promise<Response>} The fetch response
- */
 export async function proxyAwareFetch(url, options = {}) {
     const proxyUrl = getProxyUrl();
     if (proxyUrl) {
-        // Use undici with ProxyAgent when proxy is configured
         const proxyAgent = new ProxyAgent(proxyUrl);
         const undiciOptions = {
             ...options,
             dispatcher: proxyAgent,
         };
         const response = await undiciFetch(url, undiciOptions);
-        // Cast to native Response type for compatibility
         return response;
     }
-    // Use native fetch when no proxy is configured
     return fetch(url, options);
 }
-/**
- * Validates an array of message objects for chat completion tools.
- * Ensures each message has a valid role and content field.
- *
- * @param {unknown} messages - The messages to validate
- * @param {string} toolName - The name of the tool calling this validation (for error messages)
- * @throws {Error} If messages is not an array or if any message is invalid
- */
 export function validateMessages(messages, toolName) {
     if (!Array.isArray(messages)) {
         throw new Error(`Invalid arguments for ${toolName}: 'messages' must be an array`);
@@ -65,33 +39,15 @@ export function validateMessages(messages, toolName) {
         }
     }
 }
-/**
- * Strips thinking tokens (content within <think>...</think> tags) from the response.
- * This helps reduce context usage when the thinking process is not needed.
- *
- * @param {string} content - The content to process
- * @returns {string} The content with thinking tokens removed
- */
 export function stripThinkingTokens(content) {
     return content.replace(/<think>[\s\S]*?<\/think>/g, '').trim();
 }
-/**
- * Performs a chat completion by sending a request to the Perplexity API.
- * Appends citations to the returned message content if they exist.
- *
- * @param {Message[]} messages - An array of message objects.
- * @param {string} model - The model to use for the completion.
- * @param {boolean} stripThinking - If true, removes <think>...</think> tags from the response.
- * @returns {Promise<string>} The chat completion result with appended citations.
- * @throws Will throw an error if the API request fails.
- */
-export async function performChatCompletion(messages, model = "sonar-pro", stripThinking = false) {
+export async function performChatCompletion(messages, model = "sonar-pro", stripThinking = false, serviceOrigin) {
     if (!PERPLEXITY_API_KEY) {
         throw new Error("PERPLEXITY_API_KEY environment variable is required");
     }
     // Read timeout fresh each time to respect env var changes
     const TIMEOUT_MS = parseInt(process.env.PERPLEXITY_TIMEOUT_MS || "300000", 10);
-    // Construct the API endpoint URL and request body
     const url = new URL("https://api.perplexity.ai/chat/completions");
     const body = {
         model: model,
@@ -101,12 +57,16 @@ export async function performChatCompletion(messages, model = "sonar-pro", strip
     const timeoutId = setTimeout(() => controller.abort(), TIMEOUT_MS);
     let response;
     try {
+        const headers = {
+            "Content-Type": "application/json",
+            "Authorization": `Bearer ${PERPLEXITY_API_KEY}`,
+        };
+        if (serviceOrigin) {
+            headers["X-Service"] = serviceOrigin;
+        }
         response = await proxyAwareFetch(url.toString(), {
             method: "POST",
-            headers: {
-                "Content-Type": "application/json",
-                "Authorization": `Bearer ${PERPLEXITY_API_KEY}`,
-            },
+            headers,
             body: JSON.stringify(body),
             signal: controller.signal,
         });
@@ -119,7 +79,6 @@ export async function performChatCompletion(messages, model = "sonar-pro", strip
         }
         throw new Error(`Network error while calling Perplexity API: ${error}`);
     }
-    // Check for non-successful HTTP status
     if (!response.ok) {
         let errorText;
         try {
@@ -148,13 +107,10 @@ export async function performChatCompletion(messages, model = "sonar-pro", strip
         throw new Error(`Failed to parse JSON response from Perplexity API: ${error}`);
     }
     const firstChoice = data.choices[0];
-    // Directly retrieve the main message content from the response
     let messageContent = firstChoice.message.content;
-    // Strip thinking tokens if requested
     if (stripThinking) {
         messageContent = stripThinkingTokens(messageContent);
     }
-    // If citations are provided, append them to the message content
     if (data.citations && Array.isArray(data.citations) && data.citations.length > 0) {
         messageContent += "\n\nCitations:\n";
         data.citations.forEach((citation, index) => {
@@ -163,12 +119,6 @@ export async function performChatCompletion(messages, model = "sonar-pro", strip
     }
     return messageContent;
 }
-/**
- * Formats search results from the Perplexity Search API into a readable string.
- *
- * @param {SearchResponse} data - The search response data from the API.
- * @returns {string} Formatted search results.
- */
 export function formatSearchResults(data) {
     if (!data.results || !Array.isArray(data.results)) {
         return "No search results found.";
@@ -187,17 +137,7 @@ export function formatSearchResults(data) {
     });
     return formattedResults;
 }
-/**
- * Performs a web search using the Perplexity Search API.
- *
- * @param {string} query - The search query string.
- * @param {number} maxResults - Maximum number of results to return (1-20).
- * @param {number} maxTokensPerPage - Maximum tokens to extract per webpage.
- * @param {string} country - Optional ISO country code for regional results.
- * @returns {Promise<string>} The formatted search results.
- * @throws Will throw an error if the API request fails.
- */
-export async function performSearch(query, maxResults = 10, maxTokensPerPage = 1024, country) {
+export async function performSearch(query, maxResults = 10, maxTokensPerPage = 1024, country, serviceOrigin) {
     if (!PERPLEXITY_API_KEY) {
         throw new Error("PERPLEXITY_API_KEY environment variable is required");
     }
@@ -214,12 +154,16 @@ export async function performSearch(query, maxResults = 10, maxTokensPerPage = 1
     const timeoutId = setTimeout(() => controller.abort(), TIMEOUT_MS);
     let response;
     try {
+        const headers = {
+            "Content-Type": "application/json",
+            "Authorization": `Bearer ${PERPLEXITY_API_KEY}`,
+        };
+        if (serviceOrigin) {
+            headers["X-Service"] = serviceOrigin;
+        }
         response = await proxyAwareFetch(url.toString(), {
             method: "POST",
-            headers: {
-                "Content-Type": "application/json",
-                "Authorization": `Bearer ${PERPLEXITY_API_KEY}`,
-            },
+            headers,
             body: JSON.stringify(body),
             signal: controller.signal,
         });
@@ -232,7 +176,6 @@ export async function performSearch(query, maxResults = 10, maxTokensPerPage = 1
         }
         throw new Error(`Network error while calling Perplexity Search API: ${error}`);
     }
-    // Check for non-successful HTTP status
     if (!response.ok) {
         let errorText;
         try {
@@ -253,18 +196,11 @@ export async function performSearch(query, maxResults = 10, maxTokensPerPage = 1
     }
     return formatSearchResults(data);
 }
-/**
- * Creates and configures the Perplexity MCP server with all tools.
- * This factory function is transport-agnostic and returns a configured server instance.
- *
- * @returns The configured MCP server instance
- */
-export function createPerplexityServer() {
+export function createPerplexityServer(serviceOrigin) {
     const server = new McpServer({
         name: "io.github.perplexityai/mcp-server",
-        version: "0.5.2",
+        version: "0.6.0",
     });
-    // Register perplexity_ask tool
     server.registerTool("perplexity_ask", {
         title: "Ask Perplexity",
         description: "Engages in a conversation using the Sonar API. " +
@@ -285,13 +221,12 @@ export function createPerplexityServer() {
         },
     }, async ({ messages }) => {
         validateMessages(messages, "perplexity_ask");
-        const result = await performChatCompletion(messages, "sonar-pro");
+        const result = await performChatCompletion(messages, "sonar-pro", false, serviceOrigin);
         return {
             content: [{ type: "text", text: result }],
             structuredContent: { response: result },
         };
     });
-    // Register perplexity_research tool
     server.registerTool("perplexity_research", {
         title: "Deep Research",
         description: "Performs deep research using the Perplexity API. " +
@@ -315,13 +250,12 @@ export function createPerplexityServer() {
     }, async ({ messages, strip_thinking }) => {
         validateMessages(messages, "perplexity_research");
         const stripThinking = typeof strip_thinking === "boolean" ? strip_thinking : false;
-        const result = await performChatCompletion(messages, "sonar-deep-research", stripThinking);
+        const result = await performChatCompletion(messages, "sonar-deep-research", stripThinking, serviceOrigin);
         return {
             content: [{ type: "text", text: result }],
             structuredContent: { response: result },
         };
     });
-    // Register perplexity_reason tool
     server.registerTool("perplexity_reason", {
         title: "Advanced Reasoning",
         description: "Performs reasoning tasks using the Perplexity API. " +
@@ -345,13 +279,12 @@ export function createPerplexityServer() {
     }, async ({ messages, strip_thinking }) => {
         validateMessages(messages, "perplexity_reason");
         const stripThinking = typeof strip_thinking === "boolean" ? strip_thinking : false;
-        const result = await performChatCompletion(messages, "sonar-reasoning-pro", stripThinking);
+        const result = await performChatCompletion(messages, "sonar-reasoning-pro", stripThinking, serviceOrigin);
         return {
             content: [{ type: "text", text: result }],
             structuredContent: { response: result },
         };
     });
-    // Register perplexity_search tool
     server.registerTool("perplexity_search", {
         title: "Search the Web",
         description: "Performs web search using the Perplexity Search API. " +
@@ -377,7 +310,7 @@ export function createPerplexityServer() {
         const maxResults = typeof max_results === "number" ? max_results : 10;
         const maxTokensPerPage = typeof max_tokens_per_page === "number" ? max_tokens_per_page : 1024;
         const countryCode = typeof country === "string" ? country : undefined;
-        const result = await performSearch(query, maxResults, maxTokensPerPage, countryCode);
+        const result = await performSearch(query, maxResults, maxTokensPerPage, countryCode, serviceOrigin);
         return {
             content: [{ type: "text", text: result }],
             structuredContent: { results: result },

package/dist/types.js

@@ -1,4 +1 @@
-/**
- * Type definitions for the Perplexity MCP Server
- */
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@perplexity-ai/mcp-server",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "mcpName": "io.github.perplexityai/mcp-server",
   "description": "Real-time web search, reasoning, and research through Perplexity's API",
   "keywords": [