Table of Contents

Enabling Perplexity Web Search for an Agent

This guide walks through configuring an agent to use the Perplexity MCP server for web search, question answering, reasoning, and deep research through the built-in Perplexity tools.

Overview

The Perplexity MCP server exposes four tools. The Tool Library has a built-in tool for each one in the Perplexity family:

Library tool Resource name MCP tool Agent tool name Best for Default operation timeout
Perplexity Search Platform-Tool-Perplexity-Search perplexity_search Search Ranked web results with titles, URLs, and snippets 30 s
Perplexity Ask Platform-Tool-Perplexity-Ask perplexity_ask Ask Quick answers with citations 30 s
Perplexity Reason Platform-Tool-Perplexity-Reason perplexity_reason Reason Step-by-step reasoning, comparisons, analysis 60 s
Perplexity Research Platform-Tool-Perplexity-Research perplexity_research Research Deep multi-source research (slow, 30+ s) 120 s

Each tool is a separate MCP tool on the agent so the agent's model can pick the right one. The built-in Perplexity Essentials tool set adds Search and Ask in one step.

All four tools reference an MCP server named Platform-MCP-Perplexity by default.

Prerequisites

  • Access to the Management Portal with permission to manage MCP servers and agents
  • A Perplexity MCP server reachable over HTTP from the platform (see below)
  • The API key that the MCP server expects in its requests

Deploying the Perplexity MCP Server

Using Docker

docker build -t perplexity-mcp-server .
docker run -p 8080:8080 -e PERPLEXITY_API_KEY=pplx_xxxxxxxxxxxx perplexity-mcp-server

Using Node.js

export PERPLEXITY_API_KEY=pplx_xxxxxxxxxxxx
npm install @perplexity-ai/mcp-server
npm run build && npm run start:http

The server listens on http://localhost:8080/mcp by default. Key environment variables:

Variable Default Description
PERPLEXITY_API_KEY (required) Your Perplexity API key
PORT 8080 HTTP server port
BIND_ADDRESS 0.0.0.0 Network interface to bind to
PERPLEXITY_BASE_URL https://api.perplexity.ai Custom base URL for the Perplexity API
PERPLEXITY_TIMEOUT_MS 300000 Request timeout in milliseconds

Step 1: Register the MCP Server

  1. In the sidebar, select Agents > MCP Servers, and then select Create MCP Server.
  2. Configure the server:
Field Value
Resource name Platform-MCP-Perplexity (the name the built-in tools reference). You can use another name and select it on each tool instead.
Display name For example Perplexity MCP
Provider Generic
Endpoint URL https://your-perplexity-mcp-server/mcp
Timeout (seconds) 30 or more
Authentication type API Key
  1. Under HTTP headers, select + Add Header, enter Key x-api-key, choose Source New Value, and enter the key. The value is stored in Key Vault through App Configuration when you save.
  2. Select Create MCP Server.

See MCP Servers for all fields.

Step 2: Add the Perplexity Tools to the Agent

  1. In the sidebar, select Agents > Agents, and then select the pencil icon for the agent (or select Create Agent).
  2. Select the Tools tab, and then select Add Tool.
  3. Do one of the following:
    • To add Search and Ask together, under More options select Add Tool Set, and then select Add set next to Perplexity Essentials.
    • To add one tool, expand the Perplexity folder, select Select on the tool, and then select Add to Agent.
  4. Repeat for any other Perplexity tools you want.

Step 3: Review Each Tool

For each Perplexity tool, select the pencil icon in Tools available to the agent to open Edit Agent Tool, and check:

Section Setting
Connection Registered endpoint with MCP Server Endpoint set to your Perplexity MCP server, and Transport Streamable HTTP
Tool Selection and Configuration Enable Intelligent Execute unchecked, MCP Tool Name set (for example perplexity_search), Response Format JSON
Operation Timeout (seconds) Keep the default, or increase it for slow servers. Use 120 or more for perplexity_research.
Tool Arguments Prefilled from the library tool

To refresh the arguments from the live server, select List Tools, choose the tool, and select Configure. This fills in the description, MCP tool name, response format, and arguments from the tool's input schema.

Select Save changes for each tool, and then save the agent.

Key arguments

Tool Arguments
perplexity_search query (string, required); optional max_results, max_tokens_per_page, country
perplexity_ask messages (array, required)
perplexity_reason messages (array, required), strip_thinking (boolean, optional)
perplexity_research messages (array, required), strip_thinking (boolean, optional)

Note: For messages, the agent's model must build an array of objects with role and content. If the model struggles with this format, use perplexity_search, which takes a simple string.

Configure a Perplexity tool manually

To call a Perplexity tool that is not in the library, add MCP Client from the FoundationaLLM folder, select your Perplexity MCP server under Connection, and then either use List Tools and Configure or enter the MCP Tool Name and Tool Arguments yourself.

Step 4: Update the Agent Prompt

Tell the model about the tools in the agent's main workflow prompt (Basic Settings tab), for example:

You have access to the following web search tools:
- Search: Search the web for current information. Use for finding URLs, checking news, and verifying facts.
- Ask: Ask a question and get an AI-generated answer with citations. Use for quick factual questions and summaries.
- Reason: Perform step-by-step reasoning grounded in web results. Use for complex analysis, math, and comparisons.
- Research: Conduct deep multi-source research. Use for comprehensive overviews and investigative queries (slow, 30+ seconds).

Always use at least one tool to answer questions. Do not answer from your own knowledge.

Step 5: Save and Test

  1. Select Save Changes (or Create Agent) on the agent.
  2. Open the User Portal, select the agent, and try queries such as:
    • What is the current price of GOOG? (Search)
    • Explain how transformers work (Ask)
    • Compare the performance of GPT-4o vs Claude Sonnet on coding benchmarks (Reason)

Choosing Between Search and Ask

For most agents, start with perplexity_search:

  • It takes a simple query string, so the model can call it easily.
  • It returns raw results, so the agent controls how they are presented.
  • It avoids the nested messages format.

Use perplexity_ask when you want Perplexity to summarize results with citations first.

Troubleshooting

List Tools fails or returns no tools

List Tools runs on the platform, not in your browser. For a registered endpoint, the Management API connects with the MCP server's URL, headers, and authentication. Check that the URL and x-api-key header are correct and that the server is reachable from the Management API.

Tool calls fail with a connection error

Verify that the MCP server is running and reachable from the LangChain API. To test connectivity:

curl -X POST https://your-perplexity-mcp-server/mcp \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your key>" \
  -d '{"jsonrpc": "2.0", "method": "initialize", "id": 1, "params": {"protocolVersion": "2025-03-26", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0"}}}'

The model picks the wrong tool

Make the tool descriptions and the agent prompt specific and distinct for each tool.

perplexity_ask reports a messages format error

The model must send messages as a JSON array of role/content objects. If it keeps failing, switch to perplexity_search.

perplexity_research times out

Deep research can take 30 seconds or more. Increase the tool's Operation Timeout (seconds) to at least 120.