docs(schema): reject duplicate stdio env names (#2693)

* docs(schema): reject duplicate stdio env names

* docs(schema): document unique stdio env names in the Rust doc

* docs(schema): let Agents accept duplicate env names, last one wins

Author: benbrandt

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

@@ -3170,7 +3170,8 @@ pub struct McpServerStdio {
     #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-null" = true)))]
     #[serde(default, skip_serializing_if = "Vec::is_empty")]
     pub args: Vec<String>,
-    /// Environment variables to set when launching the MCP server.
+    /// Environment variables to set when launching the MCP server. Names SHOULD be unique;
+    /// Agents MAY reject duplicates with `-32602`, and otherwise the last entry wins.
     #[serde_as(deserialize_as = "DefaultOnNull")]
     #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-null" = true)))]
     #[serde(default, skip_serializing_if = "Vec::is_empty")]
@@ -3207,7 +3208,8 @@ impl McpServerStdio {
         self
     }
 
-    /// Environment variables to set when launching the MCP server.
+    /// Environment variables to set when launching the MCP server. Names SHOULD be unique;
+    /// Agents MAY reject duplicates with `-32602`, and otherwise the last entry wins.
     #[must_use]
     pub fn env(mut self, env: Vec<EnvVariable>) -> Self {
         self.env = env;

docs/protocol/v2/draft/schema.mdx

@@ -5060,7 +5060,8 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d
   Absolute path to the MCP server executable.
 </ResponseField>
 <ResponseField name="env" type={<a href="#envvariable">EnvVariable[]</a>} >
-  Environment variables to set when launching the MCP server.
+  Environment variables to set when launching the MCP server. Names SHOULD be unique;
+Agents MAY reject duplicates with `-32602`, and otherwise the last entry wins.
 </ResponseField>
 <ResponseField name="name" type={"string"} required>
   Human-readable name identifying this MCP server.
@@ -5198,7 +5199,8 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d
   Absolute path to the MCP server executable.
 </ResponseField>
 <ResponseField name="env" type={<a href="#envvariable">EnvVariable[]</a>} >
-  Environment variables to set when launching the MCP server.
+  Environment variables to set when launching the MCP server. Names SHOULD be unique;
+Agents MAY reject duplicates with `-32602`, and otherwise the last entry wins.
 </ResponseField>
 <ResponseField name="name" type={"string"} required>
   Human-readable name identifying this MCP server.

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

@@ -601,7 +601,7 @@ Example stdio transport configuration:
 }
 ```
 
-Agents **SHOULD** launch stdio servers with the session's `cwd` as the working directory. `env` entries are added to the environment the Agent would otherwise give the process, replacing variables with the same name. Each `env` entry **MUST** have a unique `name`.
+Agents **SHOULD** launch stdio servers with the session's `cwd` as the working directory. `env` entries are added to the environment the Agent would otherwise give the process, replacing variables with the same name. Each `env` entry **SHOULD** have a unique `name`. Agents **MAY** reject duplicates with `-32602`; otherwise the last entry with a given name wins.
 
 #### HTTP Transport
 

docs/protocol/v2/schema.mdx

@@ -4431,7 +4431,8 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e
   Absolute path to the MCP server executable.
 </ResponseField>
 <ResponseField name="env" type={<a href="#envvariable">EnvVariable[]</a>} >
-  Environment variables to set when launching the MCP server.
+  Environment variables to set when launching the MCP server. Names SHOULD be unique;
+Agents MAY reject duplicates with `-32602`, and otherwise the last entry wins.
 </ResponseField>
 <ResponseField name="name" type={"string"} required>
   Human-readable name identifying this MCP server.
@@ -4522,7 +4523,8 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e
   Absolute path to the MCP server executable.
 </ResponseField>
 <ResponseField name="env" type={<a href="#envvariable">EnvVariable[]</a>} >
-  Environment variables to set when launching the MCP server.
+  Environment variables to set when launching the MCP server. Names SHOULD be unique;
+Agents MAY reject duplicates with `-32602`, and otherwise the last entry wins.
 </ResponseField>
 <ResponseField name="name" type={"string"} required>
   Human-readable name identifying this MCP server.

docs/protocol/v2/session-setup.mdx

@@ -533,7 +533,7 @@ Example stdio transport configuration:
 }
 ```
 
-Agents **SHOULD** launch stdio servers with the session's `cwd` as the working directory. `env` entries are added to the environment the Agent would otherwise give the process, replacing variables with the same name. Each `env` entry **MUST** have a unique `name`.
+Agents **SHOULD** launch stdio servers with the session's `cwd` as the working directory. `env` entries are added to the environment the Agent would otherwise give the process, replacing variables with the same name. Each `env` entry **SHOULD** have a unique `name`. Agents **MAY** reject duplicates with `-32602`; otherwise the last entry with a given name wins.
 
 #### HTTP Transport
 

schema/v2/schema.json

@@ -6416,7 +6416,7 @@
           "x-deserialize-default-on-null": true
         },
         "env": {
-          "description": "Environment variables to set when launching the MCP server.",
+          "description": "Environment variables to set when launching the MCP server. Names SHOULD be unique;\nAgents MAY reject duplicates with `-32602`, and otherwise the last entry wins.",
           "type": "array",
           "items": {
             "$ref": "#/$defs/EnvVariable"

schema/v2/schema.unstable.json

@@ -7578,7 +7578,7 @@
           "x-deserialize-default-on-null": true
         },
         "env": {
-          "description": "Environment variables to set when launching the MCP server.",
+          "description": "Environment variables to set when launching the MCP server. Names SHOULD be unique;\nAgents MAY reject duplicates with `-32602`, and otherwise the last entry wins.",
           "type": "array",
           "items": {
             "$ref": "#/$defs/EnvVariable"