diff --git a/agent-client-protocol-schema/src/v2/agent.rs b/agent-client-protocol-schema/src/v2/agent.rs
index 41553001f..60be6e38e 100644
--- a/agent-client-protocol-schema/src/v2/agent.rs
+++ b/agent-client-protocol-schema/src/v2/agent.rs
@@ -4805,7 +4805,9 @@ impl McpServerAcp {
pub struct McpServerStdio {
/// Human-readable name identifying this MCP server.
pub name: String,
- /// Absolute path to the MCP server executable.
+ /// Path to the MCP server executable. Must be an absolute path.
+ ///
+ /// Agents reject a request with a relative `command` with `-32602`.
pub command: AbsolutePath,
/// Command-line arguments to pass to the MCP server.
#[serde_as(deserialize_as = "DefaultOnNull")]
diff --git a/docs/protocol/v2/draft/schema.mdx b/docs/protocol/v2/draft/schema.mdx
index b95390c3b..f114406a7 100644
--- a/docs/protocol/v2/draft/schema.mdx
+++ b/docs/protocol/v2/draft/schema.mdx
@@ -6986,7 +6986,10 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d
Command-line arguments to pass to the MCP server.
AbsolutePath} required>
- Absolute path to the MCP server executable.
+ Path to the MCP server executable. Must be an absolute path.
+
+Agents reject a request with a relative `command` with `-32602`.
+
EnvVariable[]} >
Environment variables to set when launching the MCP server. Names SHOULD be unique.
@@ -7125,7 +7128,10 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d
Command-line arguments to pass to the MCP server.
AbsolutePath} required>
- Absolute path to the MCP server executable.
+ Path to the MCP server executable. Must be an absolute path.
+
+Agents reject a request with a relative `command` with `-32602`.
+
EnvVariable[]} >
Environment variables to set when launching the MCP server. Names SHOULD be unique.
diff --git a/docs/protocol/v2/draft/session-setup.mdx b/docs/protocol/v2/draft/session-setup.mdx
index c7654a51b..0603753b7 100644
--- a/docs/protocol/v2/draft/session-setup.mdx
+++ b/docs/protocol/v2/draft/session-setup.mdx
@@ -654,7 +654,8 @@ When the Agent supports `session.mcp.stdio`, Clients can specify MCP servers con
- The absolute path to the MCP server executable
+ The path to the MCP server executable. It **MUST** be an absolute path. Agents
+ reject a request with a relative `command` with `-32602`.
diff --git a/docs/protocol/v2/migration.mdx b/docs/protocol/v2/migration.mdx
index 94490db36..1816522d2 100644
--- a/docs/protocol/v2/migration.mdx
+++ b/docs/protocol/v2/migration.mdx
@@ -856,6 +856,7 @@ MCP transport configuration is aligned with the current MCP transport model:
- The deprecated HTTP+SSE transport (`"type": "sse"`) is **removed**.
- Support is advertised per transport under `capabilities.session.mcp`: `stdio` is now an explicit capability (`session.mcp.stdio`), so agents that cannot launch subprocesses can opt out, and `session.mcp.http` covers remote servers.
- Each server `name` **MUST** be unique within `mcpServers`, and Agents reject duplicates with `-32602`.
+- A stdio `command` **MUST** be an absolute path, and Agents reject a relative one with `-32602`. v1 described the field as an absolute path but did not require it.
- On `session/resume`, `mcpServers` is the complete set of Client-provided servers, like `additionalDirectories`. Servers from earlier requests are not restored.
- Empty arrays are no longer required: `args` and `env` on stdio configs and `headers` on HTTP configs are optional in v2 (v1 required `args`, `env`, and `headers` even when empty).
@@ -970,7 +971,7 @@ See [Errors](/protocol/v2/error).
11. **Modes and config options.** Drop `session/set_mode`, `modes`, and `current_mode_update`. Expose the same state as config options with `category: "mode"` and emit `config_option_update`. Return the session's `configOptions` in every `session/new` and `session/resume` response. Rename option `id` to `configId` and group `group` to `groupId`, and require the `type` discriminator (`"id"` or `"boolean"`) on `session/set_config_option`. List the values of a `select` `thought_level` option from lowest to highest.
12. **Replay.** Handle `replayFrom` on `session/resume`. Replay history as ordinary `session/update` notifications when asked, current-state snapshots such as terminal `output` are fine. When the Client may already hold an entity's `_meta`, remove stale keys explicitly, since an `_meta` object no longer replaces them. Start each entity that you replay as chunks with an update that empties the chunked field. Send `replay_complete` after the last replayed update, also for an empty history, and hold every other update for the session until after it. Remove `session/load`.
13. **Client file and terminal methods.** Remove all `fs/*` and `terminal/*` calls. The new terminal content is Agent-owned display state, not a Client resource.
-14. **MCP config.** Require and emit `type` discriminators. Reject SSE and unadvertised transports with `-32602`. Advertise `session.mcp.stdio` / `session.mcp.http` as appropriate.
+14. **MCP config.** Require and emit `type` discriminators. Reject SSE and unadvertised transports with `-32602`, and a relative stdio `command` too. Advertise `session.mcp.stdio` / `session.mcp.http` as appropriate.
15. **Slash commands.** Add the `type: "command"` discriminator to each advertised command and the `type: "text"` discriminator to command `input` specifications. Return the session's commands in `availableCommands` in every `session/new` and `session/resume` response, and use complete-replacement `available_commands_update` notifications for later changes.
16. **Parsing.** Make enum handling open: preserve unknown variants where a safe fallback exists.
17. **Errors.** Return the now-required [error codes](#errors): `-32601`, `-32002` with `data.sessionId`, and `-32600` before initialization or for a late `initialize`.
@@ -992,7 +993,7 @@ See [Errors](/protocol/v2/error).
10. **Notices and compaction.** Handle `notice`, `compaction_update`, and `compaction_summary_chunk`, or ignore them. v2 sends them without a Client capability.
11. **Modes and config options.** Drop `session/set_mode` and `current_mode_update` handling. Drive mode/model UI from `configOptions` (using `category`) via `session/set_config_option` and `config_option_update`. Read `configId` and `groupId`, render `boolean` options, and send `session/set_config_option` with a `type` of `"id"` or `"boolean"`.
12. **Resume.** Replace `session/load` with `session/resume` + `replayFrom: { "type": "start" }`, and use `session/resume` without `replayFrom` to reattach when you still hold the session's entities and missed no updates. Request replay when you want them resynchronized, for example after a lost connection. Use `replay_complete` to find the end of the replayed history, and treat a replay that ends without it and without a successful response as truncated.
-13. **Client file and terminal methods.** Remove `fs/*` and `terminal/*` implementations for v2 connections. Expose Client-side tools through MCP servers passed in `mcpServers`, using only transports the Agent advertises under `session.mcp`. Do not treat display terminals as Client resources.
+13. **Client file and terminal methods.** Remove `fs/*` and `terminal/*` implementations for v2 connections. Expose Client-side tools through MCP servers passed in `mcpServers`, using only transports the Agent advertises under `session.mcp`. Send an absolute `command` for each stdio server. Do not treat display terminals as Client resources.
14. **Cancellation.** After `session/cancel`, keep accepting updates and wait for the idle `state_update` with `stopReason: "cancelled"` as confirmation. Don't answer every pending permission request when you send it. Dismiss and answer a request when the Agent cancels it with `$/cancel_request`.
15. **Parsing.** Preserve unknown enum variants, tolerate unknown `sessionUpdate` types, and read commands and their `input` as tagged unions. Replace the `configOptions` and `availableCommands` lists you hold with the lists in each setup response, including lists from updates that arrived before the response. An omitted list means none. Replace the command list on each `available_commands_update`, including `[]` to clear it.
16. **Subagents.** Handle `subagent_update`, which needs no capability and cannot be ignored as an unknown update. Register each child session, attribute its updates and requests to it, and show `session_message` entries as messages between sessions. Send nothing for a child except responses to its requests, `session/cancel` while the child advertises `capabilities.cancel`, and `tool_call/cancel` or `terminal/cancel` for an item that advertises its own. Discard child state and capabilities when you resume the parent.
diff --git a/docs/protocol/v2/schema.mdx b/docs/protocol/v2/schema.mdx
index a69b5e82f..d24e002fa 100644
--- a/docs/protocol/v2/schema.mdx
+++ b/docs/protocol/v2/schema.mdx
@@ -4783,7 +4783,10 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e
Command-line arguments to pass to the MCP server.
AbsolutePath} required>
- Absolute path to the MCP server executable.
+ Path to the MCP server executable. Must be an absolute path.
+
+Agents reject a request with a relative `command` with `-32602`.
+
EnvVariable[]} >
Environment variables to set when launching the MCP server. Names SHOULD be unique.
@@ -4875,7 +4878,10 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e
Command-line arguments to pass to the MCP server.
AbsolutePath} required>
- Absolute path to the MCP server executable.
+ Path to the MCP server executable. Must be an absolute path.
+
+Agents reject a request with a relative `command` with `-32602`.
+
EnvVariable[]} >
Environment variables to set when launching the MCP server. Names SHOULD be unique.
diff --git a/docs/protocol/v2/session-setup.mdx b/docs/protocol/v2/session-setup.mdx
index 1faa0d1a7..fa77d96d4 100644
--- a/docs/protocol/v2/session-setup.mdx
+++ b/docs/protocol/v2/session-setup.mdx
@@ -637,7 +637,8 @@ When the Agent supports `session.mcp.stdio`, Clients can specify MCP servers con
- The absolute path to the MCP server executable
+ The path to the MCP server executable. It **MUST** be an absolute path. Agents
+ reject a request with a relative `command` with `-32602`.
diff --git a/schema/v2/schema.json b/schema/v2/schema.json
index e99fbcdc6..92f7d721a 100644
--- a/schema/v2/schema.json
+++ b/schema/v2/schema.json
@@ -7256,7 +7256,7 @@
"type": "string"
},
"command": {
- "description": "Absolute path to the MCP server executable.",
+ "description": "Path to the MCP server executable. Must be an absolute path.\n\nAgents reject a request with a relative `command` with `-32602`.",
"allOf": [
{
"$ref": "#/$defs/AbsolutePath"
diff --git a/schema/v2/schema.unstable.json b/schema/v2/schema.unstable.json
index 70087fcde..1e260961c 100644
--- a/schema/v2/schema.unstable.json
+++ b/schema/v2/schema.unstable.json
@@ -9321,7 +9321,7 @@
"type": "string"
},
"command": {
- "description": "Absolute path to the MCP server executable.",
+ "description": "Path to the MCP server executable. Must be an absolute path.\n\nAgents reject a request with a relative `command` with `-32602`.",
"allOf": [
{
"$ref": "#/$defs/AbsolutePath"