feat(api): Add connectors support for MCP tool

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 119
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai%2Fopenai-4bcdfe525558e67a09b32dec7a573e87b94bab47db3951eb4a86a4dafb60296c.yml
-openapi_spec_hash: 49e7e46bfe9f61b7b7a60e36840c0cd7
-config_hash: e4514526ae01126a61f9b6c14a351737
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai%2Fopenai-ddbdf9343316047e8a773c54fb24e4a8d225955e202a1888fde6f9c8898ebf98.yml
+openapi_spec_hash: 9802f6dd381558466c897f6e387e06ca
+config_hash: fe0ea26680ac2075a6cd66416aefe7db

src/openai/types/responses/tool.py

@@ -15,7 +15,7 @@
     "Tool",
     "Mcp",
     "McpAllowedTools",
-    "McpAllowedToolsMcpAllowedToolsFilter",
+    "McpAllowedToolsMcpToolFilter",
     "McpRequireApproval",
     "McpRequireApprovalMcpToolApprovalFilter",
     "McpRequireApprovalMcpToolApprovalFilterAlways",
@@ -29,30 +29,54 @@
 ]
 
 
-class McpAllowedToolsMcpAllowedToolsFilter(BaseModel):
+class McpAllowedToolsMcpToolFilter(BaseModel):
+    read_only: Optional[bool] = None
+    """Indicates whether or not a tool modifies data or is read-only.
+
+    If an MCP server is
+    [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint),
+    it will match this filter.
+    """
+
     tool_names: Optional[List[str]] = None
     """List of allowed tool names."""
 
 
-McpAllowedTools: TypeAlias = Union[List[str], McpAllowedToolsMcpAllowedToolsFilter, None]
+McpAllowedTools: TypeAlias = Union[List[str], McpAllowedToolsMcpToolFilter, None]
 
 
 class McpRequireApprovalMcpToolApprovalFilterAlways(BaseModel):
+    read_only: Optional[bool] = None
+    """Indicates whether or not a tool modifies data or is read-only.
+
+    If an MCP server is
+    [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint),
+    it will match this filter.
+    """
+
     tool_names: Optional[List[str]] = None
-    """List of tools that require approval."""
+    """List of allowed tool names."""
 
 
 class McpRequireApprovalMcpToolApprovalFilterNever(BaseModel):
+    read_only: Optional[bool] = None
+    """Indicates whether or not a tool modifies data or is read-only.
+
+    If an MCP server is
+    [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint),
+    it will match this filter.
+    """
+
     tool_names: Optional[List[str]] = None
-    """List of tools that do not require approval."""
+    """List of allowed tool names."""
 
 
 class McpRequireApprovalMcpToolApprovalFilter(BaseModel):
     always: Optional[McpRequireApprovalMcpToolApprovalFilterAlways] = None
-    """A list of tools that always require approval."""
+    """A filter object to specify which tools are allowed."""
 
     never: Optional[McpRequireApprovalMcpToolApprovalFilterNever] = None
-    """A list of tools that never require approval."""
+    """A filter object to specify which tools are allowed."""
 
 
 McpRequireApproval: TypeAlias = Union[McpRequireApprovalMcpToolApprovalFilter, Literal["always", "never"], None]
@@ -62,15 +86,49 @@ class Mcp(BaseModel):
     server_label: str
     """A label for this MCP server, used to identify it in tool calls."""
 
-    server_url: str
-    """The URL for the MCP server."""
-
     type: Literal["mcp"]
     """The type of the MCP tool. Always `mcp`."""
 
     allowed_tools: Optional[McpAllowedTools] = None
     """List of allowed tool names or a filter object."""
 
