Perplexity Agent

perplexity-agent-mcp

Perplexity の Agent API に対応する、単一ファイルで動作し、サードパーティー依存関係がない MCP サーバーです。引用付きの複数ステップにわたる Web リサーチ機能を、stdio 経由で任意の MCP クライアントに提供します。

Python の標準ライブラリのみを使用します。MCP SDK や HTTP ライブラリは不要で、ビルド時にコードが生成されることもありません。perplexity_agent_mcp.py が API キーを保持し、ユーザーに代わってネットワークと通信するため、コードを読めるように書かれています。コメントを含めて 1,774 行です。以下のどちらのインストール方法でも、まったく同じファイルが提供されます。どちらを選ぶかによって変わるのは、ディスクへの配置をどれだけ多くの第三者に任せるかであり、実際に実行される内容ではありません。

背景情報： perplexity-agent-mcp：Perplexity の Agent API に対応するオープンソース MCP サーバー — このプロジェクトが存在する理由、Agent API が Sonar と異なる点、そして開発を通じて明らかになったことを解説します。

このプロジェクトの目的

Perplexity 公式の @perplexity-ai/mcp-server は、Sonar チャットモデルと Search API をラップしています。Perplexity の複数ステップにわたるツール利用型リサーチエンドポイントである Agent API（POST /v1/agent）には対応していません。この API は独自に Web 検索を実行し、ページを取得して、引用付きの回答を 1 つにまとめます。このサーバーは、まさにその不足を補います。公式サーバーを置き換えるのではなく、併用することを想定しています。

3 つのツール

Agent API は内部的には非同期です（その理由については設定を参照してください）。そのため、このサーバーは API を単一の呼び出しではなく、一連のライフサイクルとして公開します。

ツール	機能	使用するタイミング
perplexity_agent	調査を開始します。デフォルトでは、回答の準備ができるまで処理をブロックし、情報源を明示した統合テキストを返します。	あらゆる調査の質問で、通常の最初の入口として使用します。
perplexity_agent_result	以前に開始した実行の結果を取得します。1 回だけ進捗を確認するか、結果が出るまで処理をブロックして待機します。	perplexity_agent が回答の代わりに response_id を返した場合に使用します（待機時間の上限に達した場合、または wait: false を指定した場合です）。
perplexity_agent_cancel	不要になった実行を停止するよう Perplexity に要求します。	wait: false で開始した処理の回答が不要になった場合に使用します。

すべてのパラメーター

perplexity_agent

パラメーター	型	デフォルト	備考
query	string	(必須)	調査の質問です。
preset	string	medium	fast、low、medium、high、xhigh、wide-research のいずれかです。クライアント側では検証されない任意の文字列のため、Perplexity が明日プリセットを追加しても、このサーバーを更新せずに使用できます。
recency	string	(なし)	hour、day、week、month、year のいずれかです。
domains	string[]	(なし)	最大 20 個のドメインを指定できます。エントリーの先頭に - を付けると、そのドメインを除外します。許可リストと拒否リストを同時に指定することはできません。
wait	boolean	true	完了までブロックするか、すぐに response_id を返して、複数の詳細なクエリを並行して実行できるようにします。

perplexity_agent_result

パラメーター	型	デフォルト	備考
response_id	string	(必須)	perplexity_agent から取得します。
wait_seconds	integer	0	0 の場合は 1 回確認してすぐに返します。値を大きくすると処理をブロックして待機しますが、拒否されるのではなく、このサーバーに設定された待機時間の上限まで暗黙的に 制限 されます（設定を参照してください）。

perplexity_agent_cancel

パラメーター	型	デフォルト	備考
response_id	string	(必須)	perplexity_agent から取得します。

tools/list で確認できる意図的な非対称性が 1 つあります。perplexity_agent の readOnlyHint アノテーションは false です。ローカルマシンには一切アクセスしませんが、Perplexity のサーバー上に実際に課金対象となる、キャンセル可能な状態を作成するためです。MCP クライアントはこのヒントを使って、実行前に呼び出しの承認が必要かどうかを判断します。perplexity_agent_cancel には、実態に即して destructiveHint: true が設定されています。実行を終了し、キャンセルされた実行について Perplexity は使用状況を一切報告しないため、このツールではキャンセルによって請求額が変わったかどうかを確認できません（セキュリティを参照してください）。

インストール — 方法 A：単一ファイル

このプロジェクトの主な目的は、API キーを預ける前に、そのキーを扱う 1 つのファイルを読めることです。まず perplexity_agent_mcp.py をダウンロードし、最初から最後まで読んでください。

