MCP

Overview

Beyond the function tools you define yourself, you can give a model new capabilities by connecting it to a remote Model Context Protocol (MCP) server. The model calls that server's tools to reach and control external services when it needs them to answer a prompt.

The mcp tool connects a user-supplied remote MCP server to an Agent API request. Agent API discovers the server's tools when the request starts and calls them like native tools during the run, so you don't have to write a custom function tool for each one.

You can connect your own MCP server in two ways:

Use type: "mcp" to provide the server URL and authentication in each request. This requires Streamable HTTP.
Add a custom connector to save the server URL and authentication once in the API Console. Perplexity stores the MCP server's token, so your application does not need to store or send it with each request. Any API key in that Project can then use it with type: "connector" and its connector ID. Custom connectors support Streamable HTTP and SSE.

Some managed connectors, such as GitHub, also provide credentials for Sandbox commands. Custom connectors and the mcp tool do not provide this Sandbox integration.

The example below connects to the public DeepWiki MCP server, which needs no authentication, and asks the model to answer a question about a GitHub repository using the server's tools.

Python

from perplexity import Perplexity

client = Perplexity()

response = client.responses.create(
    model="openai/gpt-5.6-sol",
    input="Ask DeepWiki which Python versions the perplexityai/perplexity-py repository supports.",
    tools=[
        {
            "type": "mcp",
            "server_label": "deepwiki",
            "server_url": "https://mcp.deepwiki.com/mcp",
        }
    ],
)

print(response.output_text)

Typescript

import Perplexity from '@perplexity-ai/perplexity_ai';

const client = new Perplexity();

const response = await client.responses.create({
  model: 'openai/gpt-5.6-sol',
  input: 'Ask DeepWiki which Python versions the perplexityai/perplexity-py repository supports.',
  tools: [
    {
      type: 'mcp',
      server_label: 'deepwiki',
      server_url: 'https://mcp.deepwiki.com/mcp',
    },
  ],
});

console.log(response.output_text);

cURL

curl https://api.perplexity.ai/v1/agent \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.6-sol",
    "input": "Ask DeepWiki which Python versions the perplexityai/perplexity-py repository supports.",
    "tools": [
      {
        "type": "mcp",
        "server_label": "deepwiki",
        "server_url": "https://mcp.deepwiki.com/mcp"
      }
    ]
  }' | jq

The sample below shows only the response's output array, with long MCP tool outputs truncated.

Response

JSON

[
  {
    "type": "mcp_list_tools",
    "id": "mcpl_b6875670-9dd5-46e0-9616-2f15e35bc0d1",
    "server_label": "deepwiki",
    "tools": [
      {
        "name": "ask_question",
        "description": "Ask any question about a GitHub repository and get an AI-powered, context-grounded response.",
        "input_schema": {
          "type": "object",
          "properties": {
            "repoName": {
              "description": "GitHub repository or list of repositories (max 10) in owner/repo format.",
              "anyOf": [
                { "type": "string" },
                { "type": "array", "items": { "type": "string" } }
              ]
            },
            "question": {
              "type": "string",
              "description": "The question to ask about the repository."
            }
          },
          "required": ["repoName", "question"]
        }
      },
      {
        "name": "read_wiki_contents",
        "description": "View documentation about a GitHub repository.",
        "input_schema": {
          "type": "object",
          "properties": {
            "repoName": {
              "type": "string",
              "description": "GitHub repository in owner/repo format (e.g. \"facebook/react\")."
            }
          },
          "required": ["repoName"]
        }
      },
      {
        "name": "read_wiki_structure",
        "description": "Get a list of documentation topics for a GitHub repository.",
        "input_schema": {
          "type": "object",
          "properties": {
            "repoName": {
              "type": "string",
              "description": "GitHub repository in owner/repo format (e.g. \"facebook/react\")."
            }
          },
          "required": ["repoName"]
        }
      }
    ]
  },
  {
    "type": "mcp_call",
    "id": "call_Ev48gan4OR0rrPQYb8xuSq3r",
    "server_label": "deepwiki",
    "name": "ask_question",
    "arguments": "{\"question\":\"Which Python versions does this repository support? Please cite the repository files or documentation that specify the supported versions, and distinguish package metadata requirements from tested CI versions if applicable.\",\"repoName\":\"perplexityai/perplexity-py\"}",
    "output": "The `perplexity-py` repository supports Python versions 3.9 and higher. This is specified in the `pyproject.toml` file, which indicates a `requires-python` constraint of `>= 3.9`.\n\nThe project metadata also lists classifiers for Python versions 3.9 through 3.14, indicating that these versions are considered compatible... [truncated]",
    "error": null
  },
  {
    "type": "message",
    "id": "msg_b80c49c9-1215-4c0a-94f0-188ecc2b1e22",
    "role": "assistant",
    "status": "completed",
    "content": [
      {
        "type": "output_text",
        "text": "The `perplexityai/perplexity-py` repository supports **Python 3.9 and newer** (`requires-python = \">=3.9\"` in `pyproject.toml`).\n\nIts package classifiers list compatibility with **Python 3.9 through 3.14**. Python 3.8 support was previously dropped. Note that Ruff's `py38` target concerns source-code syntax and does not change the runtime requirement.",
        "annotations": []
      }
    ]
  }
]