+    authorization: Optional[str] = None
+    """
+    An OAuth access token that can be used with a remote MCP server, either with a
+    custom MCP server URL or a service connector. Your application must handle the
+    OAuth authorization flow and provide the token here.
+    """
+
+    connector_id: Optional[
+        Literal[
+            "connector_dropbox",
+            "connector_gmail",
+            "connector_googlecalendar",
+            "connector_googledrive",
+            "connector_microsoftteams",
+            "connector_outlookcalendar",
+            "connector_outlookemail",
+            "connector_sharepoint",
+        ]
+    ] = None
+    """Identifier for service connectors, like those available in ChatGPT.
+
+    One of `server_url` or `connector_id` must be provided. Learn more about service
+    connectors
+    [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors).
+
+    Currently supported `connector_id` values are:
+
+    - Dropbox: `connector_dropbox`
+    - Gmail: `connector_gmail`
+    - Google Calendar: `connector_googlecalendar`
+    - Google Drive: `connector_googledrive`
+    - Microsoft Teams: `connector_microsoftteams`
+    - Outlook Calendar: `connector_outlookcalendar`
+    - Outlook Email: `connector_outlookemail`
+    - SharePoint: `connector_sharepoint`
+    """
+
     headers: Optional[Dict[str, str]] = None
     """Optional HTTP headers to send to the MCP server.
 
@@ -83,6 +141,12 @@ class Mcp(BaseModel):
     server_description: Optional[str] = None
     """Optional description of the MCP server, used to provide more context."""
 
+    server_url: Optional[str] = None
+    """The URL for the MCP server.
+
+    One of `server_url` or `connector_id` must be provided.
+    """
+
 
 class CodeInterpreterContainerCodeInterpreterToolAuto(BaseModel):
     type: Literal["auto"]

src/openai/types/responses/tool_param.py

@@ -16,7 +16,7 @@
     "ToolParam",
     "Mcp",
     "McpAllowedTools",
-    "McpAllowedToolsMcpAllowedToolsFilter",
+    "McpAllowedToolsMcpToolFilter",
     "McpRequireApproval",
     "McpRequireApprovalMcpToolApprovalFilter",
     "McpRequireApprovalMcpToolApprovalFilterAlways",
@@ -30,30 +30,54 @@
 ]
 
 
-class McpAllowedToolsMcpAllowedToolsFilter(TypedDict, total=False):
+class McpAllowedToolsMcpToolFilter(TypedDict, total=False):
+    read_only: bool
+    """Indicates whether or not a tool modifies data or is read-only.
+
+    If an MCP server is
+    [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint),
+    it will match this filter.
+    """
+
     tool_names: List[str]
     """List of allowed tool names."""
 
 
-McpAllowedTools: TypeAlias = Union[List[str], McpAllowedToolsMcpAllowedToolsFilter]
+McpAllowedTools: TypeAlias = Union[List[str], McpAllowedToolsMcpToolFilter]
 
 
 class McpRequireApprovalMcpToolApprovalFilterAlways(TypedDict, total=False):
+    read_only: bool
+    """Indicates whether or not a tool modifies data or is read-only.
+
+    If an MCP server is
+    [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint),
+    it will match this filter.
+    """
+
     tool_names: List[str]
-    """List of tools that require approval."""
+    """List of allowed tool names."""
 
 
 class McpRequireApprovalMcpToolApprovalFilterNever(TypedDict, total=False):
+    read_only: bool
+    """Indicates whether or not a tool modifies data or is read-only.
+
+    If an MCP server is
+    [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint),
+    it will match this filter.
+    """
+
     tool_names: List[str]
-    """List of tools that do not require approval."""
+    """List of allowed tool names."""
 
 
 class McpRequireApprovalMcpToolApprovalFilter(TypedDict, total=False):
     always: McpRequireApprovalMcpToolApprovalFilterAlways
-    """A list of tools that always require approval."""
+    """A filter object to specify which tools are allowed."""
 
     never: McpRequireApprovalMcpToolApprovalFilterNever
-    """A list of tools that never require approval."""
+    """A filter object to specify which tools are allowed."""
 
 
 McpRequireApproval: TypeAlias = Union[McpRequireApprovalMcpToolApprovalFilter, Literal["always", "never"]]
@@ -63,15 +87,47 @@ class Mcp(TypedDict, total=False):
     server_label: Required[str]
     """A label for this MCP server, used to identify it in tool calls."""
 
-    server_url: Required[str]
-    """The URL for the MCP server."""
-
     type: Required[Literal["mcp"]]
     """The type of the MCP tool. Always `mcp`."""
 
     allowed_tools: Optional[McpAllowedTools]
     """List of allowed tool names or a filter object."""
 
+    authorization: str
+    """
+    An OAuth access token that can be used with a remote MCP server, either with a
+    custom MCP server URL or a service connector. Your application must handle the
+    OAuth authorization flow and provide the token here.
+    """
+
+    connector_id: Literal[
+        "connector_dropbox",
+        "connector_gmail",
+        "connector_googlecalendar",
+        "connector_googledrive",
+        "connector_microsoftteams",
+        "connector_outlookcalendar",
+        "connector_outlookemail",
+        "connector_sharepoint",
+    ]
+    """Identifier for service connectors, like those available in ChatGPT.
+
+    One of `server_url` or `connector_id` must be provided. Learn more about service
+    connectors
+    [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors).
+
+    Currently supported `connector_id` values are:
+
+    - Dropbox: `connector_dropbox`
+    - Gmail: `connector_gmail`
+    - Google Calendar: `connector_googlecalendar`
+    - Google Drive: `connector_googledrive`
+    - Microsoft Teams: `connector_microsoftteams`
+    - Outlook Calendar: `connector_outlookcalendar`
+    - Outlook Email: `connector_outlookemail`
+    - SharePoint: `connector_sharepoint`
+    """
+
     headers: Optional[Dict[str, str]]
     """Optional HTTP headers to send to the MCP server.
 
@@ -84,6 +140,12 @@ class Mcp(TypedDict, total=False):
     server_description: str
     """Optional description of the MCP server, used to provide more context."""
 
+    server_url: str
+    """The URL for the MCP server.
+
+    One of `server_url` or `connector_id` must be provided.
+    """
+
 
 class CodeInterpreterContainerCodeInterpreterToolAuto(TypedDict, total=False):
     type: Required[Literal["auto"]]