Perplexity Computer MCP Server

Overview

The Perplexity Computer MCP Server connects AI assistants to Perplexity Computer, a general-purpose AI agent that can complete virtually any task on your behalf. Through the Model Context Protocol, your MCP client can delegate complex, multi-step work to Computer and receive structured results.

This integration is separate from the Perplexity API MCP Server, which is focused on Perplexity’s Search and Completion APIs.

Computer can:

Search and browse the web for real-time information, including login-gated pages
Write and execute code in an interactive Linux sandbox with Python, Node, and standard Unix tools
Create documents and media including PDFs, slide decks, spreadsheets, images, and videos
Read and send emails via Gmail and Outlook, and schedule calendar events
Manage tasks across GitHub, Linear, Jira, Asana, Slack, Notion, and more
Analyze data from Snowflake, Databricks, Google Sheets, Salesforce, and other sources
Build and deploy websites to a live public URL in minutes
Connect to 400+ services through a managed connector framework with one-click OAuth

Authentication

The Computer MCP Server authenticates users via OAuth 2.0 using your Perplexity account. No API key is required. On first use, compatible MCP clients open a browser window to complete the authorization flow automatically.

Computer usage is billed against your Perplexity account credits. If your balance is insufficient, Computer returns insufficient_credits with a link to manage billing.

Installation

Step 1: Install the server

Add the Computer MCP server to your client.

claude mcp add perplexity-computer --transport http https://www.perplexity.ai/rest/computer/mcp

codex mcp add perplexity-computer --url https://www.perplexity.ai/rest/computer/mcp

Add to your mcp.json:

{
  "mcpServers": {
    "perplexity-computer": {
      "url": "https://www.perplexity.ai/rest/computer/mcp"
    }
  }
}

Add to your .vscode/mcp.json:

{
  "servers": {
    "perplexity-computer": {
      "type": "http",
      "url": "https://www.perplexity.ai/rest/computer/mcp"
    }
  }
}

Add to your ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "perplexity-computer": {
      "serverUrl": "https://www.perplexity.ai/rest/computer/mcp"
    }
  }
}

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "perplexity-computer": {
      "url": "https://www.perplexity.ai/rest/computer/mcp"
    }
  }
}

Any MCP client that supports the HTTP transport can connect using the server URL:

https://www.perplexity.ai/rest/computer/mcp

Refer to your client’s documentation for the correct configuration format.

Step 2: Authenticate with Perplexity Computer

After installation, you will be asked to authenticate with your Perplexity account, and will be directed to a browser window to complete the OAuth flow.

Perplexity OAuth screen for Computer MCP

Step 3: Start using the Computer MCP

Once authenticated, you’re ready to start delegating tasks to Perplexity Computer through your MCP client.Run a short flow to test the connection and see Computer in action:

Summarize the top 5 stories on Hacker News right now.

Then follow up in the same conversation:

Turn that into a PDF report.

Conversation Threading

Computer remembers the context from the first message and builds on it. To keep follow-up prompts in the same workflow, your MCP client must pass the thread_id from the previous response. The first call creates a new thread and returns a thread_id. Reuse that thread_id on later calls to continue the same session.

1. call_perplexity_computer(message: "Summarize the top 5 stories on Hacker News right now")
   -> { thread_id: "123e4567-e89b-12d3-a456-426614174000", event: "complete", text: "Here are today's top stories..." }

2. call_perplexity_computer(message: "Turn that into a PDF report", thread_id: "123e4567-e89b-12d3-a456-426614174000")
   -> { thread_id: "123e4567-e89b-12d3-a456-426614174000", event: "complete", text: "Here's the report.\n\n[report.pdf](https://...)" }

This also applies to interactive events. If Computer needs to connect to a service mid-task, it returns an auth_required event. After you sign in, notify_connected tells Computer, and the same request continues on the same thread:

1. call_perplexity_computer(message: "Email me a summary of my unread Slack messages")
   -> { thread_id: "123e4567-e89b-12d3-a456-426614174001", event: "auth_required", interactive: { type: "auth_required", connector: "slack", auth_url: "https://..." } }

2. notify_connected(thread_id: "123e4567-e89b-12d3-a456-426614174001", message: "Slack connected", connector: "slack")
   -> { thread_id: "123e4567-e89b-12d3-a456-426614174001", event: "complete", task_status: "working", text: "Sign-in sent. Computer is continuing this request; ..." }

