release: 0.39.0

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.38.0"
+  ".": "0.39.0"
 }

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 13
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/perplexity-ai/perplexity-6a9e741f72f36fa6c1f8ece842ba1616376107badbfdeaf6e88c5db7b9412437.yml
-openapi_spec_hash: 76d7c6e6e7f84a1de30b869a7579e6b6
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/perplexity-ai/perplexity-a48f6cfc0c2120ede5bd103b3c7fce20079d5a8baece7dad3ddaf98955309329.yml
+openapi_spec_hash: 5f4746838a4a9455b5413bb3f1a01b84
 config_hash: 3f1487a29a16f85810ba4d77134da232

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.39.0 (2026-07-02)
+
+Full Changelog: [v0.38.0...v0.39.0](https://github.com/perplexityai/perplexity-py/compare/v0.38.0...v0.39.0)
+
+### Features
+
+* **responses:** add `mcp` tool and typed `mcp_list_tools`/`mcp_call` output items ([52f63d3](https://github.com/perplexityai/perplexity-py/commit/52f63d379a5b871fdffedc3bc38c0d6393f4db54))
+
 ## 0.38.0 (2026-06-08)
 
 Full Changelog: [v0.37.0...v0.38.0](https://github.com/perplexityai/perplexity-py/compare/v0.37.0...v0.38.0)

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "perplexityai"
-version = "0.38.0"
+version = "0.39.0"
 description = "The official Python library for the perplexity API"
 dynamic = ["readme"]
 license = "Apache-2.0"

src/perplexity/_version.py

@@ -1,4 +1,4 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 __title__ = "perplexity"
-__version__ = "0.38.0"  # x-release-please-version
+__version__ = "0.39.0"  # x-release-please-version

src/perplexity/types/output_item.py

@@ -1,6 +1,6 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-from typing import List, Union, Optional
+from typing import Dict, List, Union, Optional
 from typing_extensions import Literal, Annotated, TypeAlias
 
 from .._utils import PropertyInfo
@@ -15,6 +15,9 @@
     "SearchResultsOutputItem",
     "FetchURLResultsOutputItem",
     "FetchURLResultsOutputItemContent",
+    "McpListToolsOutputItem",
+    "McpListToolsOutputItemTool",
+    "McpCallOutputItem",
 ]
 
 
@@ -59,7 +62,68 @@ class FetchURLResultsOutputItem(BaseModel):
     type: Literal["fetch_url_results"]
 
 
+class McpListToolsOutputItemTool(BaseModel):
+    """One tool discovered on a remote MCP server."""
+
+    input_schema: Dict[str, object]
+    """The server's JSON Schema for the tool, passed through unmodified."""
+
+    name: str
+
+    description: Optional[str] = None
+
+
+class McpListToolsOutputItem(BaseModel):
+    """Tools discovered on one external MCP server at boot.
+
+    Matches OpenAI's mcp_list_tools item.
+    """
+
+    id: str
+
+    server_label: str
+
+    tools: List[McpListToolsOutputItemTool]
+
+    type: Literal["mcp_list_tools"]
+
+    error: Optional[str] = None
+
+
+class McpCallOutputItem(BaseModel):
+    """
+    One tool call executed against an external MCP server, modeled on OpenAI's mcp_call item.
+    """
+
+    id: str
+
+    arguments: str
+    """JSON-encoded arguments the model passed."""
+
+    name: str
+
+    server_label: str
+
+    type: Literal["mcp_call"]
+
+    error: Optional[str] = None
+    """
+    The failure string when the call failed (also returned to the model in-band);
+    null on success, matching OpenAI's mcp_call.
+    """
+
+    output: Optional[str] = None
+    """Tool output text; empty when the call failed."""
+
+
 OutputItem: TypeAlias = Annotated[
-    Union[MessageOutputItem, SearchResultsOutputItem, FetchURLResultsOutputItem, FunctionCallOutputItem],
+    Union[
+        MessageOutputItem,
+        SearchResultsOutputItem,
+        FetchURLResultsOutputItem,
+        FunctionCallOutputItem,
+        McpListToolsOutputItem,
+        McpCallOutputItem,
+    ],
     PropertyInfo(discriminator="type"),
 ]

src/perplexity/types/response_create_params.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Union, Iterable, Optional
+from typing import Dict, Union, Iterable, Optional
 from typing_extensions import Literal, Required, TypeAlias, TypedDict
 
 from .._types import SequenceNotStr
@@ -21,6 +21,7 @@
     "ToolPeopleSearchTool",
     "ToolFinanceSearchTool",
     "ToolSandboxTool",
+    "ToolMcpTool",
     "ResponseCreateParamsNonStreaming",
     "ResponseCreateParamsStreaming",
 ]
@@ -172,8 +173,45 @@ class ToolSandboxTool(TypedDict, total=False):
     """
 
 
+class ToolMcpTool(TypedDict, total=False):
+    """Connects a user-supplied remote MCP server.
+
+    The worker discovers the
+    server's tools at boot and calls them like native tools. Matches
+    OpenAI's mcp tool. `require_approval`, `connector_id`, and
+    `defer_loading` are not supported in v1 and are ignored if sent:
+    every call auto-runs, and only bring-your-own `server_url` is honored.
+    """
+
+    server_label: Required[str]
+    """Unique per request, ^[a-zA-Z0-9_-]{1,64}$. Namespaces the server's tools."""
+
+    server_url: Required[str]
+    """HTTPS URL of the remote MCP server."""
+
+    type: Required[Literal["mcp"]]
+
+    allowed_tools: SequenceNotStr[str]
+    """Optional allowlist of tool names. Empty exposes all discovered tools."""
+
+    authorization: str
+    """
+    An OAuth access token that can be used with a remote MCP server, with a custom
+    MCP server URL. Never logged or echoed.
+    """
+
+    headers: Dict[str, str]
+    """Extra request headers. Never logged or echoed."""
+
+
 Tool: TypeAlias = Union[
-    ToolWebSearchTool, ToolFetchURLTool, ToolPeopleSearchTool, FunctionToolParam, ToolFinanceSearchTool, ToolSandboxTool
+    ToolWebSearchTool,
+    ToolFetchURLTool,
+    ToolPeopleSearchTool,
+    FunctionToolParam,
+    ToolFinanceSearchTool,
+    ToolSandboxTool,
+    ToolMcpTool,
 ]
 
 

src/perplexity/types/response_stream_chunk.py

@@ -178,6 +178,10 @@ class OutputItemAddedEvent(BaseModel):
     """
 
     item: OutputItem
+    """
+    One item in the response output: an assistant message, retrieved tool results,
+    or a record of a tool call.
+    """
 
     output_index: int
 
@@ -195,6 +199,10 @@ class OutputItemDoneEvent(BaseModel):
     """
 
     item: OutputItem
+    """
+    One item in the response output: an assistant message, retrieved tool results,
+    or a record of a tool call.
+    """
 
     output_index: int