Perplexity Agent

perplexity-agent-mcp

A single-file, zero-third-party-dependency MCP server for Perplexity's Agent API — multi-step web research with citations, exposed to any MCP client over stdio.

Python standard library only: no MCP SDK, no HTTP library, no code generated at build time. perplexity_agent_mcp.py holds your API key and talks to the network on your behalf, so it is written to be read — 1,774 lines, comments included. Both install paths below ship the exact same file; which one you pick changes how many other parties you're trusting to get it onto your disk, not what actually runs.

Background reading: *perplexity-agent-mcp: an open-source MCP server for Perplexity's Agent API* — why this exists, what the Agent API does that Sonar doesn't, and what building it turned up.

Why this exists

Perplexity's own @perplexity-ai/mcp-server wraps the Sonar chat models and the Search API. It does not reach the Agent API (POST /v1/agent) — Perplexity's multi-step, tool-using research endpoint, which runs its own web searches, fetches pages, and synthesizes one cited answer. This server fills exactly that gap. It's meant to run alongside the official one, not replace it.

The three tools

The Agent API is asynchronous under the hood (see Configuration for why that matters), so this server exposes it as one lifecycle, not one call:

Full parameters

`perplexity_agent`

`perplexity_agent_result`

`perplexity_agent_cancel`

One deliberate asymmetry, visible in tools/list: perplexity_agent's readOnlyHint annotation is false, even though it never touches your local machine — it creates real, billable, cancellable state on Perplexity's servers, and MCP clients use that hint to decide whether a call needs your approval before running. perplexity_agent_cancel carries destructiveHint: true, honestly: it ends a run, and Perplexity reports no usage at all for cancelled runs, so this tool cannot tell you whether cancelling changed your bill (see Security).

Install — Path A: single file

The whole point of this project is that you can read the one file that will hold your API key before you trust it with one. Do that first: download perplexity_agent_mcp.py and read it top to bottom.

Then check your interpreter. Stock macOS ships Python 3.9.6 at /usr/bin/python3 (confirmed on a current macOS install) — below this server's 3.10 floor. It will refuse to start and say why rather than fail obscurely, but you still want a real 3.10+ python3 (Homebrew, python.org, or uv python install all provide one):

python3 --version   # must be >= 3.10

which python3 # note this path for the config below

Point your MCP client at the absolute paths of both the interpreter and the file:

{

"mcpServers": { "perplexity-agent": { "command": "/absolute/path/to/python3", "args": ["/absolute/path/to/perplexity_agent_mcp.py"], "env": { "PERPLEXITY_API_KEY": "pplx-…" } } } }

Use absolute paths for both — the same reason Path B insists on one below applies here too: a GUI app's PATH is not your shell's PATH, and a bare "command": "python3" can quietly resolve to that too-old system interpreter instead of the one you meant. On macOS, Claude Desktop's config file lives at ~/Library/Application Support/Claude/claude_desktop_config.json.

Trust chain: Python standard library, plus Perplexity. Nothing else.

Install — Path B: uvx from PyPI

One JSON snippet, nothing to download by hand. uv fetches and runs the published package each time your MCP client starts the server.

{

"mcpServers": { "perplexity-agent": { "command": "/absolute/path/to/uvx", "args": ["perplexity-agent-mcp"], "env": { "PERPLEXITY_API_KEY": "pplx-…" } } } }

Two things worth getting right, each the difference between a working config and a support thread:

Use an absolute path to `uvx`. macOS GUI apps — Claude Desktop launched from Finder or Spotlight, not a terminal — do not inherit your shell's PATH. If the config above says "command": "uvx", Claude Desktop very likely can't find it and fails with spawn uvx ENOENT. Run which uvx in your terminal and paste the absolute path it prints into command instead.