3. read_thread(thread_id: "123e4567-e89b-12d3-a456-426614174001")
   -> { thread_id: "123e4567-e89b-12d3-a456-426614174001", event: "transcript", web_state: { task_status: "completed", ... }, text: "... Done! Sent the summary to your email." }

Status and Progress Updates

Computer tasks can take several minutes when they involve browsing, connector authentication, code execution, or file generation. Without MCP Tasks, the tool call waits up to two minutes for a final state or a checkpoint that needs action. If Computer is still working after that, the call returns a timeout event and the task keeps running. Use task_status for the current Computer status and event for the tool call outcome. The response also includes the thread_id for follow-up calls:

{
  "thread_id": "123e4567-e89b-12d3-a456-426614174000",
  "event": "complete",
  "task_status": "completed",
  "text": "Finished the report."
}

When Computer needs input before it can continue, the response includes an actionable event and an interactive object:

{
  "thread_id": "123e4567-e89b-12d3-a456-426614174000",
  "event": "ask_user_question",
  "text": "Which format should I use?\n1. PDF\n2. DOCX",
  "interactive": {
    "type": "ask_user_question",
    "thread_id": "123e4567-e89b-12d3-a456-426614174000",
    "respond_with_tool": "answer_question"
  }
}

Handle these checkpoints by calling the indicated follow-up tool with the same thread_id:

Event	Follow-up
`ask_user_question`	Call `answer_question` with the user’s answer.
`confirm_action`	Call `confirm_action_approve` or `confirm_action_deny`.
`auth_required`	Open the OAuth URL, then call `notify_connected` with the event’s `connector`.
`sleep`	Nothing. Computer resumes on its own at the scheduled time, shown in the result’s `wake_at`. Use `read_thread` to check on it; its `web_state.wake_at` shows the same time.
`waiting`	Call `call_perplexity_computer` with the same `thread_id` when you want to continue.

The Computer MCP server sends status updates as MCP progress notifications while a task runs. Your client must include a progress token and support progress notifications to display them. These updates are task statuses rather than token-by-token response streaming.

If the tool returns timeout, Computer has not reached a checkpoint yet and is still working. Keep the thread_id and call read_thread with it to check the task’s status, read new messages, and find any questions or confirmations waiting for an answer. Don’t call call_perplexity_computer again just to check status: that sends a new message to the task.

Clients that support MCP Tasks can run the whole request as one task instead, with no two-minute limit. See MCP Tasks.

MCP Tasks

Clients that support the MCP Tasks extension (io.modelcontextprotocol/tasks, protocol 2026-07-28) can follow a Computer request as one task. The task covers the work, questions, approvals, sign-ins, and final answer. Use tasks/get to check progress and tasks/update to answer input requests.

Start a task

Declare the extension in the capabilities attached to each request, including task methods. Include this _meta object in params, or configure your MCP SDK to supply it:

{
  "_meta": {
    "io.modelcontextprotocol/clientCapabilities": {
      "extensions": {
        "io.modelcontextprotocol/tasks": {}
      }
    }
  }
}

Call call_perplexity_computer as usual. When Computer accepts a new message, the call returns a task:

{
  "resultType": "task",
  "taskId": "123e4567-e89b-12d3-a456-426614174000.5e3b0b1d-5e34-4167-8e5a-5733d4f3695f.1792800678709",
  "status": "working",
  "statusMessage": "Computer is working on it.",
  "createdAt": "2026-10-24T00:11:18.709Z",
  "lastUpdatedAt": "2026-10-24T00:11:18.709Z",
  "ttlMs": 2592000000,
  "pollIntervalMs": 5000,
  "_meta": {
    "ai.perplexity/stopUrl": "https://www.perplexity.ai/computer/tasks/123e4567-e89b-12d3-a456-426614174000",
    "ai.perplexity/threadId": "123e4567-e89b-12d3-a456-426614174000"
  }
}

If a request cannot start, such as an invalid argument or insufficient credits, the call can return a regular tool result instead. Task creation, tasks/get, and tasks/cancel return the thread ID in _meta["ai.perplexity/threadId"]. Save this value for tools that require thread_id, including cancel_task before completion. Do not parse the task ID or Stop URL to obtain it. Call tasks/get with params.taskId set to the returned taskId. Wait for the returned pollIntervalMs between polls. Save the exact task ID without parsing it. After a disconnect, authenticate again and continue polling the same ID. A disconnect does not stop Computer. tasks/get returns resultType: "complete" because the polling request has finished. Use its status field to determine whether Computer has finished. When status is completed, the same response includes the final tool result in result. There is no separate tasks/result call. To send a follow-up, call call_perplexity_computer with the saved thread ID. The completed task also includes thread_id in result.structuredContent. Each new message starts a new task. Answers and sign-ins continue the existing task.