次に、インタープリターを確認します。標準の macOS に付属する /usr/bin/python3 は Python 3.9.6 です（現行の macOS インストールで確認済み）。このバージョンは、このサーバーの最低要件である 3.10 を下回っています。サーバーは起動を拒否して理由を説明するため、原因不明のエラーにはなりませんが、実際に使える 3.10 以降の python3 が必要です（Homebrew、python.org、uv python install でインストールできます）。

python3 --version   # must be >= 3.10
which python3       # note this path for the config below

MCP クライアントには、インタープリターとファイルの両方について絶対パスを指定してください。

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

どちらにも絶対パスを使用してください。以下で方法 B が絶対パスを求めているのと同じ理由です。GUI アプリの PATH はシェルの PATH とは異なり、"command": "python3" のように指定すると、意図したものではなく、バージョンが古すぎるシステムのインタープリターがひそかに選ばれる可能性があります。macOS では、Claude Desktop の設定ファイルは ~/Library/Application Support/Claude/claude_desktop_config.json にあります。

信頼の連鎖：Python 標準ライブラリと Perplexity のみです。

インストール — パス B：PyPI からの uvx

JSON スニペットを 1 つ設定するだけで、手動でダウンロードするものはありません。MCP クライアントがサーバーを起動するたびに、uv が公開済みパッケージを取得して実行します。

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

正しく設定しておくべき点が 2 つあります。どちらも、動作する設定とサポートへの問い合わせを分けるポイントです。

uvx には絶対パスを指定してください。 macOS の GUI アプリ（ターミナルではなく Finder や Spotlight から起動した Claude Desktop）は、シェルの PATH を引き継ぎません。上記の設定で "command": "uvx" となっていると、Claude Desktop は uvx を見つけられず、spawn uvx ENOENT で失敗する可能性が非常に高いです。ターミナルで which uvx を実行し、表示された絶対パスを command に貼り付けてください。

再現性を確保したい場合は、バージョンを固定してください。 "args": ["[email protected]"] と指定すると、1 つのリリースを使い続けます。バージョンを固定しない場合、再起動のたびに uv が最新の 公開リリース を解決します。これは、ブランチを追跡する場合とはリスクが大きく異なります。リリースは変更されず、タグ付けされ、ほかのすべてと同じ CI を通過します。アップグレードごとに確認したい場合は固定し、修正を自動で受け取りたい場合は固定しないでください。どちらも妥当な選択なので、警告にはしていません。

こちらもご覧ください：llm 用プラグイン

Simon Willison の llm CLI で、同じ Perplexity Agent クライアントをモデルとして利用できます。これはオプションです。MCP サーバーがこれをインポートすることはなく、どちらの場合も依存関係はゼロのままです。

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?'

オプションは MCP ツールと同じです。

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'

進行状況は stderr に出力されるため、回答をそのままパイプに渡せます。

$ 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

なぜ llm から MCP サーバーを直接指定しないのですか？ llm は MCP に対応していません。 simonw/llm#696 は、2025 年 1 月から未解決のままです。サードパーティ製のブリッジもありますが、メンテナンスされているものは、意図的に依存関係を持たないサーバーと通信するために、MCP SDK 全体を取り込みます。また、既存の llm-perplexity プラグインは、Agent API ではなく古い Sonar チャットモデルをラップしています。これは、このプロジェクトが MCP に対して解消するのと同じギャップです。

MCP サーバーとの意図的な違いが 1 つあります。ここでは、デフォルトでスポットライティングが無効です。 MCP では、回答がツールを扱うモデルに直接渡されるため、注入された指示によってアクションが実行される可能性があり、ラッパーは不可欠です。一方、コマンドラインでは回答は人が読むターミナルに出力され、llm はデフォルトではツールループを実行しません。そのため、現実的なリスクはエージェントの乗っ取りではなく、別のモデルにパイプした場合に要約が操作されることです。重要な用途に出力を渡す場合は、-o spotlight true で有効にしてください。

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

信頼の連鎖：パス A とパス B

この 2 つは、同じものをインストールするための、同じくらい手軽な方法ではありません。パス B の信頼対象はパス A より明らかに広くなります。これはパス B を否定するものではなく、手動でダウンロードする手間を省くために受け入れるトレードオフです。

	パス A：単一ファイル	パス B：uvx