Pin the version if you want reproducibility. "args": ["perplexity-agent-mcp@0.4.0"] holds you on one release. Unpinned, uv resolves the newest *published release* on every restart — which is a materially different risk from tracking a branch: releases are immutable, tagged, and go through the same CI as everything else. Pin if you would rather review each upgrade; leave it off if you would rather get fixes automatically. Either is defensible, which is why this is not a warning.

Also: a plugin for llm

The same Perplexity Agent client, exposed as a model for Simon Willison's llm CLI. Optional — the MCP server never imports it and keeps its zero dependencies either way.

llm install llm-perplexity-agent

llm keys set perplexity # skip if you already set this for llm-perplexity llm -m perplexity-agent 'What changed in MCP 2026-07-28?'

Options mirror the MCP tool:

llm -m perplexity-agent -o preset xhigh -o recency week 'Latest on X'

llm -m perplexity-agent -o domains 'nasa.gov,-reddit.com' 'Artemis status' llm -m perplexity-agent -o timeout 600 'Something genuinely deep'

Poll progress goes to stderr, so the answer pipes cleanly:

$ llm -m perplexity-agent 'What is MCP?' > answer.md

[perplexity-agent] status queued after 1s; no intermediate results yet [perplexity-agent] status in_progress after 3s; 10 search result(s) gathered

Why not just point `llm` at the MCP server? llm has no MCP support — simonw/llm#696 has been open since January 2025. Third-party bridges exist, but the maintained ones pull in the full MCP SDK to talk to a server that deliberately has no dependencies. And the existing llm-perplexity plugin wraps the older Sonar chat models, not the Agent API — the same gap this project fills for MCP.

One deliberate difference from the MCP server: spotlighting is off by default here. In MCP the answer goes straight into a model that is holding tools, so injected instructions could cause actions, and the wrapper is essential. On the command line the answer goes to a terminal for a human to read, and llm runs no tool loop by default — so the realistic risk is a manipulated summary if you pipe it into another model, not a hijacked agent. Turn it on with -o spotlight true when the output is headed somewhere that matters:

llm -m perplexity-agent -o spotlight true 'Research X' | llm -m gpt-5 'Summarise'

Trust chain: Path A vs Path B

These are not two equally convenient ways to install the same thing. Path B has a strictly larger trust surface than Path A — full stop; that's not a knock on Path B, it's the trade you make for not downloading anything by hand.

Both paths ship *the same bytes* — flit_core copies the one .py file into a wheel; nothing is generated, bundled, or vendored in between. Reading the file audits both.

Configuration

Why 55

Claude Desktop enforces a tool-call timeout of 60 seconds that its users cannot configure — no setting, no environment variable, nothing in the UI. A synchronous MCP call that runs longer simply dies from the client's point of view, while Perplexity keeps working — and billing — server-side regardless. 55 leaves this server's own submit-then-poll round trip a 5-second margin inside that hard ceiling.

If your client isn't Claude Desktop, raise it — there's no reason to hand back a response_id early if your client is happy to keep waiting:

"env": { "PERPLEXITY_API_KEY": "pplx-…", "PERPLEXITY_AGENT_WAIT_SECONDS": "300" }

300 is what we recommend for Claude Code, VS Code, and Cursor IDE — see why in the table below. An unset, empty, non-numeric, zero, or negative value silently falls back to 55; a valid positive value is capped at 1800 (30 minutes) so a stray extra zero can't hang a call indefinitely. perplexity_agent_result's own wait_seconds parameter advertises this same ceiling as its declared maximum in tools/list — but sending it a larger value anyway doesn't get rejected, it gets silently clamped to the ceiling.

No MCP client publishes Claude Desktop's figure anywhere; we obtained it by reverse-engineering the installed app (v1.24012.1) — its bundled TypeScript SDK defaults DEFAULT_REQUEST_TIMEOUT_MSEC to 60000ms, and Claude Desktop calls callTool() without overriding it. The rest of this table comes from each project's own docs or source, with confidence noted where it's shaky:

|