Connect Perplexity to Claude Code
Ask a question and get an answer with the sources it came from, synchronously or as a queued job. Add Toolspoke to Claude Code once and it can use 11 Perplexity actions. Your Perplexity credential stays in Toolspoke, and you choose which actions Claude Code may call.
Set it up in Claude Code
Three steps, the first one once for every toolkit you will ever add.
Add Toolspoke to Claude Code
Run it in your project, then /mcp to sign in
claude mcp add --transport http toolspoke https://toolspoke.com/mcpThe sign-in opens in your browser, and Toolspoke asks you to approve it.
Install Perplexity and connect it
Add Perplexity to a project in your Toolspoke workspace.
API key. You provide it once, when you install the connector. Toolspoke encrypts it at rest and decrypts it only for the length of a single call, and the gateway attaches it to the outbound request itself, so it is never part of the arguments an agent sends.
- API key
- perplexity.ai → Settings → API → API Keys. Every operation here except list_models is billed per request and per token, so give this key its own budget if the account allows it.
Choose what Claude Code may do
All 11 actions start on. Switch off any of the 4 actions that change something in Perplexity, and Claude Code gets a refusal if it tries.
What you can ask Claude Code for
A few of the Perplexity actions that only read, so they are safe to try first.
- List the models this key can reach, in OpenAI list format
- Check a job started by create_async_completion and read its answer
- List the async jobs this key has submitted, with their statuses
- Search the web and get ranked results with page content, and no written answer
What Claude Code can do in Perplexity
7 actions read and 4 write.
Reads
List models
List the models this key can reach, in OpenAI list format. Free, creates nothing, and needs no arguments, which is why it is the connection test. Read one caveat before trusting it as a catalogue: Perplexity documents this endpoint as the roster for the Agent API, the ids it returns look like "anthropic/claude-…" and "openai/gpt-…", so it does not enumerate the Sonar models that chat_completion takes. For those, the names in circulation are sonar, sonar-pro, sonar-reasoning-pro and sonar-deep-research, and this connector deliberately hard-codes none of them, because the roster moves faster than a file in a repository: sonar-reasoning was removed in December 2025 and any enum written before then is now wrong.
Get async completion
Check a job started by create_async_completion and read its answer. Free, polling is not billed; the work already queued is. Poll every few seconds and back off; a sonar-deep-research job can take several minutes. A completed job carries the same shape chat_completion returns, including the citations and the token usage the bill was computed from. The answer is built from other people's pages, so the payload is kept out of the audit log.
List async completions
List the async jobs this key has submitted, with their statuses. Free. The reason to call it is finding a job whose id was lost, a deep-research submission costs real money, and looking for it here is always better than sending it again. Each record carries the request that started it and, once finished, the answer, so the payload is kept out of the audit log.
Search
Search the web and get ranked results with page content, and no written answer. A flat $5 per thousand requests with no token charge, which makes it the cheapest thing here by a wide margin and the right call whenever an agent wants sources it will read itself rather than a paragraph Perplexity wrote. `query` takes a string or a list of strings, and a list runs several searches in one request. Bound the payload with `max_tokens_per_page` rather than `search_context_size`, the two are alternatives and Perplexity asks that you send one or the other, not both. The results are pages other people wrote, so the payload is kept out of the audit log, and the query is prose the caller wrote, so it is kept out too.
Get agent response
Read an agent response by id, the one to poll after create_agent_response with `background: true`. Free; the run already in flight is what costs. Poll every few seconds and back off. The completed response carries the answer, the steps the agent took and its token usage. Built from other people's pages, so the payload is kept out of the audit log.
List agent files
List the files an agent run produced, charts, spreadsheets, documents written in its sandbox, with their ids and names. Free. Downloading the bytes is a separate endpoint this connector does not declare, because the gateway returns JSON and a binary body has nowhere to go here; the ids are what a client that can fetch them needs. Filenames describe whatever the agent was asked to make, so the payload is kept out of the audit log.
Create embeddings
Turn text into vectors with Perplexity's own embedding models. A read because it creates nothing and stores nothing, it returns numbers, but it is billed per token, so batching is what keeps it cheap: up to 512 texts in one request, each under 32,000 tokens and 120,000 tokens across the whole call. `dimensions` shortens the vectors (Matryoshka truncation) when a smaller index is worth more than the last few points of accuracy: 128 to 1024 for pplx-embed-v1-0.6b, 128 to 2560 for pplx-embed-v1-4b. Both sides are withheld from the audit log: the input is somebody's text and the output is a very large array derived from it.
Writes
Chat completion
Ask Perplexity a question and get a written answer with the citations behind it. This is the operation the product exists for and the one that costs money, which is why it is a write. Billed twice: per token, $1 in and out for sonar, $3 and $15 for sonar-pro, $2 and $8 for sonar-reasoning-pro, $2 and $8 plus citation and reasoning token charges for sonar-deep-research, and per request, at $5 to $12 per thousand for sonar and $6 to $14 for the pro models depending on `web_search_options.search_context_size`, which defaults to low. Leave it low unless the answer is genuinely thin; raising it roughly doubles the per-request fee. `model` is a plain string with no list hard-coded here; sonar is the cheap default, sonar-pro answers harder questions, sonar-deep-research runs for minutes and belongs in create_async_completion rather than this blocking call. Narrow the sources with `search_domain_filter` and `search_recency_filter` before reaching for a bigger model, it is cheaper and usually more accurate. The citations come back on the response, and an answer whose citations do not support it is one to distrust. Streaming is not offered; the gateway returns whole responses. Prompts are prose the caller wrote and the answer is built from other people's pages, so neither is written to the audit log.
Create async completion
Queue a question instead of waiting for it. Returns a `request_id` and a status, and get_async_completion is what eventually carries the answer. Use this for sonar-deep-research, which routinely runs for minutes and will time out a blocking call. Priced exactly like chat_completion, the queue is free, the work is not, so read that operation's description for what a call costs before choosing a model and a context size. `idempotency_key` is worth setting: a submission that times out ambiguously can then be retried without paying for the same research twice, which is a real risk on a job that costs dollars rather than cents. Prompts are prose the caller wrote, so they are kept out of the audit log, and so is the response, which echoes the request back.
Create agent response
Run Perplexity's agent, which chooses a model, searches, reads and can use tools across several steps. More capable than chat_completion and more expensive, because it may run many searches and many model turns for one request; the bill is the sum of those, and `max_steps` is the only ceiling this connector offers on it, set it. Either `model` (as "provider/model", e.g. "anthropic/claude-sonnet-4-6") or `preset` (fast, low, medium, high, xhigh) has to be given; list_models is the roster for the `model` form, which is the one thing that endpoint is actually authoritative about. `max_output_tokens` is required when the model is an Anthropic one, and omitting it there is a 400 that says so. Set `background: true` to have it queued rather than answered in the same call, then poll get_agent_response. Instructions are prose the caller wrote and the answer is built from other people's pages, so neither is written to the audit log.
Cancel agent response
Stop an agent run that is still going, so it stops spending. Free to call, and the only lever this connector offers on a background run that is taking far longer than expected. This destroys nothing recoverable: a cancelled run has produced no final answer to lose, and its record stays readable through get_agent_response. Work already done is still billed, so this caps a run rather than refunding it. The response is the run record, which carries the question it was given.
Perplexity in Claude Code: questions
Does Claude Code see my Perplexity credential?
No. The credential is stored encrypted in Toolspoke, and the gateway adds it to each call. Claude Code only ever talks to Toolspoke, and the dashboard shows the last four characters of the credential and nothing more.
Can I stop Claude Code from changing things in Perplexity?
Yes. Each of the 11 actions can be switched off for a project. Turn off the 4 that change something and Claude Code can only read.
Will 11 actions crowd Claude Code's context?
No. Toolspoke shows Claude Code five bridge tools, plus a guide where a toolkit has one, and Claude Code searches for the Perplexity action it needs when it needs it. Adding more toolkits does not add more tools to its list.
Can I add it once for every project?
Yes. Add --scope user to the command and Claude Code keeps Toolspoke in every project on this machine. Without it, the server is added to the project you ran the command in.
What does it cost?
Tool calls are free on every plan, and a Perplexity call does not run in a sandbox, so it bills nothing.
Perplexity in your other apps
Try Perplexity in Claude Code
Free to start, and tool calls cost nothing on any plan.