信頼する対象	Python 標準ライブラリ、Perplexity	Python 標準ライブラリ、Perplexity、さらに uv、flit_core、GitHub（取得時。バージョンを固定しない限り、再起動のたびに取得）
実行されるもの	読んだとおりのバイト列	固定したタグから flit_core がビルドする wheel。同じソースですが、取得とビルドを代行します
最適な用途	監査可能性を最大限に高めたい場合	利便性を最大限に高めたい場合

どちらのパスも 同じバイト列 を配布します。flit_core は 1 つの .py ファイルを wheel にコピーするだけで、その間に何かが生成、バンドル、ベンダー化されることはありません。このファイルを読めば、どちらのパスも監査できます。

設定

変数	必須	デフォルト	説明
PERPLEXITY_API_KEY	はい	—	Perplexity API キーです。未設定または空の場合は、クラッシュするのではなく、変数名を示す明確なツールエラーが返ります。
PERPLEXITY_AGENT_WAIT_SECONDS	いいえ	55	ブロッキングするツール呼び出しが回答の代わりに response_id を返すまでに待機できる秒数です。

55である理由

Claude Desktopでは、ユーザーが設定できないツール呼び出しタイムアウトが60秒に設定されています。設定項目も、環境変数も、UI上の設定もありません。同期MCP呼び出しがそれより長く実行されると、クライアント側からは失敗したように見えますが、Perplexityはサーバー側で処理を続け、課金も続きます。55なら、このサーバーの送信後のポーリング往復に、厳格な上限まで5秒の余裕を持たせられます。

Claude Desktop以外のクライアントをお使いの場合は、値を大きくしてください。クライアントが待ち続けても問題ないなら、response_idを早めに返す理由はありません。

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

Claude Code、VS Code、Cursor IDEには300をおすすめします。その理由は、下の表をご覧ください。値が未設定、空、数値以外、ゼロ、または負の場合は、エラーを表示せず55にフォールバックします。有効な正の値は最大1800（30分）に制限されるため、余分なゼロを誤って入力しても、呼び出しがいつまでも終了しないことはありません。perplexity_agent_resultのwait_secondsパラメーターも、tools/listで宣言される最大値としてこの同じ上限を示しています。ただし、それを超える値を送信しても拒否されるわけではなく、エラーを表示せず上限に切り詰められます。

MCPクライアントは、Claude Desktopのタイムアウト値を公開していません。この値は、インストール済みアプリ（v1.24012.1）をリバースエンジニアリングして確認しました。アプリに同梱されたTypeScript SDKでは、DEFAULT_REQUEST_TIMEOUT_MSECのデフォルト値が60000msで、Claude Desktopは上書きせずにcallTool()を呼び出しています。この表のその他の情報は、各プロジェクトのドキュメントまたはソースに基づいています。確度が低い情報にはその旨を記載しています。

クライアント	ツール呼び出しのタイムアウト	ユーザーが設定可能？	進捗トークンを送信する？
Claude Desktop	60秒	いいえ	一切送信しない
Claude Code（stdio）	実時間で約28時間、アイドル時は30分	はい（MCP_TOOL_TIMEOUT、サーバーごとのtimeout、アイドル時の変数）	はい — 2分を超える呼び出しは自動的にバックグラウンドで実行
Cursor（ACP/CLI）	60秒	いいえ	—
Cursor（IDE）	約60分（スタッフによるフォーラム投稿1件に基づく、未検証）	いいえ	—
VS Code / GitHub Copilot	なし — 無期限に待機	該当なし	はい。UIに表示
MCP TypeScript SDK	60秒	リクエストごと	インテグレーターが有効にした場合のみ
MCP Python SDK	なし	はい	未実装

進捗通知を送っても、Claude Desktopの問題は解決しません。仕様では、進捗が届いたときにクライアントがタイムアウトの計測をリセットできますが、そもそもクライアントがprogressTokenを指定している場合に限られます。Claude Desktopはこれを一切指定しません。このサーバーのnotifications/progress対応は、利用可能なクライアントにとってはメリットしかなく、Claude Desktopでは何も起こりません。

プロトコルのリビジョン

このサーバーは、MCP の両方の世代に対応しており、送信内容からどちらを使うかを判断します。設定は不要で、間違えることもありません。

リビジョン	世代	リクエストでの指定方法
2026-07-28	モダン — ステートレス、ハンドシェイクなし	すべてのリクエストの _meta.io.modelcontextprotocol/protocolVersion
2025-11-25	レガシー — initialize ハンドシェイク	initialize の呼び出し、または単に _meta を含めない
2025-06-18、2025-03-26	レガシー	initialize を通じてネゴシエーション

