async_openai/types/
mcp.rs

1use derive_builder::Builder;
2use serde::{Deserialize, Serialize};
3
4use crate::error::OpenAIError;
5
6#[derive(Debug, Serialize, Deserialize, Clone, PartialEq, Eq)]
7#[serde(rename_all = "snake_case")]
8pub enum McpToolConnectorId {
9    ConnectorDropbox,
10    ConnectorGmail,
11    ConnectorGooglecalendar,
12    ConnectorGoogledrive,
13    ConnectorMicrosoftteams,
14    ConnectorOutlookcalendar,
15    ConnectorOutlookemail,
16    ConnectorSharepoint,
17}
18
19#[derive(Debug, Serialize, Deserialize, Clone, Builder, PartialEq, Default)]
20#[builder(
21    name = "MCPToolArgs",
22    pattern = "mutable",
23    setter(into, strip_option),
24    default
25)]
26#[builder(build_fn(error = "OpenAIError"))]
27pub struct MCPTool {
28    /// A label for this MCP server, used to identify it in tool calls.
29    pub server_label: String,
30
31    /// List of allowed tool names or a filter object.
32    #[serde(skip_serializing_if = "Option::is_none")]
33    pub allowed_tools: Option<MCPToolAllowedTools>,
34
35    /// An OAuth access token that can be used with a remote MCP server, either with a custom MCP
36    /// server URL or a service connector. Your application must handle the OAuth authorization
37    /// flow and provide the token here.
38    #[serde(skip_serializing_if = "Option::is_none")]
39    pub authorization: Option<String>,
40
41    /// Identifier for service connectors, like those available in ChatGPT. One of `server_url` or
42    /// `connector_id` must be provided. Learn more about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors).
43    ///
44    /// Currently supported `connector_id` values are:
45    /// - Dropbox: `connector_dropbox`
46    /// - Gmail: `connector_gmail`
47    /// - Google Calendar: `connector_googlecalendar`
48    /// - Google Drive: `connector_googledrive`
49    /// - Microsoft Teams: `connector_microsoftteams`
50    /// - Outlook Calendar: `connector_outlookcalendar`
51    /// - Outlook Email: `connector_outlookemail`
52    /// - SharePoint: `connector_sharepoint`
53    #[serde(skip_serializing_if = "Option::is_none")]
54    pub connector_id: Option<McpToolConnectorId>,
55
56    /// Optional HTTP headers to send to the MCP server. Use for authentication or other purposes.
57    #[serde(skip_serializing_if = "Option::is_none")]
58    pub headers: Option<serde_json::Value>,
59
60    /// Specify which of the MCP server's tools require approval.
61    #[serde(skip_serializing_if = "Option::is_none")]
62    pub require_approval: Option<MCPToolRequireApproval>,
63
64    /// Optional description of the MCP server, used to provide more context.
65    #[serde(skip_serializing_if = "Option::is_none")]
66    pub server_description: Option<String>,
67
68    /// The URL for the MCP server. One of `server_url` or `connector_id` must be provided.
69    #[serde(skip_serializing_if = "Option::is_none")]
70    pub server_url: Option<String>,
71}
72
73#[derive(Debug, Serialize, Deserialize, Clone, PartialEq)]
74#[serde(untagged)]
75pub enum MCPToolAllowedTools {
76    /// A string array of allowed tool names
77    List(Vec<String>),
78    /// A filter object to specify which tools are allowed.
79    Filter(MCPToolFilter),
80}
81
82#[derive(Debug, Serialize, Deserialize, Clone, PartialEq)]
83pub struct MCPToolFilter {
84    /// Indicates whether or not a tool modifies data or is read-only.
85    /// If an MCP server is annotated with [readOnlyHint](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint),
86    /// it will match this filter.
87    #[serde(skip_serializing_if = "Option::is_none")]
88    pub read_only: Option<bool>,
89    /// List of allowed tool names.
90    #[serde(skip_serializing_if = "Option::is_none")]
91    pub tool_names: Option<Vec<String>>,
92}
93
94/// Approval policy or filter for MCP tools.
95#[derive(Debug, Serialize, Deserialize, Clone, PartialEq)]
96#[serde(untagged)]
97pub enum MCPToolRequireApproval {
98    /// Specify which of the MCP server's tools require approval. Can be
99    /// `always`, `never`, or a filter object associated with tools
100    /// that require approval.
101    Filter(MCPToolApprovalFilter),
102    /// Specify a single approval policy for all tools. One of `always` or
103    /// `never`. When set to `always`, all tools will require approval. When
104    /// set to `never`, all tools will not require approval.
105    ApprovalSetting(MCPToolApprovalSetting),
106}
107
108#[derive(Debug, Serialize, Deserialize, Clone, PartialEq)]
109#[serde(rename_all = "lowercase")]
110pub enum MCPToolApprovalSetting {
111    Always,
112    Never,
113}
114
115#[derive(Debug, Serialize, Deserialize, Clone, PartialEq)]
116pub struct MCPToolApprovalFilter {
117    /// A list of tools that always require approval.
118    #[serde(skip_serializing_if = "Option::is_none")]
119    pub always: Option<MCPToolFilter>,
120    /// A list of tools that never require approval.
121    #[serde(skip_serializing_if = "Option::is_none")]
122    pub never: Option<MCPToolFilter>,
123}
124
125#[derive(Debug, Serialize, Deserialize, Clone, PartialEq)]
126pub struct MCPListToolsTool {
127    /// The JSON schema describing the tool's input.
128    pub input_schema: serde_json::Value,
129    /// The name of the tool.
130    pub name: String,
131    /// Additional annotations about the tool.
132    #[serde(skip_serializing_if = "Option::is_none")]
133    pub annotations: Option<serde_json::Value>,
134    /// The description of the tool.
135    #[serde(skip_serializing_if = "Option::is_none")]
136    pub description: Option<String>,
137}
138
139// MCPToolRequireApproval ergonomics
140
141impl From<MCPToolApprovalSetting> for MCPToolRequireApproval {
142    fn from(setting: MCPToolApprovalSetting) -> Self {
143        MCPToolRequireApproval::ApprovalSetting(setting)
144    }
145}
146
147impl From<MCPToolApprovalFilter> for MCPToolRequireApproval {
148    fn from(filter: MCPToolApprovalFilter) -> Self {
149        MCPToolRequireApproval::Filter(filter)
150    }
151}
152
153// MCPToolAllowedTools ergonomics
154
155impl From<MCPToolFilter> for MCPToolAllowedTools {
156    fn from(filter: MCPToolFilter) -> Self {
157        MCPToolAllowedTools::Filter(filter)
158    }
159}
160
161impl From<Vec<String>> for MCPToolAllowedTools {
162    fn from(tools: Vec<String>) -> Self {
163        MCPToolAllowedTools::List(tools)
164    }
165}
166
167impl From<Vec<&str>> for MCPToolAllowedTools {
168    fn from(tools: Vec<&str>) -> Self {
169        MCPToolAllowedTools::List(tools.into_iter().map(|s| s.to_string()).collect())
170    }
171}
172
173impl From<&[&str]> for MCPToolAllowedTools {
174    fn from(tools: &[&str]) -> Self {
175        MCPToolAllowedTools::List(tools.iter().map(|s| s.to_string()).collect())
176    }
177}
178
179impl<const N: usize> From<[&str; N]> for MCPToolAllowedTools {
180    fn from(tools: [&str; N]) -> Self {
181        MCPToolAllowedTools::List(tools.iter().map(|s| s.to_string()).collect())
182    }
183}
184
185impl From<&Vec<String>> for MCPToolAllowedTools {
186    fn from(tools: &Vec<String>) -> Self {
187        MCPToolAllowedTools::List(tools.clone())
188    }
189}
190
191impl From<&Vec<&str>> for MCPToolAllowedTools {
192    fn from(tools: &Vec<&str>) -> Self {
193        MCPToolAllowedTools::List(tools.iter().map(|s| s.to_string()).collect())
194    }
195}
196
197impl From<&str> for MCPToolAllowedTools {
198    fn from(tool: &str) -> Self {
199        MCPToolAllowedTools::List(vec![tool.to_string()])
200    }
201}
202
203impl From<String> for MCPToolAllowedTools {
204    fn from(tool: String) -> Self {
205        MCPToolAllowedTools::List(vec![tool])
206    }
207}
async_openai/types/mcp.rs

async_openai/types/
mcp.rs
