perplexity-agent-mcp

<!-- mcp-name: io.github.zalez/perplexity-agent-mcp -->

# perplexity-agent-mcp

[![CI](https://github.com/zalez/perplexity-agent-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/zalez/perplexity-agent-mcp/actions/workflows/ci.yml)

A single-file, zero-third-party-dependency [MCP](https://modelcontextprotocol.io/) server for Perplexity's [Agent API](https://docs.perplexity.ai/docs/agent-api/quickstart) — 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,478 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*](https://constantin.glez.de/posts/2026-07-27-perplexity-agent-mcp-open-source-mcp-server-perplexitys-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`](https://github.com/ppl-ai/modelcontextprotocol) 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](#configuration) for why that matters), so this server exposes it as one lifecycle, not one call:

| Tool | Does | Use it when |
|---|---|---|
| `perplexity_agent` | Starts a research run. By default, blocks until the answer is ready and returns synthesized, sourced text. | Your default entry point for any research question. |
| `perplexity_agent_result` | Collects a run started earlier — a one-shot progress check, or a blocking wait. | `perplexity_agent` handed back a `response_id` instead of an answer (it ran out of wait budget, or you called it with `wait: false`). |
| `perplexity_agent_cancel` | Asks Perplexity to stop a run that's no longer needed. | You started something with `wait: false` and no longer want the answer. |

<details>
<summary>Full parameters</summary>

**`perplexity_agent`**

| Param | Type | Default | Notes |
|---|---|---|---|
| `query` | string | *(required)* | The research question. |
| `preset` | string | `medium` | `fast`, `low`, `medium`, `high`, `xhigh`, `wide-research` — an open string, not validated client-side, so a preset Perplexity adds tomorrow works today without an update to this server. |
| `recency` | string | *(none)* | One of `hour`, `day`, `week`, `month`, `year`. |
| `domains` | string[] | *(none)* | Up to 20 domains. Prefix an entry with `-` to exclude it. Allowlist or denylist, not both. |
| `wait` | boolean | `true` | Block until done, or return a `response_id` immediately so you can run several deep queries in parallel. |

**`perplexity_agent_result`**

| Param | Type | Default | Notes |
|---|---|---|---|
| `response_id` | string | *(required)* | From `perplexity_agent`. |
| `wait_seconds` | integer | `0` | `0` checks once and returns immediately. A higher value blocks, but is silently **clamped** to this server's configured wait budget (see [Configuration](#configuration)) rather than rejected. |

**`perplexity_agent_cancel`**

| Param | Type | Default | Notes |
|---|---|---|---|
| `response_id` | string | *(required)* | From `perplexity_agent`. |

</details>

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](#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):

```bash
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:

```json
{
  "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.

```json
{
  "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.3.1"]` 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`](https://llm.datasette.io) CLI. Optional — the MCP server never imports
it and keeps its zero dependencies either way.

```bash
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:

```bash
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](https://github.com/simonw/llm/issues/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`](https://pypi.org/project/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:

```bash
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.

| | Path A: single file | Path B: `uvx` |
|---|---|---|
| You trust | Python standard library, Perplexity | Python standard library, Perplexity, **plus `uv`, `flit_core`, and GitHub** (at fetch time — every restart, unless pinned) |
| What runs | Exactly the bytes you read | A wheel `flit_core` builds from the tag you pinned — same source, but fetched and built on your behalf |
| Best for | Maximum auditability | Maximum convenience |

Both paths ship *the same bytes* — `flit_core` copies the one `.py` file into a wheel; nothing is gene