2026-07-28 は2026-07-28 に正式リリースされ、initialize／notifications/initialized のハンドシェイクを完全に廃止します。これによりプロトコルはステートレスになり、すべてのリクエストに独自のプロトコルバージョンとクライアントの機能が含まれ、サーバーは server/discover を実装する必要があります。これは MCP の歴史上、最大の破壊的変更です。

セットアップを変更する必要はありません。 レガシークライアントから見た動作は、これまでとバイト単位で同一です。これは意図ではなく、完全一致テストによって保証されています。執筆時点では、2026-07-28 への対応を一般公開した MCP クライアントはありません。そのため実際には、すべてのクライアントが引き続きレガシーの経路を使います。モダンな経路を用意しているのは、対応クライアントが登場した際に、このサーバーの対応を待たずに済むようにするためです。

このサーバーをテストする際に知っておくとよい動作が 2 つあります。

• server/discover は _meta がなくても応答します。 stdio では、これが指定された後方互換性プローブであり、クライアントは応答を読み取って、このサーバーがどちらの世代かを判断します。ここでエラーが返ると、クライアントはこのサーバーを「レガシーサーバー」として恒久的に扱います。
• 対応していないリビジョンを指定したモダンリクエストには、再試行時に指定すべきリビジョンの一覧を含む -32022 が返ります。 これは、バージョンネゴシエーションでエラーを返さず、代わりにダウングレードする initialize とは意図的に逆の動作です。この 2 つのルールは異なるコード経路に適用されるため、矛盾しません。

プリセット

preset はリサーチの深さを指定します。Perplexity 側でも自由な文字列として扱われており、API リファレンスでは列挙型ではなく単なる string として定義されています。そのため、このサーバーでも制約を設けていません。この README の執筆後に Perplexity が追加したプリセットも、変更なしで使えます。以下は、現在ドキュメント化されているプリセットを、おおむね浅いものから深いものの順に並べたものです。

プリセット	Perplexity が示す用途
fast	最小限のレイテンシで、事実をすばやく調べる
low	最新情報を使ったバランスのよいリサーチ
medium（デフォルト）	複数の情報源を対象とした、複数ステップのリサーチ
high	網羅的な調査
xhigh	範囲を限定しないエージェント型リサーチ
wide-research	根拠に裏付けられた大規模な情報源コレクションの構築

確かな数値としてわかっているのは、medium の 1 回の実行（3 つの情報源を比較するクエリ）で、12.5 秒、$0.039 かかったことです。これは 1 回のサンプルであり、ベンチマークではありません。質問の内容や、より深いプリセットによって結果は変わり、おそらく大きく変動します。このサーバーは、プリセットにかかわらず、常に Perplexity のバックグラウンドモードでリクエストを送信します。リサーチの実行中ずっとソケットを開いたままにするのではなく、ポーリングしてください。wide-research にも、このモードが必要です。

最新かつ正式な一覧については、Perplexity のプリセットガイドをご覧ください。

セルフテスト

API キーは不要です。これらの呼び出しはどれもネットワークに接続しません。このサーバーは2 つのプロトコルリビジョンに対応しているため、呼び出しは 2 つあり、それぞれ 1 つずつをテストします。

旧形式（2025-11-25）、ハンドシェイク時代：

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"manual","version":"1"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | python3 perplexity_agent_mcp.py

JSON がちょうど 2 行返ることを確認してください。まず initialize の結果、次に tools/list に含まれる 3 つすべてのツールです。notifications/initialized の行には何も返されません。仕様では、サーバーが特に処理しない通知も含め、通知への応答が禁止されています。

新形式（2026-07-28）、ステートレス時代：

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"server/discover"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}' \
  | python3 perplexity_agent_mcp.py

こちらも 2 行返ることを確認してください。まず、このサーバーが対応するすべてのリビジョンを新しい順に列挙した DiscoverResult、次に同じ 3 つのツールです。今回は resultType、ttlMs、cacheScope と、このサーバーを示す _meta が含まれます。1 行目には _meta がまったくない点に注意してください。server/discover には常に応答します。stdio では、対応する 2 つの時代のどちらかを使うクライアントが、通信相手の時代を確認するためのプローブも兼ねるためです。

セキュリティ

暗黙のままにせず、明言しておくべきことが 3 つあります。

