Skip to content

Switchyard lets LLM applications route traffic across models and providers while preserving native OpenAI and Anthropic API compatibility - enabling flexible model selection, benchmarking, and cost/performance optimization.

Rust

feat(protocol): represent MCP tools and backend history (#993)

David Gardnerab7d26443899
diff --git a/crates/protocol/README.md b/crates/protocol/README.md
index a5b5b9f57..83a1eff17 100644
--- a/crates/protocol/README.md
+++ b/crates/protocol/README.md
@@ -17,7 +17,7 @@ serde_json = "1"
| Area | Types |
|---|---|
| Conversation | [`LlmRequest`], [`Message`], [`InstructionBlock`], [`ContentBlock`] |
-| Tools | [`ToolDefinition`], [`ToolChoice`], [`ToolCall`], [`ToolResult`] |
+| Tools | [`Tool`], [`ToolDefinition`], [`McpToolset`], [`McpToolConfig`], [`McpContent`], [`ToolChoice`], [`ToolCall`], [`ToolResult`] |
| Response | [`AggLlmResponse`], [`ResponseOutput`], [`Usage`], [`StopReason`] |
| Streaming | [`LlmResponse`], [`LlmResponseStream`], [`LlmResponseStreamEvent`], [`LlmResponseChunk`], [`ProviderStreamEvent`] |
| Envelope | [`Request`], [`Response`], [`Metadata`] |
@@ -75,7 +75,7 @@ let request = Request {
"required": ["name"]
}),
strict: Some(true),
- }],
+ }.into()],
tool_choice: Some(ToolChoice::Auto),
sampling: SamplingParams {
temperature: Some(0.2),
@@ -96,7 +96,7 @@ let request = Request {
..Request::default()
};
-assert_eq!(request.llm_request.tools[0].name, "lookup_metric");
+assert_eq!(request.llm_request.tools[0].function().map(|tool| tool.name.as_str()), Some("lookup_metric"));
```
## Response forms
diff --git a/crates/protocol/src/llm.rs b/crates/protocol/src/llm.rs
index cef8d5980..a284136b9 100644
--- a/crates/protocol/src/llm.rs
+++ b/crates/protocol/src/llm.rs
@@ -2,8 +2,13 @@
// SPDX-License-Identifier: Apache-2.0
//! Provider-neutral conversation types shared by routing, clients, and translation.
+//!
+//! Debug output redacts MCP URLs and authorization tokens and hides raw provider tool definitions,
+//! extensions, and preserved bodies. Conversation content, including unknown provider
+//! blocks, remains visible and may contain secrets. Serialization retains the stored values.
use std::collections::BTreeMap;
+use std::fmt;
use serde::{Deserialize, Serialize};
use serde_json::{Map, Value};
@@ -116,6 +121,8 @@ pub enum ContentBlock {
ToolCall(ToolCall),
/// Result of an earlier tool invocation.
ToolResult(ToolResult),
+ /// MCP activity executed by the backend, rather than by the calling agent.
+ Mcp(McpContent),
/// Provider refusal content.
Refusal {
/// Human-readable refusal text.
@@ -226,6 +233,198 @@ pub struct ToolDefinition {
pub strict: Option<bool>,
}
+/// A tool available to the model, in catalog order.
+#[derive(Clone, PartialEq, Serialize)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum Tool {
+ /// A remote MCP server and the tools it exposes.
+ Mcp(McpToolset),
+ /// A definition without a supported neutral representation.
+ Provider {
+ /// Source wire format; this definition is only replayed in that format.
+ provider: FormatId,
+ /// Complete provider definition.
+ raw: Value,
+ },
+ /// An agent-executed function. Its JSON retains the existing flat definition shape.
+ #[serde(untagged)]
+ Function(ToolDefinition),
+}
+
+impl<'de> Deserialize<'de> for Tool {
+ fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+ where
+ D: serde::Deserializer<'de>,
+ {
+ // Keep these variants and the conversion below in sync with Tool.
+ #[derive(Deserialize)]
+ #[serde(tag = "type", rename_all = "snake_case")]
+ enum TaggedTool {
+ Mcp(McpToolset),
+ Provider { provider: FormatId, raw: Value },
+ Function(ToolDefinition),
+ }
+
+ let value = Value::deserialize(deserializer)?;
+ // Only definitions without a type use the legacy function shape. A malformed
+ // tagged definition must fail instead of falling back to a function.
+ if value.get("type").is_none() {
+ return serde_json::from_value(value)
+ .map(Self::Function)
+ .map_err(serde::de::Error::custom);
+ }
+ let tool = serde_json::from_value(value).map_err(serde::de::Error::custom)?;
+ Ok(match tool {
+ TaggedTool::Mcp(mcp) => Self::Mcp(mcp),
+ TaggedTool::Provider { provider, raw } => Self::Provider { provider, raw },
+ TaggedTool::Function(function) => Self::Function(function),
+ })
+ }
+}
+
+impl fmt::Debug for Tool {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ match self {
+ Self::Function(definition) => f.debug_tuple("Function").field(definition).finish(),
+ Self::Mcp(mcp) => f.debug_tuple("Mcp").field(mcp).finish(),
+ // Raw provider definitions can contain credentials without normalized fields.
+ Self::Provider { provider, .. } => f
+ .debug_struct("Provider")
+ .field("provider", provider)
+ .finish_non_exhaustive(),
+ }
+ }
+}
+
+impl From<ToolDefinition> for Tool {
+ fn from(definition: ToolDefinition) -> Self {
+ Self::Function(definition)
+ }
+}
+
+impl Tool {
+ /// Returns the function definition, if this is an agent-executed function.
+ pub fn function(&self) -> Option<&ToolDefinition> {
+ match self {
+ Self::Function(definition) => Some(definition),
+ _ => None,
+ }
+ }
+}
+
+/// Configuration for a URL-based remote MCP toolset.
+///
+/// This type covers the supported neutral settings. Definitions with additional settings,
+/// such as Responses headers, server descriptions, or conditional approval rules, belong
+/// in [`Tool::Provider`] with the complete original definition.
+#[derive(Clone, PartialEq, Serialize, Deserialize)]
+pub struct McpToolset {
+ /// Server identity used by MCP calls.
+ pub name: String,
+ /// Remote MCP endpoint.
+ pub url: String,
+ /// Credential sent to the MCP server, when supplied.
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub authorization_token: Option<String>,
+ /// Defaults for tools without a per-tool setting in `configs`.
+ #[serde(default, skip_serializing_if = "McpToolConfig::is_empty")]
+ pub default_config: McpToolConfig,
+ /// Per-tool settings, keyed by tool name. Each omitted setting inherits
+ /// from `default_config`, then falls back to the provider's default.
+ #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
+ pub configs: BTreeMap<String, McpToolConfig>,
+ /// Whether all calls require approval (`true`) or none do (`false`).
+ /// Absence retains provider defaults. Definitions with conditional approval rules
+ /// are stored in full as [`Tool::Provider`], rather than as this type.
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub require_approval: Option<bool>,
+}
+
+impl fmt::Debug for McpToolset {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ let Self {
+ name,
+ url: _,
+ authorization_token,
+ default_config,
+ configs,
+ require_approval,
+ } = self;
+ f.debug_struct("McpToolset")
+ .field("name", name)
+ // Credentials can appear in any part of the URL, including its path.
+ .field("url", &"[REDACTED]")
+ .field(
+ "authorization_token",
+ &authorization_token.as_ref().map(|_| "[REDACTED]"),
+ )
+ .field("default_config", default_config)
+ .field("configs", configs)
+ .field("require_approval", require_approval)
+ .finish()
+ }
+}
+
+/// Settings for an individual MCP tool or the defaults for a toolset.
+#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
+pub struct McpToolConfig {
+ /// Whether the tool is available for the model to call.
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub enabled: Option<bool>,
+ /// Whether the tool definition is loaded through tool search instead of initially.
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub defer_loading: Option<bool>,
+}
+
+impl McpToolConfig {
+ fn is_empty(&self) -> bool {
+ self.enabled.is_none() && self.defer_loading.is_none()
+ }
+}
+
+/// A tool discovered on an MCP server.
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+pub struct McpListedTool {
+ /// Tool name as exposed by the server.
+ pub name: String,
+ /// Human-readable tool description, when supplied.
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub description: Option<String>,
+ /// JSON Schema describing accepted arguments.
+ pub input_schema: Value,
+ /// Additional tool metadata reported by the server.
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub annotations: Option<Value>,
+}
+
+/// MCP discovery and execution history. Results reference the matching call's server identity.
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case")]
+pub enum McpContent {
+ /// Tools discovered on a server at this point in the conversation.
+ Listing {
+ /// Identity of the MCP server.
+ server_name: String,
+ /// Listing identifier, when supplied by the provider.
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ id: Option<String>,
+ /// Discovered tools in the order reported by the server.
+ tools: Vec<McpListedTool>,
+ /// Discovery failure, when reported. An empty tool list alone is not a failure.
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ error: Option<String>,
+ },
+ /// A call executed by the backend's MCP client.
+ Call {
+ /// Identity of the MCP server.
+ server_name: String,
+ /// Ordinary call ID, name, and arguments.
+ call: ToolCall,
+ },
+ /// Output from a backend-executed MCP call.
+ Result(ToolResult),
+}
+
/// Normalized tool choice policy.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(tag = "type", content = "data", rename_all = "snake_case")]
@@ -279,7 +478,7 @@ pub struct ReasoningParams {
}
/// Provider-specific fields that do not have first-class conversation fields.
-#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
+#[derive(Clone, Default, PartialEq, Serialize, Deserialize)]
#[serde(default)]
pub struct ProviderExtensions {
/// Provider fields keyed by their original wire names.
@@ -289,13 +488,22 @@ pub struct ProviderExtensions {
pub fields: Map<String, Value>,
}
+// Extension values can include credentials or embedded original request bodies.
+impl fmt::Debug for ProviderExtensions {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ f.debug_struct("ProviderExtensions")
+ .field("field_count", &self.fields.len())
+ .finish_non_exhaustive()
+ }
+}
+
/// Exact source payloads retained for lossless same-format round trips.
///
/// Translation's default preservation policy prefers a stored same-format body
/// over reconstructing one from normalized fields. A caller that mutates the IR
/// must clear the corresponding entry or use a policy with preservation disabled
/// when those mutations must be encoded.
-#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
+#[derive(Clone, Default, PartialEq, Serialize, Deserialize)]
#[serde(default)]
pub struct PreservationMetadata {
/// Original request bodies keyed by source format.
@@ -304,6 +512,16 @@ pub struct PreservationMetadata {
pub responses: BTreeMap<FormatId, Value>,
}
+// Original payloads can contain credentials even when normalized fields redact them.
+impl fmt::Debug for PreservationMetadata {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ f.debug_struct("PreservationMetadata")
+ .field("request_formats", &self.requests.keys())
+ .field("response_formats", &self.responses.keys())
+ .finish_non_exhaustive()
+ }
+}
+
/// Normalized request representation shared by Switchyard components.
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
#[serde(default)]
@@ -318,7 +536,7 @@ pub struct LlmRequest {
/// Ordered conversation messages.
pub messages: Vec<Message>,
/// Tools available to the model.
- pub tools: Vec<ToolDefinition>,
+ pub tools: Vec<Tool>,
/// Policy controlling model tool selection.
pub tool_choice: Option<ToolChoice>,
/// Common sampling controls.
@@ -514,4 +732,123 @@ mod tests {
);
Ok(())
}
+
+ #[test]
+ fn tool_deserialization_rejects_invalid_tagged_definitions() {
+ for definition in [
+ json!({"type": "mcp", "name": "inv", "parameters": {}}),
+ json!({"type": "provider", "provider": "x", "name": "n", "parameters": {}}),
+ json!({"type": "unknown", "name": "n", "parameters": {}}),
+ json!({"type": null, "name": "n", "parameters": {}}),
+ ] {
+ assert!(serde_json::from_value::<Tool>(definition).is_err());
+ }
+ let error = serde_json::from_value::<Tool>(json!({
+ "type": "mcp", "name": "inv", "url": "https://example.invalid/mcp",
+ "authorization_token": 5, "parameters": {}
+ }))
+ .expect_err("an invalid credential must not become a function")
+ .to_string();
+ assert!(error.contains("string"), "field error was lost: {error}");
+ }
+
+ #[test]
+ fn tool_catalog_preserves_function_json_and_backend_history() -> Result<(), serde_json::Error> {
+ let function = json!({"name": "lookup", "description": null, "parameters": {"type": "object"}, "strict": null});
+ let definitions = json!([
+ function,
+ {"type": "mcp", "name": "inventory", "url": "https://example.invalid/mcp", "require_approval": false},
+ {"type": "provider", "provider": "openai_responses", "raw": {"type": "mcp", "connector_id": "connector_example", "server_label": "example"}},
+ {
+ "type": "mcp", "name": "configured", "url": "https://example.invalid/mcp",
+ "default_config": {"enabled": false, "defer_loading": true},
+ "configs": {"lookup": {"enabled": true}, "search": {"defer_loading": false}}
+ }
+ ]);
+ let tools: Vec<Tool> = serde_json::from_value(definitions.clone())?;
+ assert!(matches!(&tools[0], Tool::Function(_)));
+ assert!(matches!(&tools[1], Tool::Mcp(_)));
+ assert!(matches!(&tools[2], Tool::Provider { .. }));
+ assert_eq!(serde_json::to_value(&tools)?, definitions);
+ let explicit_function: Tool = serde_json::from_value(json!({
+ "type": "function", "name": "lookup", "parameters": {"type": "object"}
+ }))?;
+ assert_eq!(explicit_function, tools[0]);
+
+ let history = json!([
+ {
+ "type": "mcp", "kind": "listing", "server_name": "inventory",
+ "id": "listing_1",
+ "tools": [{
+ "name": "lookup", "description": "Look up stock",
+ "input_schema": {"type": "object"},
+ "annotations": {"readOnlyHint": true}
+ }]
+ },
+ {"type": "mcp", "kind": "listing", "server_name": "empty", "tools": []},
+ {
+ "type": "mcp", "kind": "listing", "server_name": "unavailable",
+ "tools": [], "error": "Server unavailable"
+ },
+ {
+ "type": "mcp", "kind": "call", "server_name": "inventory",
+ "call": {"id": "call_1", "name": "lookup", "arguments": {}}
+ },
+ {
+ "type": "mcp", "kind": "result", "tool_call_id": "call_1",
+ "content": [{"type": "text", "text": "in stock"}], "is_error": false
+ }
+ ]);
+ let content: Vec<ContentBlock> = serde_json::from_value(history.clone())?;
+ assert_eq!(serde_json::to_value(&content)?, history);
+ Ok(())
+ }
+
+ #[test]
+ fn mcp_credentials_are_omitted_from_debug() -> Result<(), serde_json::Error> {
+ let token = "synthetic-mcp-debug-secret";
+ let url_secret = "synthetic-mcp-url-secret";
+ let url = format!("https://example.invalid/mcp?api_key={url_secret}");
+ let mcp: McpToolset = serde_json::from_value(json!({
+ "name": "inventory", "url": url,
+ "authorization_token": token
+ }))?;
+ let raw = json!({"mcp_servers": [{"authorization_token": token}]});
+ let mut request = LlmRequest {
+ tools: vec![
+ Tool::Mcp(mcp.clone()),
+ Tool::Provider {
+ provider: "openai_responses".into(),
+ raw: json!({"type": "mcp", "authorization": token}),
+ },
+ ],
+ ..LlmRequest::default()
+ };
+ request
+ .preservation
+ .requests
+ .insert("anthropic_messages".into(), raw.clone());
+ request.extensions.fields.insert("metadata".into(), raw);
+ let serialized = serde_json::to_value(&request)?;
+ for debug in [
+ format!("{mcp:?}"),
+ format!("{mcp:#?}"),
+ format!("{:?}", request.tools),
+ format!("{:?}", request.extensions),
+ format!("{:?}", request.preservation),
+ format!("{request:?}"),
+ format!("{request:#?}"),
+ ] {
+ assert!(!debug.contains(token), "Debug exposed an MCP credential");
+ assert!(
+ !debug.contains(url_secret),
+ "Debug exposed an MCP URL secret"
+ );
+ }
+ assert_eq!(serde_json::to_value(&request)?, serialized);
+ assert_eq!(serialized["tools"][0]["url"], url);
+ assert_eq!(serialized["tools"][0]["authorization_token"], token);
+ assert_eq!(serialized["tools"][1]["raw"]["authorization"], token);
+ Ok(())
+ }
}
diff --git a/crates/protocol/src/stream.rs b/crates/protocol/src/stream.rs
index c59a66f77..428d01a0f 100644
--- a/crates/protocol/src/stream.rs
+++ b/crates/protocol/src/stream.rs
@@ -214,7 +214,7 @@ impl AggLlmResponse {
///
/// This conversion is lossy: only text, reasoning, and tool-call content has
/// a synthetic chunk representation. Refusals, tool results, media, files,
- /// unknown blocks, response extensions, and preservation metadata are omitted.
+ /// MCP activity, unknown blocks, response extensions, and preservation metadata are omitted.
pub fn into_stream(self) -> LlmResponseStream {
let mut chunks: Vec<LlmResponseChunk> = Vec::new();
chunks.push(LlmResponseChunk::MessageStart {
@@ -255,8 +255,7 @@ impl AggLlmResponse {
});
tool_call_index += 1;
}
- // Other variants (Image, ToolResult, Refusal, etc.) don't have
- // a streaming chunk representation and don't appear in assistant outputs.
+ // Other variants, including backend MCP activity, have no synthetic chunks.
_ => {}
}
}
diff --git a/crates/switchyard-translation/src/codecs/anthropic/buffered.rs b/crates/switchyard-translation/src/codecs/anthropic/buffered.rs
index de6d7c210..88aa8a324 100644
--- a/crates/switchyard-translation/src/codecs/anthropic/buffered.rs
+++ b/crates/switchyard-translation/src/codecs/anthropic/buffered.rs
@@ -20,7 +20,7 @@ use crate::format::{FormatId, WireFormat};
use crate::llm::{
AggLlmResponse, ContentBlock, FileSource, ImageSource, InstructionBlock, LlmRequest,
MediaSource, Message, OutputParams, ProviderExtensions, ReasoningParams, ResponseOutput, Role,
- SamplingParams, StopReason, ToolCall, ToolChoice, ToolDefinition, ToolResult, Usage,
+ SamplingParams, StopReason, Tool, ToolCall, ToolChoice, ToolDefinition, ToolResult, Usage,
};
use crate::policy::{DeterministicIdPolicy, TranslationPolicy};
use crate::util::{
@@ -154,7 +154,10 @@ impl FormatCodec for AnthropicMessagesCodec {
request.messages.push(Message { role, content });
}
}
- request.tools = decode_anthropic_tools(body.get("tools"));
+ request.tools = decode_anthropic_tools(body.get("tools"))
+ .into_iter()
+ .map(Tool::from)
+ .collect();
request.tool_choice = body.get("tool_choice").map(decode_anthropic_tool_choice);
request.extensions.fields = provider_extensions(
body,
@@ -245,7 +248,7 @@ impl FormatCodec for AnthropicMessagesCodec {
);
if !tools.is_empty() {
- body.insert("tools".to_string(), encode_anthropic_tools(tools));
+ body.insert("tools".to_string(), encode_anthropic_tools(tools)?);
}
let parallel_tool_calls = request
.extensions
@@ -1118,6 +1121,11 @@ fn encode_one_anthropic_block(block: &ContentBlock) -> Result<Vec<Value>> {
}),
MediaSource::Raw(raw) => raw.clone(),
}],
+ ContentBlock::Mcp(_) => {
+ return Err(TranslationError::LossyConversion(
+ "MCP history encoding is not implemented".into(),
+ ));
+ }
ContentBlock::Unknown { raw, .. } => vec![raw.clone()],
})
}
@@ -1137,6 +1145,9 @@ fn encode_one_anthropic_tool_result_block(block: &ContentBlock) -> Result<Vec<Va
ContentBlock::Unknown { raw, .. } => {
Ok(vec![json!({"type": "text", "text": json_string(raw)})])
}
+ ContentBlock::Mcp(_) => Err(TranslationError::LossyConversion(
+ "MCP history encoding is not implemented".into(),
+ )),
ContentBlock::Reasoning { .. }
| ContentBlock::Audio { .. }
| ContentBlock::Video { .. }
@@ -1198,11 +1209,16 @@ fn ensure_anthropic_tool_input_object(arguments: Value) -> Value {
}
// Encodes normalized tool definitions into Anthropic tool JSON.
-fn encode_anthropic_tools(tools: &[ToolDefinition]) -> Value {
- Value::Array(
+fn encode_anthropic_tools(tools: &[Tool]) -> Result<Value> {
+ Ok(Value::Array(
tools
.iter()
.map(|tool| {
+ let tool = tool.function().ok_or_else(|| {
+ TranslationError::LossyConversion(
+ "MCP and provider tool encoding is not implemented".into(),
+ )
+ })?;
let mut item = json!({
"name": tool.name,
"description": tool.description.clone().unwrap_or_default(),
@@ -1211,10 +1227,10 @@ fn encode_anthropic_tools(tools: &[ToolDefinition]) -> Value {
if let Some(strict) = tool.strict {
item["strict"] = Value::Bool(strict);
}
- item
+ Ok(item)
})
- .collect(),
- )
+ .collect::<Result<_>>()?,
+ ))
}
// Encodes normalized tool choice into Anthropic tool-choice JSON.
diff --git a/crates/switchyard-translation/src/codecs/common.rs b/crates/switchyard-translation/src/codecs/common.rs
index b8e0fc20c..ddd795f80 100644
--- a/crates/switchyard-translation/src/codecs/common.rs
+++ b/crates/switchyard-translation/src/codecs/common.rs
@@ -6,7 +6,7 @@
use serde_json::{Map, Value};
use crate::error::{Result, TranslationError};
-use crate::llm::{ContentBlock, LlmRequest, ToolChoice, ToolDefinition};
+use crate::llm::{ContentBlock, LlmRequest, Tool, ToolChoice};
// Internal provenance survives mutations that invalidate exact request replay.
pub(crate) const ANTHROPIC_REQUEST_KEY: &str = "switchyard_anthropic_request";
@@ -19,7 +19,7 @@ pub(crate) fn is_anthropic_request(request: &LlmRequest) -> bool {
/// Converts an OpenAI allowed-tools policy to a restricted function list and mode.
pub(crate) fn allowed_function_tools(
request: &LlmRequest,
-) -> Result<Option<(Vec<ToolDefinition>, ToolChoice)>> {
+) -> Result<Option<(Vec<Tool>, ToolChoice)>> {
let Some(ToolChoice::Raw(choice)) = &request.tool_choice else {
return Ok(None);
};
@@ -63,7 +63,12 @@ pub(crate) fn allowed_function_tools(
}
_ => name.to_string(),
};
- if !request.tools.iter().any(|tool| tool.name == name) {
+ if !request
+ .tools
+ .iter()
+ .filter_map(Tool::function)
+ .any(|tool| tool.name == name)
+ {
return Err(error());
}
names.push(name);
@@ -73,7 +78,10 @@ pub(crate) fn allowed_function_tools(
let tools = request
.tools
.iter()
- .filter(|tool| names.contains(&tool.name))
+ .filter(|tool| {
+ tool.function()
+ .is_some_and(|tool| names.contains(&tool.name))
+ })
.cloned()
.collect();
Ok(Some((tools, mode)))
diff --git a/crates/switchyard-translation/src/codecs/openai_chat/buffered.rs b/crates/switchyard-translation/src/codecs/openai_chat/buffered.rs
index afe99c539..5c36c6d55 100644
--- a/crates/switchyard-translation/src/codecs/openai_chat/buffered.rs
+++ b/crates/switchyard-translation/src/codecs/openai_chat/buffered.rs
@@ -22,7 +22,7 @@ use crate::format::{FormatId, WireFormat};
use crate::llm::{
AggLlmResponse, ContentBlock, FileSource, ImageSource, InstructionBlock, LlmRequest,
MediaSource, Message, OutputParams, ProviderExtensions, ReasoningParams, ResponseOutput, Role,
- SamplingParams, StopReason, ToolCall, ToolChoice, ToolDefinition, ToolResult, Usage,
+ SamplingParams, StopReason, Tool, ToolCall, ToolChoice, ToolDefinition, ToolResult, Usage,
};
use crate::policy::{DeterministicIdPolicy, TranslationPolicy};
use crate::util::{
@@ -158,7 +158,10 @@ impl FormatCodec for OpenAiChatCodec {
}
}
- request.tools = decode_openai_tools(body.get("tools"), &mut diagnostics, policy)?;
+ request.tools = decode_openai_tools(body.get("tools"), &mut diagnostics, policy)?
+ .into_iter()
+ .map(Tool::from)
+ .collect();
request.tool_choice = body.get("tool_choice").map(decode_openai_tool_choice);
request.extensions.fields = provider_extensions(
body,
@@ -233,7 +236,7 @@ impl FormatCodec for OpenAiChatCodec {
body.insert("messages".to_string(), Value::Array(messages));
if !tools.is_empty() {
- body.insert("tools".to_string(), encode_openai_tools(tools));
+ body.insert("tools".to_string(), encode_openai_tools(tools)?);
if let Some(choice) = tool_choice {
body.insert("tool_choice".to_string(), encode_openai_tool_choice(choice));
}
@@ -1036,6 +1039,14 @@ pub(crate) fn encode_openai_content(
diagnostics: &mut Vec<TranslationDiagnostic>,
policy: &TranslationPolicy,
) -> Result<Value> {
+ if content
+ .iter()
+ .any(|block| matches!(block, ContentBlock::Mcp(_)))
+ {
+ return Err(TranslationError::LossyConversion(
+ "MCP history encoding is not implemented".into(),
+ ));
+ }
let has_non_text = content.iter().any(|block| {
matches!(
block,
@@ -1096,6 +1107,11 @@ pub(crate) fn encode_openai_content(
)?;
blocks.push(openai_text_part(&media_source_text(source)));
}
+ ContentBlock::Mcp(_) => {
+ return Err(TranslationError::LossyConversion(
+ "MCP history encoding is not implemented".into(),
+ ));
+ }
ContentBlock::Unknown { provider, raw } => {
reject_responses_builtin_tool_item(provider, raw, WireFormat::OpenAiChat)?;
push_lossy(
@@ -1152,11 +1168,16 @@ fn media_source_text(source: &MediaSource) -> String {
}
/// Encodes normalized tool definitions into OpenAI tool JSON.
-pub(crate) fn encode_openai_tools(tools: &[ToolDefinition]) -> Value {
- Value::Array(
+pub(crate) fn encode_openai_tools(tools: &[Tool]) -> Result<Value> {
+ Ok(Value::Array(
tools
.iter()
.map(|tool| {
+ let tool = tool.function().ok_or_else(|| {
+ TranslationError::LossyConversion(
+ "MCP and provider tool encoding is not implemented".into(),
+ )
+ })?;
let mut function = json!({
"name": tool.name,
"description": tool.description.clone().unwrap_or_default(),
@@ -1165,10 +1186,10 @@ pub(crate) fn encode_openai_tools(tools: &[ToolDefinition]) -> Value {
if let Some(strict) = tool.strict {
function["strict"] = Value::Bool(strict);
}
- json!({"type": "function", "function": function})
+ Ok(json!({"type": "function", "function": function}))
})
- .collect(),
- )
+ .collect::<Result<_>>()?,
+ ))
}
/// Encodes normalized tool choice into OpenAI Chat JSON.
diff --git a/crates/switchyard-translation/src/codecs/responses/buffered.rs b/crates/switchyard-translation/src/codecs/responses/buffered.rs
index fb970f2d9..43fab2806 100644
--- a/crates/switchyard-translation/src/codecs/responses/buffered.rs
+++ b/crates/switchyard-translation/src/codecs/responses/buffered.rs
@@ -26,7 +26,7 @@ use crate::format::{FormatId, WireFormat};
use crate::llm::{
AggLlmResponse, ContentBlock, FileSource, ImageSource, InstructionBlock, LlmRequest,
MediaSource, Message, OutputParams, ProviderExtensions, ReasoningParams, ResponseOutput, Role,
- SamplingParams, StopReason, ToolCall, ToolChoice, ToolDefinition, ToolResult, Usage,
+ SamplingParams, StopReason, Tool, ToolCall, ToolChoice, ToolDefinition, ToolResult, Usage,
};
use crate::policy::{DeterministicIdPolicy, TranslationPolicy};
use crate::util::{
@@ -114,7 +114,10 @@ impl FormatCodec for OpenAiResponsesCodec {
let mut tool_namespaces = Map::new();
let mut custom_tools = Map::new();
request.tools =
- decode_responses_tools(body.get("tools"), &mut tool_namespaces, &mut custom_tools);
+ decode_responses_tools(body.get("tools"), &mut tool_namespaces, &mut custom_tools)
+ .into_iter()
+ .map(Tool::from)
+ .collect();
// Responses-lite clients (Codex with a GPT-5 model) carry the tool definitions inside
// `input` as an `additional_tools` developer item instead of top-level `tools`. Those
// definitions are the request's tools; the item itself is kept verbatim so the request
@@ -126,11 +129,15 @@ impl FormatCodec for OpenAiResponsesCodec {
&& item.get("type").and_then(Value::as_str) == Some("additional_tools")
&& let Some(tools) = item.get("tools").and_then(Value::as_array)
{
- request.tools.extend(decode_responses_tools(
- Some(&Value::Array(tools.clone())),
- &mut tool_namespaces,
- &mut custom_tools,
- ));
+ request.tools.extend(
+ decode_responses_tools(
+ Some(&Value::Array(tools.clone())),
+ &mut tool_namespaces,
+ &mut custom_tools,
+ )
+ .into_iter()
+ .map(Tool::from),
+ );
additional_tools.extend(tools.iter().cloned());
}
}
@@ -240,7 +247,7 @@ impl FormatCodec for OpenAiResponsesCodec {
&request.tools,
crate::codex_namespaces::tool_namespaces(&request.extensions),
crate::codex_custom_tools::custom_tools(&request.extensions),
- ),
+ )?,
);
}
if let Some(choice) = &request.tool_choice
@@ -1631,6 +1638,11 @@ fn encode_responses_content(
blocks.push(json!({"type": "input_text", "text": file_source_text(source)}));
}
},
+ ContentBlock::Mcp(_) => {
+ return Err(TranslationError::LossyConversion(
+ "MCP history encoding is not implemented".into(),
+ ));
+ }
ContentBlock::Unknown { raw, .. } => {
push_lossy(
diagnostics,
@@ -1694,13 +1706,18 @@ fn responses_file_part(source: &FileSource) -> Option<Value> {
// A Responses client understands Codex containers, so a tool whose name this
// request qualified is regrouped under the container it came from.
fn encode_responses_tools(
- tools: &[ToolDefinition],
+ tools: &[Tool],
namespaces: Option<&Map<String, Value>>,
custom_tools: Option<&Map<String, Value>>,
-) -> Value {
+) -> Result<Value> {
let mut out: Vec<Value> = Vec::new();
let mut containers: Vec<(String, Vec<Value>)> = Vec::new();
for tool in tools {
+ let tool = tool.function().ok_or_else(|| {
+ TranslationError::LossyConversion(
+ "MCP and provider tool encoding is not implemented".into(),
+ )
+ })?;
// A freeform tool goes back out exactly as the client defined it.
if let Some(custom) = custom_tools.and_then(|custom| custom.get(&tool.name)) {
out.push(custom.clone());
@@ -1745,7 +1762,7 @@ fn encode_responses_tools(
"tools": children,
}));
}
- Value::Array(out)
+ Ok(Value::Array(out))
}
// Encodes normalized tool choice into Responses JSON.
diff --git a/crates/switchyard-translation/tests/request_translation.rs b/crates/switchyard-translation/tests/request_translation.rs
index 6cd696397..10445bb1e 100644
--- a/crates/switchyard-translation/tests/request_translation.rs
+++ b/crates/switchyard-translation/tests/request_translation.rs
@@ -16,6 +16,45 @@ use common::{REASONING_MODEL, normalized_policy, shell_tool_call};
type TestResult<T = ()> = std::result::Result<T, Box<dyn std::error::Error + Send + Sync>>;
+#[test]
+fn openai_chat_rejects_mcp_history_before_text_only_returns() {
+ use switchyard_translation::{LlmRequest, McpContent, Message, Role};
+
+ let engine = TranslationEngine::default();
+ for role in [Role::User, Role::Assistant] {
+ let request = LlmRequest {
+ messages: vec![Message {
+ role,
+ content: vec![
+ ContentBlock::Text {
+ text: "Keep this text".into(),
+ },
+ ContentBlock::Mcp(McpContent::Listing {
+ server_name: "inventory".into(),
+ id: None,
+ tools: Vec::new(),
+ error: None,
+ }),
+ ],
+ }],
+ ..LlmRequest::default()
+ };
+ for lossy_conversion_policy in [
+ LossyConversionPolicy::AllowWithDiagnostics,
+ LossyConversionPolicy::Reject,
+ ] {
+ let policy = TranslationPolicy {
+ lossy_conversion_policy,
+ ..TranslationPolicy::default()
+ };
+ assert!(matches!(
+ engine.encode_request(WireFormat::OpenAiChat, &request, &policy),
+ Err(TranslationError::LossyConversion(_))
+ ));
+ }
+ }
+}
+
#[test]
fn responses_allowed_tools_is_translated_or_rejected() -> TestResult {
let engine = TranslationEngine::default();
@@ -4131,7 +4170,7 @@ fn responses_lite_additional_tools_item_is_the_tool_list() -> TestResult {
.request
.tools
.iter()
- .map(|tool| tool.name.as_str())
+ .filter_map(|tool| tool.function().map(|tool| tool.name.as_str()))
.collect::<Vec<_>>();
assert_eq!(names, vec!["exec", "update_plan"]);
assert!(
diff --git a/examples/dynamo-preproc/src/request.rs b/examples/dynamo-preproc/src/request.rs
index ae36f0bd9..f8b591617 100644
--- a/examples/dynamo-preproc/src/request.rs
+++ b/examples/dynamo-preproc/src/request.rs
@@ -113,7 +113,10 @@ mod tests {
assert_eq!(ir.sampling.temperature, Some(0.2));
assert_eq!(ir.output.max_output_tokens, Some(64));
assert_eq!(ir.tool_choice, Some(ToolChoice::Required));
- assert_eq!(ir.tools[0].name, "Bash");
+ assert_eq!(
+ ir.tools[0].function().map(|tool| tool.name.as_str()),
+ Some("Bash")
+ );
let ContentBlock::ToolCall(call) = &ir.messages[0].content[0] else {
panic!("missing tool call")
};