Task status

Status	Meaning
`working`	Computer is running, waiting on subagents, or paused until a set time.
`input_required`	Computer is waiting on the user. See Answer questions and approvals.
`completed`	The final tool result is in `result`. If Computer failed, `result.isError` is `true` and `result.structuredContent.error_code` is `computer_error`.
`cancelled`	The request was stopped.

The result of a completed task remains available after a follow-up starts another task on the thread.

Status line and steps

While a task is working or input_required, statusMessage describes the current step, scheduled wake time, or thread status. tasks/get also lists the request’s steps in _meta["ai.perplexity/steps"], oldest first, up to the last 20. Each step has the same fields as the steps in read_thread:

{
  "_meta": {
    "ai.perplexity/steps": [
      {
        "id": "step-1",
        "title": "Searching for flights to Rome",
        "type": "search_web",
        "status": "completed",
        "started_at": "2026-10-24T00:11:20Z",
        "completed_at": "2026-10-24T00:11:31Z",
        "sources": [{ "url": "https://example.com", "title": "Example" }]
      }
    ]
  }
}

A step’s status is working, input_required, completed, failed, or cancelled.

Answer questions and approvals

When the task is input_required, inputRequests contains elicitation/create requests. Use each request’s params.mode to choose between a form and a URL. For forms, build the fields from params.requestedSchema. Answer with tasks/update, using the exact keys from inputRequests:

Waiting on	Request	Your response
Questions	Form	`accept` with values that match the schema sends the answers. `decline` or `cancel` leaves the question open.
Approvals	Form with no fields	`accept` approves. `decline` denies.
Sign-ins	URL	Open the URL. The user signs in on that page and the task continues. `decline` dismisses the sign-in.
Credentials, payments, file inputs, richer forms, or credits	URL	Open the URL and complete the required action in Perplexity.

For example, if a form requests a string field named q1, send its value under that name:

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tasks/update",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/clientCapabilities": {
        "extensions": {
          "io.modelcontextprotocol/tasks": {}
        }
      }
    },
    "taskId": "123e4567-e89b-12d3-a456-426614174000.5e3b0b1d-5e34-4167-8e5a-5733d4f3695f.1792800678709",
    "inputResponses": {
      "answer:3f4c8a2e-5b1d-4e7f-9a6c-2d8e0b7f1c3a": {
        "action": "accept",
        "content": { "q1": "PDF" }
      }
    }
  }
}

Keys that are no longer waiting are ignored. tasks/update returns an acknowledgement, not the final answer. Continue polling the same task ID after an update. For URL requests, accept does not complete the action. The user must finish on the linked page. For approvals, cancel leaves the approval pending. These input responses do not stop Computer.

Cancel a task

tasks/cancel acknowledges the request but does not stop Computer or change its saved status. Its response includes _meta["ai.perplexity/stopUrl"], also available from task creation and tasks/get. To stop Computer, open that URL and select Stop, or call cancel_task with thread_id set to _meta["ai.perplexity/threadId"]. Opening the URL alone does not stop work. Both actions target the thread’s current work, including work paused for a question or approval. They do not target a historical task ID. Continue polling to confirm that the current task reports cancelled.

File Uploads

Computer can work on files you provide. To attach a file to a task, request a presigned S3 envelope with create_attachment_upload, upload the bytes directly to S3, and pass the returned URL in attachment_urls on your next tool call. The MCP server never sees the file contents, so uploads scale to large binaries without going through the worker. Each attachment can be up to 200 MB on paid plans, or 25 MB on the Free plan. Plans also limit how many files you can attach per day or week. When a limit is reached, create_attachment_upload returns an error.

Step 1: Request an upload envelope

Call create_attachment_upload with the file’s filename, mime_type, and size_bytes. The server returns a presigned S3 POST you can use for the next few minutes.

create_attachment_upload(
  filename: "report.pdf",
  mime_type: "application/pdf",
  size_bytes: 482190,
)
-> {
  attachment_url: "https://bucket.s3.amazonaws.com/uploads/<uuid>/report.pdf",
  upload_url: "https://bucket.s3.amazonaws.com",
  upload_fields: { "key": "uploads/<uuid>/report.pdf", "policy": "...", ... },
}

