Perplexity with Cursor

Use Perplexity with Cursor by calling the Agent API from project code with the Perplexity or OpenAI SDK, or by adding a Perplexity MCP server.

Overview

Cursor is an AI-first code editor that can call any HTTP API from your project code and supports the Model Context Protocol (MCP) for in-editor tools. This guide covers three integration paths for Perplexity:

Official TypeScript SDK

Call the Perplexity API directly from your project code while you build in Cursor. Recommended.

OpenAI-Compatible SDK

Reuse an existing OpenAI client by pointing baseURL at https://api.perplexity.ai/v1.

Cursor MCP

Configure the hosted Perplexity Docs MCP in .cursor/mcp.json so Cursor can look up Perplexity docs while you code.

Recommended path: Use the official SDK (or the OpenAI-compatible SDK) from your application code, and add the Perplexity Docs MCP to Cursor for in-editor documentation lookup.

Prerequisites

• Cursor installed (cursor.com/download)
• Node.js 18+ for the TypeScript examples
• A Perplexity API key

Get API Key

Generate a key from the Perplexity API Portal.

Get Key

API Key Handling

Never hardcode your API key in source files or commit it to a repository. Store it in an environment variable and read it at runtime:

macOS/Linux

export PERPLEXITY_API_KEY="your_api_key_here"

Windows

setx PERPLEXITY_API_KEY "your_api_key_here"

.env (project-local)

Create a .env file in your project root and add it to .gitignore:

# .env
PERPLEXITY_API_KEY=your_api_key_here

Load it at startup (for example with dotenv):

import "dotenv/config";

Treat PERPLEXITY_API_KEY like a password. Don’t paste it into chat, prompts, or shared files. If a key is exposed, rotate it immediately.

---

Path 1: Official TypeScript SDK (Recommended)

Build your application in Cursor and call the Perplexity API from your code using the official SDK. This is the most reliable path and gives you full type safety, preset support, and access to every API feature.

Install

npm install @perplexity-ai/perplexity_ai

pnpm and yarn work the same way: pnpm add @perplexity-ai/perplexity_ai / yarn add @perplexity-ai/perplexity_ai.

Agent API with low

The Agent API is the recommended surface for most applications. Use the low preset for web-grounded responses with sensible defaults:

import Perplexity from "@perplexity-ai/perplexity_ai";

const client = new Perplexity(); // reads PERPLEXITY_API_KEY from the environment

const response = await client.responses.create({
  preset: "low",
  input: "Summarize the latest changes to the Perplexity Agent API.",
});

console.log(`Model used: ${response.model}`);
console.log(response.output_text);

Python equivalent

from perplexity import Perplexity

client = Perplexity()  # reads PERPLEXITY_API_KEY from the environment

response = client.responses.create(
    preset="low",
    input="Summarize the latest changes to the Perplexity Agent API.",
)

print(f"Model used: {response.model}")
print(response.output_text)

Add Web Search

Enable the web_search tool for explicit control over when search is used:

import Perplexity from "@perplexity-ai/perplexity_ai";

const client = new Perplexity();

const response = await client.responses.create({
  model: "openai/gpt-5.4",
  input: "What are the latest developments in AI inference hardware?",
  tools: [{ type: "web_search" }],
  instructions:
    "You have access to a web_search tool. Use it for questions about current events, news, or recent developments.",
});

if (response.status === "completed") {
  console.log(response.output_text);
}

Cursor’s AI chat can scaffold and edit these snippets for you. Open the chat with Cmd+L / Ctrl+L, paste in your goal, and ask Cursor to “use @perplexity-ai/perplexity_ai with the low preset.”

For more presets, tools, and configuration options see the Agent API quickstart and the SDK overview.

---

Path 2: OpenAI-Compatible SDK

If you already have an OpenAI client in your project, you can reuse it by pointing the baseURL at https://api.perplexity.ai/v1. Perplexity accepts POST /v1/responses as an alias for the Agent API.

Install

npm install openai

Use It

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.PERPLEXITY_API_KEY,
  baseURL: "https://api.perplexity.ai/v1",
});

const response = await client.responses.create({
  model: "openai/gpt-5.4",
  input: "Explain the key differences between REST and GraphQL APIs.",
});

console.log(response.output_text);

Python equivalent

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("PERPLEXITY_API_KEY"),
    base_url="https://api.perplexity.ai/v1",
)

response = client.responses.create(
    model="openai/gpt-5.4",
    input="Explain the key differences between REST and GraphQL APIs.",
)

print(response.output_text)

Use baseURL (TypeScript) or base_url (Python) — both must include the /v1 suffix. See the OpenAI Compatibility guide for the full list of supported parameters and which Perplexity features are available through this path.

---

Path 3: Cursor MCP for Docs Lookup

Cursor supports the Model Context Protocol (MCP). The hosted Perplexity Docs MCP at https://docs.perplexity.ai/mcp lets Cursor search and read Perplexity’s documentation directly from chat — useful for grounding code suggestions in canonical docs without context-switching to a browser.

Project-Scoped Configuration

Add a .cursor/mcp.json file at the root of your project. This makes the server available only for that project:

{
  "mcpServers": {
    "perplexity-docs": {
      "url": "https://docs.perplexity.ai/mcp"
    }
  }
}

Global Configuration

To make the server available across all projects, add the same entry to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "perplexity-docs": {
      "url": "https://docs.perplexity.ai/mcp"
    }
  }
}

1. Add the Configuration

   Save the JSON above to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global).

2. Reload Cursor

   Open Cursor → Settings → MCP and confirm perplexity-docs appears with a green/ready status. Restart Cursor if needed.

3. Use It from Chat

   In Cursor chat, ask questions like “Using the Perplexity docs MCP, show me how to enable low in the Agent API.” Cursor will call the MCP server and ground its answer in current documentation.

The Docs MCP is read-only and does not require an API key — it only serves Perplexity documentation. To give Cursor access to Perplexity search and reasoning tools (not just docs), install the Perplexity MCP Server, which uses @perplexity-ai/mcp-server and requires PERPLEXITY_API_KEY.

---

Replacing the Cursor Model (Not Supported)

Perplexity is not included in Cursor’s supported BYOK provider list. In current Cursor builds, the custom OpenAI-compatible model override sends Chat Completions requests (POST {base}/chat/completions). The Perplexity Agent API uses the Responses format and does not serve /v1/chat/completions, so pointing Cursor’s override at https://api.perplexity.ai/v1 fails with 404.

Instead:

• Use Perplexity from your project code (Path 1 or Path 2) for Agent API access.
• Add the Perplexity Docs MCP (Path 3) for in-editor docs lookup, or the Perplexity MCP Server to give Cursor’s agent Perplexity search and reasoning tools.

---

Next Steps

Agent API Quickstart

Presets, tools, and the full Agent API surface used by the examples above.

Perplexity SDK Overview

Install, configure, and use the official Python and TypeScript SDKs.

OpenAI Compatibility

Drop-in compatibility details, supported parameters, and migration tips.

Perplexity MCP Server

Add Perplexity search, ask, research, and reason tools to Cursor and other MCP clients.

Need help? Join the Perplexity developer community for support and discussion.