Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion agent-client-protocol-schema/src/v2/agent.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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")]
Expand Down
10 changes: 8 additions & 2 deletions docs/protocol/v2/draft/schema.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6986,7 +6986,10 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d
Command-line arguments to pass to the MCP server.
</ResponseField>
<ResponseField name="command" type={<a href="#absolutepath">AbsolutePath</a>} 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`.

</ResponseField>
<ResponseField name="env" type={<a href="#envvariable">EnvVariable[]</a>} >
Environment variables to set when launching the MCP server. Names SHOULD be unique.
Expand Down Expand Up @@ -7125,7 +7128,10 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d
Command-line arguments to pass to the MCP server.
</ResponseField>
<ResponseField name="command" type={<a href="#absolutepath">AbsolutePath</a>} 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`.

</ResponseField>
<ResponseField name="env" type={<a href="#envvariable">EnvVariable[]</a>} >
Environment variables to set when launching the MCP server. Names SHOULD be unique.
Expand Down
3 changes: 2 additions & 1 deletion docs/protocol/v2/draft/session-setup.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -654,7 +654,8 @@ When the Agent supports `session.mcp.stdio`, Clients can specify MCP servers con
</ParamField>

<ParamField path="command" type="string" required>
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`.
</ParamField>

<ParamField path="args" type="array">
Expand Down
5 changes: 3 additions & 2 deletions docs/protocol/v2/migration.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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).

Expand Down Expand Up @@ -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`.
Expand All @@ -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.
Expand Down
10 changes: 8 additions & 2 deletions docs/protocol/v2/schema.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4783,7 +4783,10 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e
Command-line arguments to pass to the MCP server.
</ResponseField>
<ResponseField name="command" type={<a href="#absolutepath">AbsolutePath</a>} 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`.

</ResponseField>
<ResponseField name="env" type={<a href="#envvariable">EnvVariable[]</a>} >
Environment variables to set when launching the MCP server. Names SHOULD be unique.
Expand Down Expand Up @@ -4875,7 +4878,10 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e
Command-line arguments to pass to the MCP server.
</ResponseField>
<ResponseField name="command" type={<a href="#absolutepath">AbsolutePath</a>} 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`.

</ResponseField>
<ResponseField name="env" type={<a href="#envvariable">EnvVariable[]</a>} >
Environment variables to set when launching the MCP server. Names SHOULD be unique.
Expand Down
3 changes: 2 additions & 1 deletion docs/protocol/v2/session-setup.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -637,7 +637,8 @@ When the Agent supports `session.mcp.stdio`, Clients can specify MCP servers con
</ParamField>

<ParamField path="command" type="string" required>
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`.
</ParamField>

<ParamField path="args" type="array">
Expand Down
2 changes: 1 addition & 1 deletion schema/v2/schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
2 changes: 1 addition & 1 deletion schema/v2/schema.unstable.json
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
Loading