Step 2: POST the bytes to S3

Send an unauthenticated multipart/form-data POST to upload_url. Include every key from upload_fields as a form field, then add the file under a file part.

curl -X POST "$UPLOAD_URL" \
  -F "key=$KEY" \
  -F "policy=$POLICY" \
  -F "x-amz-signature=$SIGNATURE" \
  -F "file=@./report.pdf"

S3 returns 204 No Content on success. The file is now reachable at attachment_url.

Step 3: Reference the file in a task

Pass the attachment_url to any task tool via the attachment_urls array. You can attach files to a new task or to a follow-up on an existing thread.

call_perplexity_computer(
  message: "Summarize this report and pull out the key risks.",
  attachment_urls: ["https://bucket.s3.amazonaws.com/uploads/<uuid>/report.pdf"],
)

`create_attachment_upload`

Request a presigned S3 POST for a single file. Returns an envelope your client uses to upload bytes directly to S3.

Parameter	Type	Required	Description
`filename`	string	Yes	File name including extension (e.g. `report.pdf`).
`mime_type`	string	Yes	Content type of the file (e.g. `application/pdf`, `image/png`).
`size_bytes`	integer	Yes	File size in bytes. Must not exceed your plan’s limit (200 MB on paid plans, 25 MB on Free).

Returns:

Field	Type	Description
`attachment_url`	string	Pass this back in `attachment_urls` on a follow-up tool call.
`upload_url`	string	The S3 endpoint to POST the file to.
`upload_fields`	object	Form fields to include alongside the `file` part in the multipart POST.

Choosing a Mode or Model

If you don’t choose, Computer uses its default settings for your account. You can instead pick a mode, or a specific model and effort, when you call call_perplexity_computer.

Discover your options

Call models_list to see what you can choose. It takes no parameters and only returns options your account is allowed to use, based on your plan, region, and organization policy.

{
  "default_mode": "standard",
  "modes": [
    { "mode": "light", "model": "<model id>", "effort": "low" },
    { "mode": "standard", "model": "<model id>", "effort": "high" }
  ],
  "models": [
    {
      "id": "<model id>",
      "label": "<display name>",
      "description": "<short description>",
      "fast": false,
      "efforts": ["low", "medium", "high"],
      "default_effort": "high"
    }
  ],
  "default_model": "<model id>"
}

Field	Type	Description
`default_mode`	string or null	The mode Computer uses when you don’t choose one: `light`, `standard`, `high`, or `ultra`.
`modes`	object[]	Each mode you can choose, with the `model` and `effort` it currently runs.
`models`	object[]	Each model you can choose. Use `id` as the `model` parameter, and pick `effort` from `efforts`. `default_effort` is used when you don’t pass `effort`.
`default_model`	string or null	Your account’s default model.

Pick a mode or a model

Pass either mode, or model with an optional effort, to call_perplexity_computer:

call_perplexity_computer(message: "Plan my week", mode: "light")

call_perplexity_computer(message: "Review this contract", model: "<model id>", effort: "high")

mode and model can’t be used together.
effort requires model. If you pass model without effort, Computer uses that model’s default_effort.
Use values returned by models_list. Values that aren’t available to your account are rejected.

Fast models. Fast isn’t a separate setting. To run faster, choose a model whose fast field is true in models_list. Follow-ups. On a follow-up with a thread_id, passing mode or model switches the thread to the new settings. If you leave them out, the thread keeps its current settings.

Capabilities

Browser Control

Computer includes a full cloud browser for tasks that go beyond search. When a task requires interacting with a website, filling forms, or accessing login-gated content, Computer launches a browser session automatically.

Capability	Description
Navigation	Navigate to any URL, click elements, fill forms, and extract structured data.
Authentication	Handle multi-step login flows and authenticated sessions.
Screenshots	Take high-fidelity screenshots of any webpage.
Batch processing	Run browser tasks across dozens of URLs in parallel, collecting results into structured output.
JavaScript rendering	Access content on dynamic, JavaScript-heavy pages that aren’t available through simple HTTP requests.

Code Execution

Computer runs code in a sandboxed Linux VM with a persistent file workspace. Python, Node.js, ffmpeg, and standard Unix tools are pre-installed, and additional packages can be installed on the fly.