Defer tool definitions

By default, every MCP tool definition the request exposes enters the model's initial context. Set defer_loading to true when a server has many tools or large schemas, or when you connect several servers at once. The model can then search the catalog and load only the schemas it needs. The field is per server, so set it on each one you want deferred. Omitting the field, or setting it to false, keeps the default eager behavior.

Deferred loading spends extra model turns before the first tool call. Set max_steps high enough that the model can search the catalog and still call the tools it finds. Otherwise a run can end right after the search and answer without ever calling a tool.

In the example below, none of DeepWiki's three tool definitions start in the model's context. The model searches the catalog, loads only what the search matches, and calls the tool it found.

Python

from perplexity import Perplexity

client = Perplexity()

response = client.responses.create(
    model="openai/gpt-5.6-sol",
    input="Ask DeepWiki this exact question: which license does fastapi/fastapi use?",
    max_steps=6,
    tools=[
        {
            "type": "mcp",
            "server_label": "deepwiki",
            "server_url": "https://mcp.deepwiki.com/mcp",
            "defer_loading": True,
        }
    ],
)

print(response.output_text)

Typescript

import Perplexity from '@perplexity-ai/perplexity_ai';

const client = new Perplexity();

const response = await client.responses.create({
  model: 'openai/gpt-5.6-sol',
  input: 'Ask DeepWiki this exact question: which license does fastapi/fastapi use?',
  max_steps: 6,
  tools: [
    {
      type: 'mcp',
      server_label: 'deepwiki',
      server_url: 'https://mcp.deepwiki.com/mcp',
      defer_loading: true,
    },
  ],
});

console.log(response.output_text);

cURL

curl https://api.perplexity.ai/v1/agent \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.6-sol",
    "input": "Ask DeepWiki this exact question: which license does fastapi/fastapi use?",
    "max_steps": 6,
    "tools": [
      {
        "type": "mcp",
        "server_label": "deepwiki",
        "server_url": "https://mcp.deepwiki.com/mcp",
        "defer_loading": true
      }
    ]
  }' | jq

The sample below shows only the response's output array, with long MCP tool outputs truncated.

Response

JSON

