> ## Documentation Index
> Fetch the complete documentation index at: https://docs.perplexity.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Perplexity API MCP Server

> Connect AI assistants to Perplexity's search and reasoning capabilities using the Model Context Protocol (MCP).

export const SonarDeprecationNotice = ({showGuideLink = true}) => <Warning>
    Sonar Chat Completions is now <a href="/docs/agent-api/quickstart">Agent API.</a> Sonar will be supported until September 27, 2026.{showGuideLink && <> Migration guide <a href="/docs/agent-api/migrate-from-sonar/overview">here</a>.</>}
  </Warning>;

<SonarDeprecationNotice />

## Overview

The Perplexity MCP Server enables AI assistants to access Perplexity's powerful search and reasoning capabilities directly within their workflows. Using the Model Context Protocol (MCP), you can integrate real-time web search, conversational AI, and advanced reasoning into any MCP-compatible client.

There are two ways to connect:

* **Remote MCP server (recommended):** hosted by Perplexity at `https://api.perplexity.ai/mcp`. No installation, nothing to update, works with any client that supports remote MCP servers. Sign in with your Perplexity account or use an API key.
* **Local MCP server:** run the open-source server on your machine over stdio. Use this if your client only supports stdio servers or you need to pin a version.

The hosted and local options are intended to expose the same Perplexity tools, but transport, authentication, release timing, and client behavior can differ.