Capability	Description
Interactive execution	Write and execute Python or Node scripts in real time, iterating on results.
Data processing	Process CSV, JSON, Excel, PDF, images, audio, and video files.
Shell commands	Run shell commands for system operations, data processing, and automation.
Visualizations	Generate charts, plots, and data analysis outputs.
File workspace	Persistent directory where files are created, read, and managed across the session.

Connected Services

Computer connects to 400+ external services through a managed connector framework. Users authenticate once via OAuth, and Computer uses tokens securely to read data, take actions, and search across services.

Category	Services
Communication	Slack, Gmail, Outlook, Microsoft Teams
Calendar	Google Calendar, Outlook Calendar
Documents	Notion, Google Docs, Google Sheets, Dropbox, OneDrive, SharePoint, Box
Project Management	Linear, Jira, Asana, Confluence, Trello
CRM & Sales	HubSpot, Salesforce
Development	GitHub, GitLab, Vercel, Supabase
Data & Analytics	Snowflake, Databricks, Airtable, Google Sheets
Finance	Stripe, Ramp, Plaid
Research	CB Insights, PitchBook, Statista, SEC EDGAR
And more	Hundreds of additional connectors across categories

When a task requires a service that isn’t connected yet, Computer provides an OAuth link. Authenticate in your browser and the connector becomes available immediately.

Available Tools

call_perplexity_computer

Send a message to Perplexity Computer to start or continue any task. This is the primary tool you’ll use for all interactions.Best for: Starting new tasks, sending follow-up instructions, and resuming paused conversations.

answer_question

Relays answers when Computer asks for more information. Clients that support MCP elicitation can handle this within the active call.Triggered by: ask_user_question events.

confirm_action_approve / deny

Approves or denies a sensitive action like sending an email or deploying code. Clients that support MCP elicitation can handle this within the active call.Triggered by: confirm_action events.

notify_connected

Tells Computer you finished signing in to a third-party service, so the waiting request continues.Triggered by: auth_required events.

cancel_task

Stops a running Computer task.Best for: Stopping a task the user no longer wants.

read_thread

Reads a thread’s status, transcript, and any questions or sign-ins it is waiting on, without sending a message.Best for: Checking on a task after a timeout, a dropped connection, or a sleep.

models_list

Lists the modes and models you can choose for a task.Best for: Choosing a mode, model, or effort before calling call_perplexity_computer.

list_thread_assets / create_asset_download

Lists the files a thread produced and creates fresh download URLs for them.Best for: Fetching generated files after a reconnect or once an earlier link has expired.

projects_list

Lists the Projects you can access, so a conversation can start inside one.Best for: Finding the project_uuid to pass to call_perplexity_computer.

create_attachment_upload

Creates a presigned S3 upload envelope for a file you want Computer to use.Best for: Attaching files without sending their bytes through the MCP server.

`call_perplexity_computer`

The primary tool. Send a message to start a new task or continue an existing conversation.

