Skip to main content
MCP support is in preview. Pricing and availability may change.

​
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. 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. 
from perplexity import Perplexity

client = Perplexity()

response = client.responses.create(
    model="openai/gpt-5.5",
    input="Use DeepWiki to explain what the perplexityai/perplexity-py repository does.",
    tools=[
        {
            "type": "mcp",
            "server_label": "deepwiki",
            "server_url": "https://mcp.deepwiki.com/mcp",
        }
    ],
)

print(response.output_text)

{
  "id": "resp_df17e3cb-5cdd-4197-a5c7-36746b4729cd",
  "model": "openai/gpt-5.5",
  "object": "response",
  "status": "completed",
  "output": [
    {
      "type": "mcp_list_tools",
      "id": "mcpl_8a21fbe7-9dfa-4b66-8326-24145ad33518",
      "server_label": "deepwiki",
      "tools": [
        {
          "name": "read_wiki_structure",
          "description": "Get a list of documentation topics for a GitHub repository.",
          "input_schema": {
            "type": "object",
            "properties": { "repoName": { "type": "string" } },
            "required": ["repoName"]
          }
        },
        {
          "name": "read_wiki_contents",
          "description": "View documentation about a GitHub repository.",
          "input_schema": {
            "type": "object",
            "properties": { "repoName": { "type": "string" } },
            "required": ["repoName"]
          }
        },
        {
          "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": { "type": "string" },
              "question": { "type": "string" }
            },
            "required": ["repoName", "question"]
          }
        }
      ],
      "error": null
    },
    {
      "type": "mcp_call",
      "id": "call_4zPrdxq5mvF107NpSktdKxgR",
      "server_label": "deepwiki",
      "name": "ask_question",
      "arguments": "{\"repoName\":\"perplexityai/perplexity-py\",\"question\":\"What does the perplexityai/perplexity-py repository do?\"}",
      "output": "The `perplexityai/perplexity-py` repository provides the official Python SDK for the Perplexity AI API. It offers type-safe access to chat completions, search, responses, embeddings, and browser sessions, with both synchronous and asynchronous clients...",
      "error": null
    },
    {
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "The `perplexityai/perplexity-py` repository is the official Python SDK for the Perplexity AI API. It lets Python developers call Perplexity's services from their own applications using a typed, convenient client library instead of making raw HTTP requests...",
          "annotations": []
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 2029,
    "output_tokens": 1335,
    "total_tokens": 3364
  }
}

​
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: 
import os
from perplexity import Perplexity

client = Perplexity()

response = client.responses.create(
    model="openai/gpt-5.5",
    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)
This example uses the GitHub MCP Server. Create a GitHub personal access token with access to the repositories you want the model to inspect, and export it as GITHUB_MCP_TOKEN.

​
Parameters

ParameterTypeRequiredDescription
typestringYesMust be "mcp".
server_labelstringYesUnique per request, matching ^[a-zA-Z0-9_-]{1,64}$. Namespaces the server’s tools.
server_urlstringYesHTTPS URL of the remote MCP server. Must be a Streamable HTTP MCP endpoint; the legacy SSE transport is not supported.
authorizationstringNoAn access token passed to the remote MCP server for authentication. Provide the raw token value. Never logged or echoed.
headersobjectNoExtra request headers (string values) sent to the MCP server.
allowed_toolsarrayNoAllowlist of tool names to expose to the model. Omit or leave empty to expose all discovered tools.

​
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.

​
mcp_list_tools

FieldTypeDescription
typestringAlways mcp_list_tools.
idstringIdentifier for this output item.
server_labelstringThe server_label you supplied for this server.
toolsarrayThe tools discovered on the server.
errorstring | nullnull when the server’s tools were listed successfully.
Each entry in tools has the following fields:
FieldTypeDescription
namestringTool name as exposed by the server.
descriptionstringTool description from the server.
input_schemaobjectThe server’s JSON Schema for the tool’s input, passed through unmodified.

​
mcp_call

FieldTypeDescription
typestringAlways mcp_call.
idstringIdentifier for this output item.
server_labelstringThe server_label of the server that ran the tool.
namestringName of the tool that was called.
argumentsstringJSON-encoded arguments the model passed.
outputstringTool output text. Empty when the call fails.
errorstring | nullnull on success. When the call fails, holds the failure string, which is also returned to the model in-band.
Example response output array: 
{
  "output": [
    {
      "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"]
          }
        }
      ],
      "error": null
    },
    {
      "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

CaseWhat you see
Discovery failureThe 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 failureThe 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.
Agent API does not support MCP approvals yet. Every MCP tool call auto-runs, so only connect MCP servers and expose tools that you trust to run without an approval step.
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 fieldBehavior
require_approvalIgnored. Every MCP tool call auto-runs.
mcp_approval_request / mcp_approval_responseNot emitted or accepted. Approval pause/continue flows are not available yet.
connector_id and hosted connector catalogsIgnored. Only bring-your-own server_url is honored.
Connector OAuth flowsNot supported. Pass credentials to your own remote server with authorization.
defer_loadingIgnored. Tools are discovered when the request starts.
MCP resources, prompts, and samplingNot supported yet; tools are the only supported MCP capability.
approval_request_id and status on MCP output itemsNot 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.