[
  {
    "type": "mcp_list_tools",
    "id": "mcpl_737d73ac-416a-4cde-a296-479de85a65d1",
    "server_label": "deepwiki",
    "tools": [
      {
        "name": "ask_question",
        "description": "Ask any question about a GitHub repository and get an AI-powered, context-grounded response.",
        "input_schema": {
          "properties": {
            "question": {
              "description": "The question to ask about the repository.",
              "type": "string"
            },
            "repoName": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "items": {
                    "type": "string"
                  },
                  "type": "array"
                }
              ],
              "description": "GitHub repository or list of repositories (max 10) in owner/repo format."
            }
          },
          "required": [
            "repoName",
            "question"
          ],
          "type": "object"
        }
      },
      {
        "name": "read_wiki_contents",
        "description": "View documentation about a GitHub repository.",
        "input_schema": {
          "properties": {
            "repoName": {
              "description": "GitHub repository in owner/repo format (e.g. \"facebook/react\").",
              "type": "string"
            }
          },
          "required": [
            "repoName"
          ],
          "type": "object"
        }
      },
      {
        "name": "read_wiki_structure",
        "description": "Get a list of documentation topics for a GitHub repository.",
        "input_schema": {
          "properties": {
            "repoName": {
              "description": "GitHub repository in owner/repo format (e.g. \"facebook/react\").",
              "type": "string"
            }
          },
          "required": [
            "repoName"
          ],
          "type": "object"
        }
      }
    ]
  },
  {
    "type": "tool_search_output",
    "id": "tso_call_4ZM8bZTRYO2Cq6ZvY5WBJPvK",
    "call_id": null,
    "status": "completed",
    "execution": "server",
    "arguments": "{\"paths\":[\"deepwiki\"],\"queries\":[\"ask\",\"question\"]}",
    "tools": [
      {
        "type": "namespace",
        "name": "deepwiki",
        "description": "",
        "tools": [
          {
            "type": "function",
            "name": "ask_question",
            "description": "Ask any question about a GitHub repository and get an AI-powered, context-grounded response.",
            "parameters": {
              "properties": {
                "question": {
                  "description": "The question to ask about the repository.",
                  "type": "string"
                },
                "repoName": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "items": {
                        "type": "string"
                      },
                      "type": "array"
                    }
                  ],
                  "description": "GitHub repository or list of repositories (max 10) in owner/repo format."
                }
              },
              "required": [
                "repoName",
                "question"
              ],
              "type": "object"
            }
          }
        ]
      }
    ]
  },
  {
    "type": "mcp_call",
    "id": "call_EDUuJFdKLABQvPUuDl0WeRwK",
    "server_label": "deepwiki",
    "name": "ask_question",
    "arguments": "{\"question\":\"which license does fastapi/fastapi use?\",\"repoName\":\"fastapi/fastapi\"}",
    "output": "The `fastapi/fastapi` project is licensed under the MIT License... [truncated]",
    "error": null
  },
  {
    "type": "message",
    "id": "msg_dc0c8b47-fe82-40db-a6ec-e84ac99d7710",
    "role": "assistant",
    "status": "completed",
    "content": [
      {
        "type": "output_text",
        "text": "DeepWiki says **fastapi/fastapi uses the MIT License**.",
        "annotations": []
      }
    ]
  }
]

Each tool_search_output item is one search of the deferred catalog. The search can cover every deferred server or narrow to one, and it returns only the tools it matches — one of DeepWiki's three above. A search can also return no match, and the model can then search again, so a run may hold several of these items. Calls still appear as mcp_call. Agent API still discovers each server's tools when the request starts, so deferred loading does not eliminate discovery time or change discovery failure behavior.

Three small tools is a modest catalog, so the extra search step buys little here. Deferred loading pays off as the catalog grows: more servers, more tools, larger schemas, or a context window you would otherwise exceed.

Authentication

Unlike the DeepWiki server above, most MCP servers require authentication. The most common scheme is an OAuth access token, which you pass in the authorization field of the mcp tool:

Python

import os
from perplexity import Perplexity

client = Perplexity()

response = client.responses.create(
    model="openai/gpt-5.6-sol",
    input="Use GitHub to find open issues about authentication in perplexityai/perplexity-py.",
    tools=[
        {
            "type": "mcp",
            "server_label": "github",
            "server_url": "https://api.githubcopilot.com/mcp/",
            "authorization": os.environ["GITHUB_MCP_TOKEN"],
            "allowed_tools": ["search_repositories", "list_issues", "issue_read"],
        }
    ],
)

print(response.output_text)

Typescript

import Perplexity from '@perplexity-ai/perplexity_ai';

const client = new Perplexity();

const response = await client.responses.create({
  model: 'openai/gpt-5.6-sol',
  input: 'Use GitHub to find open issues about authentication in perplexityai/perplexity-py.',
  tools: [
    {
      type: 'mcp',
      server_label: 'github',
      server_url: 'https://api.githubcopilot.com/mcp/',
      authorization: process.env.GITHUB_MCP_TOKEN,
      allowed_tools: ['search_repositories', 'list_issues', 'issue_read'],
    },
  ],
});

console.log(response.output_text);

cURL

