Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.perplexity.ai/llms.txt

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

​
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. Cursor’s “custom OpenAI-compatible model” override pointed at Perplexity is experimental and tends to be less reliable than code-level integration or MCP — see Custom Model Override (Experimental).

​
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.

​
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: 
export PERPLEXITY_API_KEY="your_api_key_here"
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.
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.
The Agent API is the recommended surface for most applications. Use the pro-search 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: "pro-search",
  input: "Summarize the latest changes to the Perplexity Agent API.",
});

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

from perplexity import Perplexity

client = Perplexity()  # reads PERPLEXITY_API_KEY from the environment

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

print(f"Model used: {response.model}")
print(response.output_text)
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 pro-search 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);

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 pro-search 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.

​
Custom Model Override (Experimental)

Cursor lets you point its built-in model picker at an OpenAI-compatible base URL. While it is possible to set this to https://api.perplexity.ai/v1 and use a Perplexity model name, this path has limitations:
  • The Agent API surface (presets, structured tool calls, finance/people search) is not fully exercised by Cursor’s internal prompting.
  • Cursor’s autocomplete and edit features are tuned to specific model behaviors and may not work well with substituted models.
  • Streaming, tool use, and error handling can behave differently than in a code-level integration.
For these reasons, we recommend calling Perplexity from your project code (Path 1 or Path 2) and using the Perplexity Docs MCP (Path 3) for in-editor docs lookup. Reach for the custom model override only when you specifically want Cursor’s chat UI to talk to a Perplexity model and are comfortable with the trade-offs.

​
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.