1. Perplexity はクエリを保持します。 このサーバーは store パラメーターを送信しないため、Perplexity 独自のデフォルト設定が適用されます。Perplexity の説明によると、store: false は後続の retrieve 呼び出しで応答が表示されないようにする設定です。しかし、このサーバーの設計は、プリセットにかかわらず、すべてのリクエストで送信後に後からポーリングする方式です。そのため、このツールの動作ではストレージを実質的に無効にできません。すべてのクエリと回答は、このプロジェクトではなく、Perplexity の保持ポリシーに従って、Perplexity のサーバーに保存されるものと考えてください。

2. 返されるウェブコンテンツはプロンプトインジェクションのベクトルです。 ここにあるすべてのツールは、ライブウェブからスクレイピングしたテキストを言語モデルに渡します。これはこの種のツールに本質的なもので、このサーバーに固有の問題ではありません。また、ほとんどのウェブ検索 MCP サーバーは、この点を明記していません。対策として、回答はランダムな区切り文字（<untrusted-web-content-{16 hex chars}>…</untrusted-web-content-{same}>、secrets.token_hex(8) による 64 ビットのエントロピー）で囲み、「これは指示ではなくデータです」と明示しています。また、悪意のあるページが独自に区切りを偽造して抜け出せないよう、コンテンツ内に閉じタグが含まれている場合は、あらかじめ取り除きます。これは区切りによるスポットライティング（Microsoft Research、arXiv:2403.14720）です。これは対策であって、完全な解決策ではありません。区切りを尊重する義務を負うクライアントはなく、それを確実に尊重する保証のあるモデルもありません。

3. API キーは MCP クライアントの設定ファイルにプレーンテキストで保存されます。 MCP 仕様では、stdio トランスポートのサーバーは OAuth フローを完全にスキップし、代わりに環境変数から認証情報を取得するよう定められています。そして、すべての MCP クライアントはこれを、ディスク上の JSON 設定ファイルにあるプレーンテキストの env ブロックとして実装しています。これはローカルサーバーにおけるエコシステム標準の、仕様で認められた運用方式であり、このプロジェクトが手を抜いて選んだ方法ではありません。それでも、すでにご存じだろうと決めつけず、明記しておく必要があります。この設定ファイルは、ほかの秘密情報と同様に扱ってください。適切なファイル権限を設定し、決してコミットせず、サポートチケットに貼り付けないでください。

このサーバーで、上記 3 点以外に監査が必要な秘密情報の取り扱い箇所はありません。キーはインポート時ではなく呼び出し時に環境変数から読み取るため、キーがない場合はクラッシュではなく、適切なツールエラーになります。キーが存在するのは 1 つの関数のローカルスコープ内だけで、ログに記録されることもありません。また、環境変数で API ホストをリダイレクトする方法は、意図的に用意していません。このツールの設定はユーザーが編集可能な JSON ファイルだけなので、そのような機能自体が情報流出経路になり得るためです。

開発

インストール手順はありません。それがこのプロジェクトの狙いです。

git clone https://github.com/zalez/perplexity-agent-mcp.git
cd perplexity-agent-mcp
python3 -m unittest discover

テストは190件で、標準ライブラリのみを使用します。tests/fake_perplexity.py は http.server 上で Perplexity の偽物をプロセス内で実行するため、実際のサービスが呼び出されることはありません。

コミットする前に、Git フックを一度インストールしてください。その後は自動的に実行されます。

uv tool install pre-commit   # or: pip install pre-commit / pipx install pre-commit
pre-commit install
pre-commit run --all-files

フックは18個あり、ファイルの整合性チェック、ruff と mypy --strict、シークレットと GitHub Actions のセキュリティスキャンを行う gitleaks と zizmor、codespell、そしてテストスイート全体が含まれます。CI では同じフック一式（ci.yml を参照）に加え、Python 3.10～3.14 でのマトリックステストと、wheel をビルドしてクリーンな環境にインストールし、実際のパイプ経由でコンソールスクリプトを実行するパッケージングジョブが実行されます。ビルドの成功だけでは、エントリーポイントが機能することの証明にはなりません。

詳細

• 設計仕様 — 各決定とその根拠、当初の概要で誤っていた点、実際の検証結果。
• 2世代に対応するMCP — このサーバーが2つのプロトコルリビジョンを同時に扱う理由と、リクエストにどちらが適用されるかを決める3つの優先規則。
• ブログ記事 — このプロジェクトの背景にあるストーリー。
• SECURITY.md — 脅威モデルと、プロンプトインジェクション対策でできること・できないことについての率直な説明。

ライセンス

BSD-3-Clause。Copyright (c) 2026, Constantin Gonzalez。LICENSE を参照してください。