curl https://api.perplexity.ai/v1/agent \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.6-sol",
    "input": "Use GitHub to find open issues about authentication in perplexityai/perplexity-py.",
    "tools": [
      {
        "type": "mcp",
        "server_label": "github",
        "server_url": "https://api.githubcopilot.com/mcp/",
        "authorization": "'"$GITHUB_MCP_TOKEN"'",
        "allowed_tools": ["search_repositories", "list_issues", "issue_read"]
      }
    ]
  }' | jq

Parameters

Parameter	Type	Required	Description
`type`	string	Yes	Must be `"mcp"`.
`server_label`	string	Yes	Unique per request, matching `^[a-zA-Z0-9_-]{1,64}$`. Namespaces the server's tools.
`server_url`	string	Yes	HTTPS URL of the remote MCP server. Must be a Streamable HTTP MCP endpoint; the legacy SSE transport is not supported.
`authorization`	string	No	An access token passed to the remote MCP server for authentication. Provide the raw token value. Never logged or echoed.
`headers`	object	No	Extra request headers (string values) sent to the MCP server.
`allowed_tools`	array	No	Allowlist of tool names to expose to the model. Omit or leave empty to expose all discovered tools.
`defer_loading`	boolean	No	When `true`, keeps discovered tool definitions out of the initial model context and lets the model load relevant schemas as needed. Defaults to `false`.

Response shape

When an mcp tool is used, the response output array can include two MCP-specific item types alongside the final message item:

mcp_list_tools — emitted once per server, listing the tools discovered when the request starts.
mcp_call — emitted for each tool the model invokes on the server.

With defer_loading: true, the array can also include tool_search_output items when the model searches the deferred catalog. Tool invocations still appear as mcp_call items.

`mcp_list_tools`

Field	Type	Description
`type`	string	Always `mcp_list_tools`.
`id`	string	Identifier for this output item.
`server_label`	string	The `server_label` you supplied for this server.
`tools`	array	The tools discovered on the server.
`error`	string	Absent when the server's tools were listed successfully.

Each entry in tools has the following fields:

Field	Type	Description
`name`	string	Tool name as exposed by the server.
`description`	string	Tool description from the server.
`input_schema`	object	The server's JSON Schema for the tool's input, passed through unmodified.

`mcp_call`

Field	Type	Description
`type`	string	Always `mcp_call`.
`id`	string	Identifier for this output item.
`server_label`	string	The `server_label` of the server that ran the tool.
`name`	string	Name of the tool that was called.
`arguments`	string	JSON-encoded arguments the model passed.
`output`	string	Tool output text. Empty when the call fails.
`error`	string \| null	`null` on success. When the call fails, holds the failure string, which is also returned to the model in-band.

`tool_search_output`

Emitted only with defer_loading: true, once per search the model runs against the deferred catalog.

Field	Type	Description
`type`	string	Always `tool_search_output`.
`id`	string	Identifier for this output item.
`call_id`	string \| null	Always `null` for hosted catalog searches.
`execution`	string	Where the search ran. Currently always `server` — tolerate other values.
`status`	string	Search status, for example `completed`.
`arguments`	string	Opaque search text the model authored, and may be absent. Treat it as unstructured and do not parse it — its shape is not part of the contract.
`tools`	array	Matching tools, grouped per server. Empty when the search finds nothing.

Each entry in tools is a namespace for one server:

Field	Type	Description
`type`	string	Always `namespace`.
`name`	string	The `server_label` of the server the tools belong to.
`description`	string	Namespace description. Empty for MCP servers.
`tools`	array	Matching tools, each with `type` (`function`), `name`, `description`, and `parameters` (the server's JSON Schema).

Example response output array:

JSON

[
  {
    "type": "mcp_list_tools",
    "id": "mcpl_01bcb639-715a-4d5e-be5e-712ac7120bb2",
    "server_label": "github",
    "tools": [
      {
        "name": "issue_read",
        "description": "Get information about a specific issue in a GitHub repository.",
        "input_schema": {
          "type": "object",
          "properties": {
            "method": { "type": "string" },
            "owner": { "type": "string" },
            "repo": { "type": "string" },
            "issue_number": { "type": "number" }
          },
          "required": ["method", "owner", "repo", "issue_number"]
        }
      },
      {
        "name": "list_issues",
        "description": "List issues in a GitHub repository.",
        "input_schema": {
          "type": "object",
          "properties": {
            "owner": { "type": "string" },
            "repo": { "type": "string" },
            "state": { "type": "string" }
          },
          "required": ["owner", "repo"]
        }
      },
      {
        "name": "search_repositories",
        "description": "Find GitHub repositories by name, description, readme, topics, or other metadata.",
        "input_schema": {
          "type": "object",
          "properties": { "query": { "type": "string" } },
          "required": ["query"]
        }
      }
    ]
  },
  {
    "type": "mcp_call",
    "id": "call_dQzJLduEASo7JlHfwN0w09xL",
    "server_label": "github",
    "name": "list_issues",
    "arguments": "{\"owner\":\"perplexityai\",\"repo\":\"perplexity-py\",\"state\":\"OPEN\",\"orderBy\":\"CREATED_AT\",\"direction\":\"DESC\"}",
    "output": "{\"issues\":[{\"number\":60,\"title\":\"Feature Bundle Request: Explicit Prompt Caching, Multi-Model Fusion, and Granular API Key Controls\"}, ...]}",
    "error": null
  },
  {
    "type": "message",
    "role": "assistant",
    "content": [
      {
        "type": "output_text",
        "text": "I found one open issue in `perplexityai/perplexity-py` relevant to authentication / access control: #60 — \"Feature Bundle Request: Explicit Prompt Caching, Multi-Model Fusion, and Granular API Key Controls\" — which requests enterprise-grade API key controls (per-key spending limits, model whitelisting, workspace segregation)."
      }
    ]
  }
]

Error handling

Case	What you see
Discovery failure	The request fails with `external_connector_error` (HTTP `424 Failed Dependency`) — the server's tools could not be listed, so the run never starts and no `output` array is returned. The error body's `message` names the server, for example `MCP server "github" could not be initialized`.
Tool-call failure	The matching `mcp_call` item has its `output` empty and an `error` string set. The failure is also returned to the model in-band, so it can recover or explain in its final answer.

A discovery failure happens when a server cannot be reached or returns an unusable response as its tools are listed at the start of the run. Because discovery runs before the model, the whole request fails with external_connector_error and returns no output array.

Tool-call failures during the run do not fail the request. The error is returned to the model in-band on the mcp_call item (as above), so the model can recover or explain it in its final answer.

Risks and safety

The mcp tool lets you connect models to external services — a powerful capability that carries risk. Remote MCP servers are third-party services that have not been verified by Perplexity. They can let a model read, send, and receive data, and take actions in the connected service, and each server is subject to its own terms and conditions. Connect only servers you trust.

Use allowed_tools to limit which server tools the model can call. For servers with write or admin actions, prefer read-only server modes, read-only tokens, or a small allowlist of read-only tools.

Limitations

The mcp tool is backward-compatible with OpenAI's Responses MCP API. The following OpenAI MCP features are temporarily not supported:

Feature or field	Behavior
`require_approval`	Ignored. Every MCP tool call auto-runs.
`mcp_approval_request` / `mcp_approval_response`	Not emitted or accepted. Approval pause/continue flows are not available yet.
`connector_id` and hosted connector catalogs	Ignored. Only bring-your-own `server_url` is honored.
Connector OAuth flows	Not supported. Pass credentials to your own remote server with `authorization`.
MCP resources, prompts, and sampling	Not supported yet; tools are the only supported MCP capability.
`approval_request_id` and `status` on MCP output items	Not present in the MCP output item shapes.

Pricing

MCP tool calls are free — Agent API does not charge a per-invocation fee for calling a remote MCP server. Model token usage is still billed separately according to Agent API token pricing (see Models for per-model rates), and you operate the remote MCP server, so any cost it incurs is outside Agent API billing.

Search documentation

Getting Started

Router API

Agent API

Embeddings API

Perplexity SDK

Admin & Management

Resources

MCP

Overview

Defer tool definitions

Authentication

Parameters

Response shape

`mcp_list_tools`

`mcp_call`

`tool_search_output`

Error handling

Risks and safety

Limitations

Pricing

Getting Started

Router API

Agent API

Embeddings API

Perplexity SDK

Admin & Management

Resources