Parameter	Type	Required	Description
`message`	string	No	The task description or follow-up message.
`thread_id`	string	No	Thread ID to continue an existing conversation. Omit to start a new one.
`attachment_urls`	string[]	No	URLs from `create_attachment_upload` for files to attach to this turn.
`project_uuid`	string	No	Start the new conversation inside this Project, using its instructions, files, connected context, and Project Brain. Get it from `projects_list`. Only for new conversations; can’t be combined with `thread_id`.
`project_visibility`	string	No	`private` (default) or `project`. `project` lets all Project members view the new session. Requires `project_uuid`.
`mode`	string	No	`light`, `standard`, `high`, or `ultra`. Can’t be combined with `model`. See Choosing a Mode or Model.
`model`	string	No	A model `id` from `models_list`. Can’t be combined with `mode`.
`effort`	string	No	`none`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`. Requires `model`, and must be one of that model’s `efforts`. Defaults to the model’s `default_effort`.

Clients that declare MCP elicitation support can handle some events within the active tool call:

Form mode: ask_user_question and confirm_action are asked as a form. Several questions are asked in one form, except when a question allows multiple choices or attachments, or when other prompts arrived at the same time. If the result also had files or sources, the call returns right after your answer with task_status: "working" and those files. Use read_thread to follow the rest of the task. MCP Tasks clients get these through inputRequests instead.
URL mode: for auth_required, interaction_required, and insufficient_credits during a task, the client is asked to open the Perplexity page where you finish that step. The call then returns the usual result. MCP Tasks clients get these through inputRequests instead.

Declining a confirmation form denies the action, so you don’t need to call confirm_action_deny. If your client doesn’t show the form, or you decline a question or cancel a form, the call returns the event. Use the following tools to resume the task.

`answer_question`

Relays answers when Computer returns an ask_user_question event.

Parameter	Type	Required	Description
`thread_id`	string	Yes	The thread ID from the active conversation.
`answers`	object	Yes	Key-value pairs mapping each question to your answer.
`attachment_urls`	string[]	No	URLs from `create_attachment_upload` for files to attach to this answer.
`followup_uuid`	string	No	The `followup_uuid` from the event’s `interactive` object, or `request.answer_submission_uuid` from a `read_thread` form. Pass it when present so the answer reaches the right question.

`confirm_action_approve`

Approves a pending action from a confirm_action event.

Parameter	Type	Required	Description
`thread_id`	string	Yes	The thread ID from the active conversation.
`result`	string	Yes	Reason or message for the approval.
`attachment_urls`	string[]	No	URLs from `create_attachment_upload` for files to attach to this approval.
`followup_uuid`	string	No	The `followup_uuid` from the event’s `interactive` object, or `request.answer_submission_uuid` from a `read_thread` form. Pass it when present so the answer reaches the right question.

`confirm_action_deny`

Denies a pending action from a confirm_action event.

Parameter	Type	Required	Description
`thread_id`	string	Yes	The thread ID from the active conversation.
`result`	string	Yes	Reason for denying the action.
`attachment_urls`	string[]	No	URLs from `create_attachment_upload` for files to attach to this denial.
`followup_uuid`	string	No	The `followup_uuid` from the event’s `interactive` object, or `request.answer_submission_uuid` from a `read_thread` form. Pass it when present so the answer reaches the right question.

`notify_connected`

Tells Computer you finished signing in after an auth_required event.

Parameter	Type	Required	Description
`thread_id`	string	Yes	The thread ID from the active conversation.
`message`	string	Yes	Message about the completed connection. Only sent when the call sends a new message (see below).
`connector`	string	No	The `connector` from the `auth_required` event, for example `slack`. The display name also works. Pass it when more than one sign-in is waiting.
`attachment_urls`	string[]	No	URLs from `create_attachment_upload` for files to attach. Passing attachments always sends a new message.

If the task is waiting on that sign-in, the server answers it the way the Perplexity page does, and the same request continues. The call returns right away with task_status: "working", and message isn’t sent. Use read_thread to follow progress. If the sign-in was already answered in Perplexity, nothing new is sent. If the task is waiting on other input, such as another sign-in, the call returns task_status: "input_required" instead; use read_thread to see what it needs. The call sends message as a new message and waits for the result, like call_perplexity_computer, when:

the request already ended or is sleeping,
no sign-in is waiting,
more than one sign-in is waiting and you didn’t pass connector, or
you passed attachment_urls.

If you pass a connector that isn’t waiting while others are, the call fails and lists the ones that are.

`cancel_task`

Requests cancellation of the current work in a Computer thread, including work paused for a question or approval.

Parameter	Type	Required	Description
`thread_id`	string	Yes	The thread ID returned by a previous call.

Returns a cancelled event with task_status: "cancelled". Only threads you own can be cancelled. If the cancel request itself fails, the call returns an error without task_status, because the task may still be running. If Computer cannot read the thread state, the tool still sends a cancellation request. A paused task may remain input_required in this case. Confirm cancellation with read_thread or tasks/get, and retry if the task remains active. The MCP protocol method tasks/cancel only acknowledges cancellation and returns a link to the thread. See Cancel a task.

`read_thread`

Reads an existing thread without sending a message or resuming the agent. Use it to check on a task after a timeout, a reconnect, or a sleep.

Parameter	Type	Required	Description
`thread_id`	string	Yes	The thread ID returned by a previous call.

Returns:

Field	Type	Description
`thread_id`	string	The thread you asked for.
`event`	string	Always `transcript`.
`status`	string	The thread’s status, for example `queued`, `running`, or `idle`.
`text`	string	The user and assistant messages in order, as Markdown. Long transcripts keep the most recent turns.
`truncated`	boolean	Present and `true` when older turns were left out.
`web_state`	object or null	The thread state shown in Perplexity: `thread_status`, `wake_at`, `task_status`, and each entry’s status, waiting questions or confirmations (`interactions`), connector sign-ins that still need action (`auth_requests`; sign-ins already completed, dismissed, or marked unavailable in Perplexity are left out), and links to forms that must be completed in Perplexity (`form_links`). The latest entry also lists its `steps`.
`web_state_error`	string	Present when `web_state` couldn’t be loaded. Retry `read_thread`.

web_state.task_status is the status of the request in progress: working, input_required, completed, failed, or cancelled. A request that is sleeping until a scheduled time shows working. The latest entry’s steps lists up to its last 20 titled top-level steps. Each has id, title, type, status (the same five values), started_at, completed_at, and up to 5 sources (url and title) when available.

idle or an empty interaction list doesn’t prove a task is finished; use web_state.task_status instead. In interactions, steps marked WORKFLOW_COMPLETED, WORKFLOW_ERROR, or WORKFLOW_CANCELED are terminal. Check for background or scheduled work before treating a thread as complete. Only threads you own can be read.

`list_thread_assets`

Lists durable assets from a thread you own, including generated files.

Parameter	Type	Required	Description
`thread_id`	string	Yes	The thread ID returned by a previous call.
`entry_id`	string	No	Only list assets from this turn.
`cursor`	string	No	`next_cursor` from a previous page.

Returns an assets array and a next_cursor. Keep paging while next_cursor is not null, even when a filtered page is empty. Each asset has:

Field	Type	Description
`asset_id`	string	Pass to `create_asset_download`.
`entry_id`	string	The turn that produced the asset.
`filename`	string or null	File name, when known.
`mime_type`	string or null	Content type guessed from the file name.
`size_bytes`	integer or null	File size in bytes. `null` when unknown.
`asset_type`	string	Asset kind, for example a file, app, or link.
`created_at`	integer	Creation time.
`is_primary_asset`	boolean or null	Whether Computer marked it as the main output. `null` when the source turn is unavailable.
`root_asset_id`	string or null	The first version of this file. Edited versions of the same file share it. Can be `null` on a first version.
`parent_asset_id`	string or null	The version this one was edited from. `null` on a first version.
`published_url`	string or null	The public URL of a website Computer published. `null` for other assets.

`create_asset_download`

Creates a fresh HTTPS download URL for an asset in a thread you own.

Parameter	Type	Required	Description
`thread_id`	string	Yes	The thread the asset belongs to.
`asset_id`	string	Yes	An `asset_id` from `list_thread_assets`.

Returns asset_id, url, and expires_in_seconds.

File download URLs are valid for up to one hour. expires_in_seconds is the time remaining on the URL you received, which can be less than an hour.
Hosted website preview URLs last 24 hours and return expires_in_seconds: null.
Call create_asset_download again whenever you need a new URL.

`projects_list`

Lists Projects you can access, 50 at a time.

Parameter	Type	Required	Description
`search_term`	string	No	Filter by a Project described in natural language.
`cursor`	string	No	`next_cursor` from a previous page.

Returns a projects array and a next_cursor. Keep paging while next_cursor is not null before concluding a Project doesn’t exist. Each Project has:

Field	Type	Description
`project_uuid`	string	Pass to `call_perplexity_computer` as `project_uuid`.
`project_url`	string	The Project’s page in Perplexity.
`name`	string	Project name.
`description`	string	Project description.
`role`	string	Your role in the Project. Writes in a Project conversation follow this role.
`landing_category`	string	Where the Project appears in Perplexity, such as pinned or invited. This isn’t its access policy.
`knowledge_enabled`	boolean	Whether Project knowledge is turned on. It doesn’t guarantee Project Brain has content yet.

Response Format

Task tools return a JSON object with the following fields. create_attachment_upload returns the upload envelope described in File Uploads instead. The JSON is always in the first text content block. Results also carry the same object as structuredContent, except the out-of-credits result returned before a message is sent. error and access_denied results also set the MCP isError flag.

Field	Type	Description
`thread_id`	string	The conversation UUID. Pass this back to continue the conversation. Omitted when a request fails before a thread starts.
`event`	string	The event type indicating what happened. See Events.
`text`	string	Markdown-formatted response text.
`task_status`	string	The result’s standard MCP Tasks state: `working`, `input_required`, `completed`, `failed`, or `cancelled`. See Events and MCP Tasks states. Omitted when the server can’t tell the task’s state, for example when the credit check fails before a message is sent or a follow-up message couldn’t be sent.
`error_code`	string	Present when Computer couldn’t do the work: `computer_error` on an `error` result when the Computer run failed, or `access_denied` when Computer isn’t available for the account. Left out of errors from the MCP server itself, such as a request that couldn’t reach Computer.
`sources`	object[]	Sources Computer could cite in this turn, one per URL in the order found, up to 50. Each has `title`, `url`, `domain`, and `snippet`; `title` and `snippet` can be `null`. Omitted when there are none.
`files`	object[]	Files attached to this result, the same ones linked in `text`. Each has `filename`, `media_type`, `size_bytes`, and `url`; `media_type` and `size_bytes` can be `null`. Omitted when there are none. For a fresh link later, use `list_thread_assets` and `create_asset_download`. Clients on MCP protocol version `2025-06-18` or later also get each file as a `resource_link` content block after the text block.
`wake_at`	string	On `sleep` results, when Computer will resume on its own.
`interactive`	object	Present only for interactive events that require a follow-up action.
`pending_interactions`	object[]	Present when more than one question or confirmation is waiting. Each item has the same shape as `interactive`.
`optional_auth_requests`	object[]	Connectors you can reconnect for better results. Each has `type: "auth_required"`, `thread_id`, `auth_url`, `connector`, `display_name`, `title`, `description`, and `requires_user_response: false`. The task isn’t waiting on these, so don’t call `notify_connected` for them.

Interactive objects for account events

When Computer can’t run for the account, interactive explains why:

{ "type": "insufficient_credits", "reason": "insufficient_credits", "billing_url": "https://www.perplexity.ai/account/usage" }

{ "type": "access_denied", "reason": "access_denied" }

billing_url is present only when topping up or changing a limit would help; it’s left out for reasons like a temporary service outage. When the reason is quota_exhausted, interactive also includes quota_reset_date, the UTC time when the quota comes back (for example 2026-11-01T00:00:00Z). Where you run out of credits matters:

Before a message is sent: the server checks credits before it sends any message, including follow-ups. If that check fails, nothing is sent and the result has no thread_id or task_status. Send the message again after topping up, with the same thread_id for a follow-up.
During a task: the thread keeps its state and task_status is input_required. After topping up, continue with the same thread_id.

Events

Computer tool results include an event field describing the outcome. For MCP Tasks, read it from result.structuredContent after completion.

Event	Description	Action Required
`complete`	The tool call returned a result.	Check `task_status` to determine whether Computer has finished.
`error`	Task failed.	Review the error message.
`cancelled`	Task was cancelled before completion, for example with `cancel_task`.	Start a new task or continue the thread with new instructions.
`sleep`	Agent paused itself and scheduled when to resume.	None. Use `read_thread` with the same `thread_id` to check progress.
`waiting`	Agent is waiting on an external condition or more time to pass.	Keep the `thread_id` and continue the thread when ready.
`ask_user_question`	Agent needs more information.	Call `answer_question` with your answers.
`confirm_action`	Agent wants to perform a sensitive action.	Call `confirm_action_approve` or `confirm_action_deny`.
`auth_required`	A third-party service needs authentication.	Open the provided `auth_url` in a browser, then call `notify_connected` with the event’s `connector`.
`interaction_required`	Computer needs input that can only be given in Perplexity, such as a form MCP doesn’t support.	Open the `url` in `interactive`, complete it there, then continue the thread.
`two_factor_required`	A connector or site requires two-factor authentication.	Follow the instructions in `text`, then continue with the same `thread_id`.
`insufficient_credits`	Account has insufficient credits.	Top up credits or adjust your spending limit.
`access_denied`	Computer is unavailable for the account.	If you belong to an organization, ask its administrator to enable Computer access.
`timeout`	Computer is still working, but the MCP call stopped waiting for a checkpoint.	Call `read_thread` with the same `thread_id` to check status.

Events and Computer task status

The tool result’s task_status field describes Computer’s state using this mapping:

Computer status	Events
`completed`	`complete`
`failed`	`error`, `access_denied`
`cancelled`	`cancelled`
`input_required`	`ask_user_question`, `confirm_action`, `auth_required`, `interaction_required`, `two_factor_required`, `insufficient_credits`
`working`	`sleep`, `waiting`, `timeout`

timeout means the MCP call stopped waiting, not that the task stopped: treat it as still working and use read_thread to check on it. A complete result whose answer is waiting on the user reports input_required. MCP Tasks use a separate status field. A Computer failure finishes the MCP task with status: "completed" and result.isError: true. See Task status.

Links & Resources