<Info>
  The **Model Context Protocol (MCP)** is an open standard that connects AI assistants with external data sources and tools. Learn more at [modelcontextprotocol.io](https://modelcontextprotocol.io/introduction).
</Info>

<Note>
  This page is for adding Perplexity as an MCP tool inside clients such as Google Antigravity, Claude Code, Cursor, VS Code, and Claude Desktop. To call the Perplexity API from application code, start with the [Quickstart](/docs/getting-started/quickstart). To select Claude models through the Agent API, use Anthropic model IDs from [Agent API models](/docs/agent-api/models).
</Note>

## Remote MCP Server

Connect to `https://api.perplexity.ai/mcp` over Streamable HTTP. There are two ways to authenticate:

* **Sign in with Perplexity (OAuth):** add the server without any credentials. On first use your client opens a browser where you sign in to your Perplexity account, choose the API organization to bill, and approve the connection. Works with any client that supports OAuth for remote MCP servers, including Claude Code, Cursor, VS Code, and claude.ai (add it as a [custom connector](https://support.anthropic.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp) using the URL above).
* **API key:** send your key as a bearer token. Use this for clients that do not support OAuth, or for server-side setups such as the Anthropic API MCP connector.

```
Authorization: Bearer YOUR_API_KEY
```

<Card title="Generate API Key" icon="key" arrow="True" horizontal="True" iconType="solid" cta="Get Key" href="https://console.perplexity.ai/project/keys">
  Navigate to the API Portal and generate a new key.
</Card>

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add --transport http perplexity https://api.perplexity.ai/mcp
    ```

    Run `/mcp` inside Claude Code and follow the sign-in prompt for `perplexity`. To use an API key instead, add `--header "Authorization: Bearer YOUR_API_KEY"` to the command.
  </Tab>

  <Tab title="Cursor">
    Add the server to `~/.cursor/mcp.json`, then open **Cursor Settings > Tools & MCP** and click **Connect** next to `perplexity` to sign in:

    ```json theme={null}
    {
      "mcpServers": {
        "perplexity": {
          "url": "https://api.perplexity.ai/mcp"
        }
      }
    }
    ```

    To use an API key instead, [install in Cursor with one click](https://cursor.com/install-mcp?name=perplexity\&config=eyJ1cmwiOiJodHRwczovL2FwaS5wZXJwbGV4aXR5LmFpL21jcCIsImhlYWRlcnMiOnsiQXV0aG9yaXphdGlvbiI6IkJlYXJlciBZT1VSX0FQSV9LRVkifX0%3D) and replace `YOUR_API_KEY` with your key.
  </Tab>

  <Tab title="VS Code">
    Add the server to `.vscode/mcp.json`. VS Code opens a browser to sign in the first time the server starts:

    ```json theme={null}
    {
      "servers": {
        "perplexity": {
          "type": "http",
          "url": "https://api.perplexity.ai/mcp"
        }
      }
    }
    ```

    To use an API key instead, [install in VS Code with one click](https://vscode.dev/redirect/mcp/install?name=perplexity\&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fapi.perplexity.ai%2Fmcp%22%2C%22headers%22%3A%7B%22Authorization%22%3A%22Bearer%20%24%7Binput%3Aperplexity-api-key%7D%22%7D%7D\&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22perplexity-api-key%22%2C%22description%22%3A%22Perplexity%20API%20Key%22%2C%22password%22%3Atrue%7D%5D) and VS Code prompts for your key.
  </Tab>

  <Tab title="Google Antigravity">
    Configure the hosted Perplexity server in your global `~/.gemini/config/mcp_config.json` file. Antigravity connects through `serverUrl` and sends your Perplexity API key as a bearer token:

    ```json theme={null}
    {
      "mcpServers": {
        "perplexity": {
          "serverUrl": "https://api.perplexity.ai/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_PERPLEXITY_API_KEY"
          }
        }
      }
    }
    ```

    Replace `YOUR_PERPLEXITY_API_KEY` with the key you generated in the API Portal. If Antigravity is already running, reopen it after saving the file.

    <Warning>
      Never commit or share API keys. Keep the key in the global configuration file, and do not put a literal key in a workspace `.agents/mcp_config.json` file because workspace configuration may be committed or shared.
    </Warning>

    <Check>
      Setup is complete when Antigravity shows `perplexity_search`, `perplexity_ask`, `perplexity_research`, and `perplexity_reason`. Antigravity runs unconfigured MCP tools in **Ask** permission mode by default, so it requests your approval before execution.
    </Check>

    <Note>
      Google's documentation currently lists `Perplexity Ask` in the [Antigravity MCP Store](https://antigravity.google/docs/mcp#supported-mcp-servers). That Store listing has not been independently verified here; the configuration above connects Antigravity specifically to Perplexity's hosted remote server.
    </Note>

    This MCP configuration gives Antigravity's agent access to Perplexity tools. It does not add Perplexity API calls to the application you are building; for application code, use the [API quickstart](/docs/getting-started/quickstart). See [Google's Antigravity MCP configuration reference](https://antigravity.google/docs/mcp#mcp-configuration-structure) for other supported settings.
  </Tab>

  <Tab title="Anthropic API">
    Use Perplexity's tools in a Messages API request with the MCP connector:

    ```bash theme={null}
    curl https://api.anthropic.com/v1/messages \
      -H "content-type: application/json" \
      -H "x-api-key: $ANTHROPIC_API_KEY" \
      -H "anthropic-version: 2023-06-01" \
      -H "anthropic-beta: mcp-client-2025-11-20" \
      -d '{
        "model": "claude-opus-5",
        "max_tokens": 1024,
        "messages": [{"role": "user", "content": "What happened in AI this week?"}],
        "mcp_servers": [{
          "type": "url",
          "url": "https://api.perplexity.ai/mcp",
          "name": "perplexity",
          "authorization_token": "YOUR_PERPLEXITY_API_KEY"
        }],
        "tools": [{
          "type": "mcp_toolset",
          "mcp_server_name": "perplexity"
        }]
      }'
    ```

    `authorization_token` accepts your Perplexity API key directly (no OAuth needed); it is sent to our server as a bearer token. Anthropic bills the Messages request as usual; Perplexity tool calls are billed to your Perplexity API key.

    To restrict which tools the model can call, disable tools by default and enable the ones you want:

    ```json theme={null}
    "tools": [{
      "type": "mcp_toolset",
      "mcp_server_name": "perplexity",
      "default_config": {"enabled": false},
      "configs": {
        "perplexity_search": {"enabled": true}
      }
    }]
    ```
  </Tab>

  <Tab title="Other Clients">
    Any client that supports remote MCP servers over Streamable HTTP can connect with:

    | Setting   | Value                                               |
    | --------- | --------------------------------------------------- |
    | URL       | `https://api.perplexity.ai/mcp`                     |
    | Transport | Streamable HTTP                                     |
    | Sign in   | OAuth 2.1 with PKCE and dynamic client registration |
    | API key   | Header `Authorization: Bearer YOUR_API_KEY`         |

    If your client only supports stdio servers, use the [local MCP server](#local-mcp-server) below.
  </Tab>
</Tabs>

<Note>
  Tool calls are billed at standard API pricing to the API key you connect with, or to the organization you chose when signing in. Your organization's rate limits apply.
</Note>

### Signing in with Perplexity

Signing in uses your regular Perplexity account. During sign-in you choose which API organization the connection bills to.

* **API usage only.** The connection can call the Perplexity API on behalf of that organization. It cannot create API keys, view balances, or manage the organization.
* **Needs an API organization.** You must be an admin of an API organization that can pay for usage. If you do not have one, the sign-in page links you to create one in the console. Then restart the connection from your client.

## Local MCP Server

Run the same server locally over stdio.

### One-Click Install

<CardGroup cols={2}>
  <Card
    title="Install in Cursor"
    icon={
<svg
  xmlns="http://www.w3.org/2000/svg"
  viewBox="0 0 466.73 532.09"
>
  <path
    d="M457.43 125.94 244.42 2.96a22.127 22.127 0 0 0-22.12 0L9.3 125.94C3.55 129.26 0 135.4 0 142.05v247.99c0 6.65 3.55 12.79 9.3 16.11l213.01 122.98a22.127 22.127 0 0 0 22.12 0l213.01-122.98c5.75-3.32 9.3-9.46 9.3-16.11V142.05c0-6.65-3.55-12.79-9.3-16.11h-.01Zm-13.38 26.05L238.42 508.15c-1.39 2.4-5.06 1.42-5.06-1.36V273.58c0-4.66-2.49-8.97-6.53-11.31L24.87 145.67c-2.4-1.39-1.42-5.06 1.36-5.06h411.26c5.84 0 9.49 6.33 6.57 11.39h-.01Z"
    style={{ fill: "var(--color-foreground)" }}
  />
</svg>
}
    href="https://cursor.com/en/install-mcp?name=perplexity&config=eyJ0eXBlIjoic3RkaW8iLCJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBwZXJwbGV4aXR5LWFpL21jcC1zZXJ2ZXIiXSwiZW52Ijp7IlBFUlBMRVhJVFlfQVBJX0tFWSI6IiJ9fQ=="
  >
    Automatically configure the Perplexity MCP server in Cursor with one click.
  </Card>

  <Card
    title="Install in VS Code"
    icon={
<svg
  xmlns="http://www.w3.org/2000/svg"
  viewBox="0 0 100 100"
>
  <path
    d="M70.912 99.572a6.193 6.193 0 0 0 4.96-.191l20.588-9.958a6.285 6.285 0 0 0 3.54-5.661V16.239a6.286 6.286 0 0 0-3.54-5.662L75.873.62a6.2 6.2 0 0 0-7.104 1.216L29.355 37.98l-17.168-13.1a4.146 4.146 0 0 0-5.318.238l-5.506 5.035a4.205 4.205 0 0 0-.004 6.194L16.247 50 1.36 63.654a4.205 4.205 0 0 0 .004 6.194l5.506 5.034a4.145 4.145 0 0 0 5.318.238l17.168-13.1L68.77 98.166a6.205 6.205 0 0 0 2.143 1.407Zm4.103-72.39L45.11 50 75.015 72.82V27.18Z"
    fillRule="evenodd"
    style={{ fill: "var(--color-foreground)" }}
  />
</svg>
}
    href="https://vscode.dev/redirect/mcp/install?name=perplexity&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40perplexity-ai%2Fmcp-server%22%5D%2C%22env%22%3A%7B%22PERPLEXITY_API_KEY%22%3A%22%22%7D%7D"
  >
    Automatically configure the Perplexity MCP server in VS Code with one click.
  </Card>
</CardGroup>

### Agent Plugin Install

The open-source repository includes an [Agent Plugins 1.0](https://agent-plugins.org) declaration for the local stdio server. If your client supports Agent Plugins, install it from [`perplexityai/modelcontextprotocol`](https://github.com/perplexityai/modelcontextprotocol), then set `PERPLEXITY_API_KEY` in the environment that starts the plugin. The plugin does not include credentials, and installation steps vary by client.

### Manual Setup

<Steps>
  <Step title="Get Your API Key">
    <Card title="Generate API Key" icon="key" arrow="True" horizontal="True" iconType="solid" cta="Get Key" href="https://console.perplexity.ai/project/keys">
      Navigate to the API Portal and generate a new key.
    </Card>
  </Step>

  <Step title="Configure Your Client">
    Add the MCP server to your client configuration:

    <Tabs>
      <Tab title="Claude Code">
        The [remote server](#remote-mcp-server) is the recommended Claude Code setup. Use one of these options only when you need to run the local stdio server.

        Every local option requires `PERPLEXITY_API_KEY` in the environment that launches Claude Code:

        ```bash theme={null}
        export PERPLEXITY_API_KEY="your_api_key_here"
        ```

        **Option 1: CLI Command**

        Add the server to Claude Code's private configuration for the current project. Single quotes preserve the environment variable reference instead of saving the key value in the configuration:

        ```bash theme={null}
        claude mcp add perplexity --env 'PERPLEXITY_API_KEY=${PERPLEXITY_API_KEY}' -- npx -y @perplexity-ai/mcp-server
        ```

        **Option 2: Claude Code Plugin**

        Add the repository as a Claude Code marketplace, install the fully qualified plugin, then start Claude Code from the same environment:

        ```bash theme={null}
        claude plugin marketplace add perplexityai/modelcontextprotocol
        claude plugin install perplexity@perplexity-mcp-server
        claude
        ```

        **Option 3: Manual Configuration**

        Add this configuration to `.mcp.json` in your project root. Claude Code expands `PERPLEXITY_API_KEY` from its launch environment:

        ```json theme={null}
        {
          "mcpServers": {
            "perplexity": {
              "type": "stdio",
              "command": "npx",
              "args": ["-y", "@perplexity-ai/mcp-server"],
              "env": {
                "PERPLEXITY_API_KEY": "${PERPLEXITY_API_KEY}"
              }
            }
          }
        }
        ```

        When you first start Claude Code in the project, approve the `.mcp.json` server when prompted. If `PERPLEXITY_API_KEY` is not set, `claude mcp list` reports it as missing and tool calls cannot authenticate.

        <Warning>
          Do not replace the environment variable reference with your actual API key or commit a key to source control.
        </Warning>
      </Tab>

      <Tab title="Cursor">
        We recommend using the one-click install above for setting up the MCP server in Cursor.

        If you prefer to configure it manually, add the following to your `mcp.json`:

        ```json theme={null}
        {
          "mcpServers": {
            "perplexity": {
              "command": "npx",
              "args": ["-y", "@perplexity-ai/mcp-server"],
              "env": {
                "PERPLEXITY_API_KEY": "your_key_here"
              }
            }
          }
        }
        ```
      </Tab>

      <Tab title="Codex">
        ```bash theme={null}
        codex mcp add perplexity --env PERPLEXITY_API_KEY="your_key_here" -- npx -y @perplexity-ai/mcp-server
        ```
      </Tab>

      <Tab title="Other Clients">
        Most MCP-compatible clients (including Claude Desktop, VS Code, and Windsurf) use the `mcpServers` format. Configuration file locations:

        | Client             | Config File                           |
        | ------------------ | ------------------------------------- |
        | Cursor             | `~/.cursor/mcp.json`                  |
        | VS Code            | `.vscode/mcp.json`                    |
        | Claude Desktop     | `claude_desktop_config.json`          |
        | Windsurf           | `~/.codeium/windsurf/mcp_config.json` |
        | Google Antigravity | `~/.gemini/config/mcp_config.json`    |

        **Standard `mcpServers` format:**

        ```json theme={null}
        {
          "mcpServers": {
            "perplexity": {
              "command": "npx",
              "args": ["-y", "@perplexity-ai/mcp-server"],
              "env": {
                "PERPLEXITY_API_KEY": "your_key_here"
              }
            }
          }
        }
        ```

        **VS Code uses a slightly different format:**

        ```json theme={null}
        {
          "servers": {
            "perplexity": {
              "type": "stdio",
              "command": "npx",
              "args": ["-y", "@perplexity-ai/mcp-server"],
              "env": {
                "PERPLEXITY_API_KEY": "your_key_here"
              }
            }
          }
        }
        ```

        If your client doesn't work with these formats, check its documentation for the correct wrapper format.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Start Using">
    Restart your MCP client and start using Perplexity's tools in your AI workflows.
  </Step>
</Steps>

## Available Tools

<CardGroup cols={2}>
  <Card title="perplexity_search" icon="search">
    Direct web search using the Perplexity Search API. Returns ranked search results with titles, URLs, snippets, and metadata.

    **Best for:** Finding current information, news, facts, or specific web content.
  </Card>

  <Card title="perplexity_ask" icon="message">
    General-purpose conversational AI with real-time web search, backed by the [Agent API](/docs/agent-api/quickstart) `fast` preset.

    **Best for:** Quick questions, everyday searches, and conversational queries that benefit from web context.
  </Card>

  <Card title="perplexity_research" icon="book">
    Deep, comprehensive research backed by the Agent API `high` preset. Provides thorough analysis with citations.

    **Best for:** Complex topics requiring detailed investigation, comprehensive reports, and in-depth analysis.
  </Card>

  <Card title="perplexity_reason" icon="brain">
    Advanced reasoning and problem-solving backed by the Agent API `medium` preset.

    **Best for:** Logical problems, complex analysis, decision-making, and tasks requiring step-by-step reasoning.
  </Card>
</CardGroup>

<Info>
  For detailed setup instructions, troubleshooting, and proxy configuration, visit our [GitHub repository](https://github.com/perplexityai/modelcontextprotocol).
</Info>