MCP

Connect a remote Model Context Protocol (MCP) server to an Agent API request so the model can call your server’s tools.

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.

Python

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:

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)

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.