docs(schema): resume mcpServers is the complete Client-provided set (#2614)

* docs(schema): resume mcpServers is the complete Client-provided set

* docs(schema): make not restoring earlier MCP servers a SHOULD NOT

Author: benbrandt

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

@@ -1256,6 +1256,9 @@ pub struct ResumeSessionRequest {
     #[serde(default, skip_serializing_if = "Vec::is_empty")]
     pub additional_directories: Vec<AbsolutePath>,
     /// List of MCP servers to connect to for this session.
+    ///
+    /// The complete set of Client-provided servers; omitted and `[]` mean none. Agents SHOULD
+    /// NOT restore servers from earlier requests.
     #[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")]

docs/protocol/v2/draft/schema.mdx

@@ -1024,6 +1024,10 @@ in a different directory reject it with `-32602`, and MAY normalize paths when c
 </ResponseField>
 <ResponseField name="mcpServers" type={<a href="#mcpserver">McpServer[]</a>} >
   List of MCP servers to connect to for this session.
+
+The complete set of Client-provided servers; omitted and `[]` mean none. Agents SHOULD
+NOT restore servers from earlier requests.
+
 </ResponseField>
 <ResponseField name="replayFrom" type={<><span><a href="#replayfrom">ReplayFrom</a></span><span> | null</span></>} >
   Inclusive cursor describing where conversation replay should begin.

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

@@ -544,6 +544,8 @@ MCP servers can be connected to using different transports. Agents advertise sup
 
 Each server `name` **MUST** be unique within `mcpServers`. Agents reject duplicates with `-32602`.
 
+On `session/resume`, `mcpServers` is the complete set of Client-provided servers for the session; omitted and `[]` mean none. Agents **SHOULD NOT** restore servers from earlier `session/new` or `session/resume` requests. MCP servers the Agent is configured with independently of ACP are unaffected.
+
 ### Transport Types
 
 Every MCP server object has a `type` discriminator that identifies its transport. Custom implementation-specific transport types **MUST** begin with `_`; unknown non-underscore transport types are reserved for future ACP variants.

docs/protocol/v2/schema.mdx

@@ -682,6 +682,10 @@ in a different directory reject it with `-32602`, and MAY normalize paths when c
 </ResponseField>
 <ResponseField name="mcpServers" type={<a href="#mcpserver">McpServer[]</a>} >
   List of MCP servers to connect to for this session.
+
+The complete set of Client-provided servers; omitted and `[]` mean none. Agents SHOULD
+NOT restore servers from earlier requests.
+
 </ResponseField>
 <ResponseField name="replayFrom" type={<><span><a href="#replayfrom">ReplayFrom</a></span><span> | null</span></>} >
   Inclusive cursor describing where conversation replay should begin.

docs/protocol/v2/session-setup.mdx

@@ -475,6 +475,8 @@ MCP servers can be connected to using different transports. Agents advertise sup
 
 Each server `name` **MUST** be unique within `mcpServers`. Agents reject duplicates with `-32602`.
 
+On `session/resume`, `mcpServers` is the complete set of Client-provided servers for the session; omitted and `[]` mean none. Agents **SHOULD NOT** restore servers from earlier `session/new` or `session/resume` requests. MCP servers the Agent is configured with independently of ACP are unaffected.
+
 ### Transport Types
 
 Every MCP server object has a `type` discriminator that identifies its transport. Custom implementation-specific transport types **MUST** begin with `_`; unknown non-underscore transport types are reserved for future ACP variants.

schema/v2/schema.json

@@ -6875,7 +6875,7 @@
           "x-deserialize-default-on-null": true
         },
         "mcpServers": {
-          "description": "List of MCP servers to connect to for this session.",
+          "description": "List of MCP servers to connect to for this session.\n\nThe complete set of Client-provided servers; omitted and `[]` mean none. Agents SHOULD\nNOT restore servers from earlier requests.",
           "type": "array",
           "items": {
             "$ref": "#/$defs/McpServer"

schema/v2/schema.unstable.json

@@ -8181,7 +8181,7 @@
           "x-deserialize-default-on-null": true
         },
         "mcpServers": {
-          "description": "List of MCP servers to connect to for this session.",
+          "description": "List of MCP servers to connect to for this session.\n\nThe complete set of Client-provided servers; omitted and `[]` mean none. Agents SHOULD\nNOT restore servers from earlier requests.",
           "type": "array",
           "items": {
             "$ref": "#/$defs/McpServer"