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

For a fuller, runnable example that combines an MCP server with the model’s own web search, see the Model Picker cookbook recipe.

from perplexity import Perplexity

client = Perplexity()

response = client.responses.create(
    model="openai/gpt-5.6-sol",
    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)

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 DeepWiki to explain what the perplexityai/perplexity-py repository does.',
  tools: [
    {
      type: 'mcp',
      server_label: 'deepwiki',
      server_url: 'https://mcp.deepwiki.com/mcp',
    },
  ],
});

console.log(response.output_text);

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 DeepWiki to explain what the perplexityai/perplexity-py repository does.",
    "tools": [
      {
        "type": "mcp",
        "server_label": "deepwiki",
        "server_url": "https://mcp.deepwiki.com/mcp"
      }
    ]
  }' | jq

Response

{
  "id": "resp_df17e3cb-5cdd-4197-a5c7-36746b4729cd",
  "model": "openai/gpt-5.6-sol",
  "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.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)

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

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

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.

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`

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 \| null	`null` 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.

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

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.

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 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`.
`defer_loading`	Ignored. Tools are discovered when the request starts.
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.

Getting Started

Agent API

Search API

Sonar API

Embeddings API

Perplexity SDK

Admin & Management

Resources

Overview

Authentication

Parameters

Response shape

`mcp_list_tools`

`mcp_call`

Error handling

Risks and safety

Limitations

Pricing

​Overview

​Authentication

​Parameters

​Response shape

​mcp_list_tools

​mcp_call

​Error handling

​Risks and safety

​Limitations

​Pricing

Overview

Authentication

Parameters

Response shape

`mcp_list_tools`

`mcp_call`

Error handling

Risks and safety

Limitations

Pricing