fix(unstable-v2): Make empty MCP arrays optional

agent-client-protocol-schema/src/v2/agent.rs

@@ -134,7 +134,7 @@ pub struct InitializeResponse {
     /// Authentication methods supported by the agent.
     #[serde_as(deserialize_as = "DefaultOnError<VecSkipError<_, SkipListener>>")]
     #[schemars(extend("x-deserialize-default-on-error" = true, "x-deserialize-skip-invalid-items" = true))]
-    #[serde(default)]
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
     pub auth_methods: Vec<AuthMethod>,
     /// The _meta property is reserved by ACP to allow clients and agents to attach additional
     /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
@@ -1804,7 +1804,7 @@ impl ListSessionsRequest {
 #[serde(rename_all = "camelCase")]
 #[non_exhaustive]
 pub struct ListSessionsResponse {
-    /// Array of session information objects
+    /// Array of session information objects.
     #[serde_as(deserialize_as = "DefaultOnError<VecSkipError<_, SkipListener>>")]
     #[schemars(extend("x-deserialize-default-on-error" = true, "x-deserialize-skip-invalid-items" = true))]
     pub sessions: Vec<SessionInfo>,
@@ -2994,6 +2994,7 @@ pub struct McpServerHttp {
     /// HTTP headers to set when making requests to the MCP server.
     #[serde_as(deserialize_as = "DefaultOnError<VecSkipError<_, SkipListener>>")]
     #[schemars(extend("x-deserialize-default-on-error" = true, "x-deserialize-skip-invalid-items" = true))]
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
     pub headers: Vec<HttpHeader>,
     /// The _meta property is reserved by ACP to allow clients and agents to attach additional
     /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
@@ -3135,10 +3136,12 @@ pub struct McpServerStdio {
     /// Command-line arguments to pass to the MCP server.
     #[serde_as(deserialize_as = "DefaultOnError<VecSkipError<_, SkipListener>>")]
     #[schemars(extend("x-deserialize-default-on-error" = true, "x-deserialize-skip-invalid-items" = true))]
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
     pub args: Vec<String>,
     /// Environment variables to set when launching the MCP server.
     #[serde_as(deserialize_as = "DefaultOnError<VecSkipError<_, SkipListener>>")]
     #[schemars(extend("x-deserialize-default-on-error" = true, "x-deserialize-skip-invalid-items" = true))]
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
     pub env: Vec<EnvVariable>,
     /// The _meta property is reserved by ACP to allow clients and agents to attach additional
     /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
@@ -5862,6 +5865,54 @@ mod test_serialization {
         }
     }
 
+    #[test]
+    fn test_mcp_server_empty_arrays_are_optional() {
+        let stdio = McpServer::Stdio(McpServerStdio::new("test-server", "/usr/bin/server"));
+        assert_eq!(
+            serde_json::to_value(&stdio).unwrap(),
+            json!({
+                "type": "stdio",
+                "name": "test-server",
+                "command": "/usr/bin/server"
+            })
+        );
+
+        let McpServer::Stdio(McpServerStdio { args, env, .. }) =
+            serde_json::from_value::<McpServer>(json!({
+                "type": "stdio",
+                "name": "test-server",
+                "command": "/usr/bin/server"
+            }))
+            .unwrap()
+        else {
+            panic!("Expected Stdio variant");
+        };
+        assert!(args.is_empty());
+        assert!(env.is_empty());
+
+        let http = McpServer::Http(McpServerHttp::new("http-server", "https://api.example.com"));
+        assert_eq!(
+            serde_json::to_value(&http).unwrap(),
+            json!({
+                "type": "http",
+                "name": "http-server",
+                "url": "https://api.example.com"
+            })
+        );
+
+        let McpServer::Http(McpServerHttp { headers, .. }) =
+            serde_json::from_value::<McpServer>(json!({
+                "type": "http",
+                "name": "http-server",
+                "url": "https://api.example.com"
+            }))
+            .unwrap()
+        else {
+            panic!("Expected Http variant");
+        };
+        assert!(headers.is_empty());
+    }
+
     #[test]
     fn test_mcp_server_unknown_transport_serialization() {
         let json = json!({

agent-client-protocol-schema/src/v2/client.rs

@@ -66,7 +66,7 @@
 }
 
 impl UpdateSessionNotification {
     /// Builds [`SessionNotification`] with the required notification fields set; optional fields start unset or empty.
     #[must_use]
     pub fn new(session_id: impl Into<SessionId>, update: SessionUpdate) -> Self {
         Self {
@@ -1020,7 +1020,7 @@
 #[serde(rename_all = "camelCase")]
 #[non_exhaustive]
 pub struct AvailableCommandsUpdate {
-    /// Commands the agent can execute
+    /// Commands the agent can execute.
     #[serde_as(deserialize_as = "DefaultOnError<VecSkipError<_, SkipListener>>")]
     #[schemars(extend("x-deserialize-default-on-error" = true, "x-deserialize-skip-invalid-items" = true))]
     pub available_commands: Vec<AvailableCommand>,

agent-client-protocol-schema/src/v2/conversion.rs

@@ -9582,15 +9582,12 @@ mod tests {
                     {
                         "type": "stdio",
                         "name": "local",
-                        "command": "/usr/bin/mcp",
-                        "args": [],
-                        "env": []
+                        "command": "/usr/bin/mcp"
                     },
                     {
                         "type": "http",
                         "name": "remote",
-                        "url": "https://example.com",
-                        "headers": []
+                        "url": "https://example.com"
                     }
                 ]
             })

docs/protocol/v2/draft/schema.mdx

@@ -356,9 +356,6 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d
 </ResponseField>
 <ResponseField name="authMethods" type={<a href="#authmethod">AuthMethod[]</a>} >
   Authentication methods supported by the agent.
-
-    - Default: `[]`
-
 </ResponseField>
 <ResponseField name="capabilities" type={<a href="#agentcapabilities">AgentCapabilities</a>} >
   Capabilities supported by the agent.
@@ -1155,7 +1152,7 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d
 to fetch the next page. If absent, there are no more results.
 </ResponseField>
 <ResponseField name="sessions" type={<a href="#sessioninfo">SessionInfo[]</a>} required>
-  Array of session information objects
+  Array of session information objects.
 </ResponseField>
 
 <a id="session-load"></a>
@@ -2753,7 +2750,7 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d
 
 </ResponseField>
 <ResponseField name="availableCommands" type={<a href="#availablecommand">AvailableCommand[]</a>} required>
-  Commands the agent can execute
+  Commands the agent can execute.
 </ResponseField>
 
 ## <span class="font-mono">BlobResourceContents</span>
@@ -4384,7 +4381,7 @@ these keys.
 See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)
 
 </ResponseField>
-<ResponseField name="headers" type={<a href="#httpheader">HttpHeader[]</a>} required>
+<ResponseField name="headers" type={<a href="#httpheader">HttpHeader[]</a>} >
   HTTP headers to set when making requests to the MCP server.
 </ResponseField>
 <ResponseField name="name" type={"string"} required>
@@ -4452,13 +4449,13 @@ these keys.
 See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)
 
 </ResponseField>
-<ResponseField name="args" type={<><span>"string"</span><span>[]</span></>} required>
+<ResponseField name="args" type={<><span>"string"</span><span>[]</span></>} >
   Command-line arguments to pass to the MCP server.
 </ResponseField>
 <ResponseField name="command" type={"string"} required>
   Absolute path to the MCP server executable.
 </ResponseField>
-<ResponseField name="env" type={<a href="#envvariable">EnvVariable[]</a>} required>
+<ResponseField name="env" type={<a href="#envvariable">EnvVariable[]</a>} >
   Environment variables to set when launching the MCP server.
 </ResponseField>
 <ResponseField name="name" type={"string"} required>
@@ -4560,7 +4557,7 @@ these keys.
 See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)
 
 </ResponseField>
-<ResponseField name="headers" type={<a href="#httpheader">HttpHeader[]</a>} required>
+<ResponseField name="headers" type={<a href="#httpheader">HttpHeader[]</a>} >
   HTTP headers to set when making requests to the MCP server.
 </ResponseField>
 <ResponseField name="name" type={"string"} required>
@@ -4586,13 +4583,13 @@ these keys.
 See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)
 
 </ResponseField>
-<ResponseField name="args" type={<><span>"string"</span><span>[]</span></>} required>
+<ResponseField name="args" type={<><span>"string"</span><span>[]</span></>} >
   Command-line arguments to pass to the MCP server.
 </ResponseField>
 <ResponseField name="command" type={"string"} required>
   Absolute path to the MCP server executable.
 </ResponseField>
-<ResponseField name="env" type={<a href="#envvariable">EnvVariable[]</a>} required>
+<ResponseField name="env" type={<a href="#envvariable">EnvVariable[]</a>} >
   Environment variables to set when launching the MCP server.
 </ResponseField>
 <ResponseField name="name" type={"string"} required>
@@ -7588,7 +7585,7 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d
 
 </ResponseField>
 <ResponseField name="availableCommands" type={<a href="#availablecommand">AvailableCommand[]</a>} required>
-  Commands the agent can execute
+  Commands the agent can execute.
 </ResponseField>
 <ResponseField name="sessionUpdate" type={"string"} required>
   The discriminator value. Must be `"available_commands_update"`.

docs/protocol/v2/draft/session-setup.mdx

@@ -427,12 +427,14 @@ When the Agent supports `session.mcp.stdio`, Clients can specify MCP servers con
   The absolute path to the MCP server executable
 </ParamField>
 
-<ParamField path="args" type="array" required>
-  Command-line arguments to pass to the server
+<ParamField path="args" type="array">
+  Command-line arguments to pass to the server. Omitted and empty values are
+  equivalent.
 </ParamField>
 
 <ParamField path="env" type="EnvVariable[]">
-  Environment variables to set when launching the server
+  Environment variables to set when launching the server. Omitted and empty
+  values are equivalent.
 
   <Expandable title="EnvVariable">
       <ParamField path="name" type="string">
@@ -477,8 +479,9 @@ When the Agent supports `session.mcp.http`, Clients can specify MCP servers conf
   The URL of the MCP server
 </ParamField>
 
-<ParamField path="headers" type="HttpHeader[]" required>
-  HTTP headers to include in requests to the server
+<ParamField path="headers" type="HttpHeader[]">
+  HTTP headers to include in requests to the server. Omitted and empty values are
+  equivalent.
 
   <Expandable title="HttpHeader">
       <ParamField path="name" type="string">

docs/protocol/v2/schema.mdx

@@ -182,9 +182,6 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e
 </ResponseField>
 <ResponseField name="authMethods" type={<a href="#authmethod">AuthMethod[]</a>} >
   Authentication methods supported by the agent.
-
-    - Default: `[]`
-
 </ResponseField>
 <ResponseField name="capabilities" type={<a href="#agentcapabilities">AgentCapabilities</a>} >
   Capabilities supported by the agent.
@@ -397,7 +394,7 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e
 to fetch the next page. If absent, there are no more results.
 </ResponseField>
 <ResponseField name="sessions" type={<a href="#sessioninfo">SessionInfo[]</a>} required>
-  Array of session information objects
+  Array of session information objects.
 </ResponseField>
 
 <a id="session-load"></a>
@@ -1304,7 +1301,7 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e
 
 </ResponseField>
 <ResponseField name="availableCommands" type={<a href="#availablecommand">AvailableCommand[]</a>} required>
-  Commands the agent can execute
+  Commands the agent can execute.
 </ResponseField>
 
 ## <span class="font-mono">BlobResourceContents</span>
@@ -2079,7 +2076,7 @@ these keys.
 See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
 
 </ResponseField>
-<ResponseField name="headers" type={<a href="#httpheader">HttpHeader[]</a>} required>
+<ResponseField name="headers" type={<a href="#httpheader">HttpHeader[]</a>} >
   HTTP headers to set when making requests to the MCP server.
 </ResponseField>
 <ResponseField name="name" type={"string"} required>
@@ -2110,13 +2107,13 @@ these keys.
 See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
 
 </ResponseField>
-<ResponseField name="args" type={<><span>"string"</span><span>[]</span></>} required>
+<ResponseField name="args" type={<><span>"string"</span><span>[]</span></>} >
   Command-line arguments to pass to the MCP server.
 </ResponseField>
 <ResponseField name="command" type={"string"} required>
   Absolute path to the MCP server executable.
 </ResponseField>
-<ResponseField name="env" type={<a href="#envvariable">EnvVariable[]</a>} required>
+<ResponseField name="env" type={<a href="#envvariable">EnvVariable[]</a>} >
   Environment variables to set when launching the MCP server.
 </ResponseField>
 <ResponseField name="name" type={"string"} required>
@@ -2170,7 +2167,7 @@ these keys.
 See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
 
 </ResponseField>
-<ResponseField name="headers" type={<a href="#httpheader">HttpHeader[]</a>} required>
+<ResponseField name="headers" type={<a href="#httpheader">HttpHeader[]</a>} >
   HTTP headers to set when making requests to the MCP server.
 </ResponseField>
 <ResponseField name="name" type={"string"} required>
@@ -2196,13 +2193,13 @@ these keys.
 See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
 
 </ResponseField>
-<ResponseField name="args" type={<><span>"string"</span><span>[]</span></>} required>
+<ResponseField name="args" type={<><span>"string"</span><span>[]</span></>} >
   Command-line arguments to pass to the MCP server.
 </ResponseField>
 <ResponseField name="command" type={"string"} required>
   Absolute path to the MCP server executable.
 </ResponseField>
-<ResponseField name="env" type={<a href="#envvariable">EnvVariable[]</a>} required>
+<ResponseField name="env" type={<a href="#envvariable">EnvVariable[]</a>} >
   Environment variables to set when launching the MCP server.
 </ResponseField>
 <ResponseField name="name" type={"string"} required>
@@ -3643,7 +3640,7 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e
 
 </ResponseField>
 <ResponseField name="availableCommands" type={<a href="#availablecommand">AvailableCommand[]</a>} required>
-  Commands the agent can execute
+  Commands the agent can execute.
 </ResponseField>
 <ResponseField name="sessionUpdate" type={"string"} required>
   The discriminator value. Must be `"available_commands_update"`.

docs/protocol/v2/session-setup.mdx

@@ -403,12 +403,14 @@ When the Agent supports `session.mcp.stdio`, Clients can specify MCP servers con
   The absolute path to the MCP server executable
 </ParamField>
 
-<ParamField path="args" type="array" required>
-  Command-line arguments to pass to the server
+<ParamField path="args" type="array">
+  Command-line arguments to pass to the server. Omitted and empty values are
+  equivalent.
 </ParamField>
 
 <ParamField path="env" type="EnvVariable[]">
-  Environment variables to set when launching the server
+  Environment variables to set when launching the server. Omitted and empty
+  values are equivalent.
 
   <Expandable title="EnvVariable">
       <ParamField path="name" type="string">
@@ -453,8 +455,9 @@ When the Agent supports `session.mcp.http`, Clients can specify MCP servers conf
   The URL of the MCP server
 </ParamField>
 
-<ParamField path="headers" type="HttpHeader[]" required>
-  HTTP headers to include in requests to the server
+<ParamField path="headers" type="HttpHeader[]">
+  HTTP headers to include in requests to the server. Omitted and empty values are
+  equivalent.
 
   <Expandable title="HttpHeader">
       <ParamField path="name" type="string">

schema/v2/schema.json

@@ -1629,7 +1629,6 @@
           "items": {
             "$ref": "#/$defs/AuthMethod"
           },
-          "default": [],
           "x-deserialize-default-on-error": true,
           "x-deserialize-skip-invalid-items": true
         },
@@ -2482,7 +2481,7 @@
       "type": "object",
       "properties": {
         "sessions": {
-          "description": "Array of session information objects",
+          "description": "Array of session information objects.",
           "type": "array",
           "items": {
             "$ref": "#/$defs/SessionInfo"
@@ -3836,7 +3835,7 @@
       "type": "object",
       "properties": {
         "availableCommands": {
-          "description": "Commands the agent can execute",
+          "description": "Commands the agent can execute.",
           "type": "array",
           "items": {
             "$ref": "#/$defs/AvailableCommand"
@@ -4353,7 +4352,7 @@
           "additionalProperties": true
         }
       },
-      "required": ["name", "url", "headers"]
+      "required": ["name", "url"]
     },
     "EnvVariable": {
       "description": "An environment variable to set when launching an MCP server.",
@@ -4413,7 +4412,7 @@
           "additionalProperties": true
         }
       },
-      "required": ["name", "command", "args", "env"]
+      "required": ["name", "command"]
     },
     "LoadSessionRequest": {
       "description": "Request parameters for loading an existing session.\n\nOnly available if the Agent supports the `session.load` capability.\n\nSee protocol docs: [Loading Sessions](https://agentclientprotocol.com/protocol/v2/session-setup#loading-sessions)",