Skip to content

feat(unstable-v2): Remove MCP SSE transport and make stdio opt-in #1368

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
benbrandt merged 2 commits into from
Jun 5, 2026
Merged

feat(unstable-v2): Remove MCP SSE transport and make stdio opt-in #1368

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9a43fb7
feat(unstable-v2): Remove MCP SSE transport and make stdio opt-in
benbrandt Jun 5, 2026
8b0ec4d
Tag MCP server transports in v2
benbrandt Jun 5, 2026
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
19 changes: 8 additions & 11 deletions docs/protocol/v2/draft/initialization.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,8 +65,8 @@ The Agent **MUST** respond with the chosen [protocol version](#protocol-version)
"embeddedContext": {}
},
"mcp": {
"http": {},
"sse": {}
"stdio": {},
"http": {}
}
},
"agentInfo": {
Expand Down Expand Up @@ -156,21 +156,18 @@ Optionally, they **MAY** support richer types of [content](/protocol/v2/draft/co

#### MCP capabilities

<ResponseField name="stdio" type="McpStdioCapabilities Object">
The Agent supports connecting to MCP servers over stdio. Omitted or `null`
means the Agent does not advertise support. Supplying `{}` means the Agent
supports stdio MCP server transports.
</ResponseField>

<ResponseField name="http" type="McpHttpCapabilities Object">
The Agent supports connecting to MCP servers over HTTP. Omitted or `null`
means the Agent does not advertise support. Supplying `{}` means the Agent
supports HTTP MCP server transports.
</ResponseField>

<ResponseField name="sse" type="McpSseCapabilities Object">
The Agent supports connecting to MCP servers over SSE. Omitted or `null` means
the Agent does not advertise support. Supplying `{}` means the Agent supports
SSE MCP server transports.

Note: This transport has been deprecated by the MCP spec.

</ResponseField>

#### Authentication Capabilities

<ResponseField name="logout" type="LogoutCapabilities Object">
Expand Down
101 changes: 36 additions & 65 deletions docs/protocol/v2/draft/schema.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4110,11 +4110,11 @@ Optional. Omitted or `null` both mean the agent does not advertise support.
Supplying `\{\}` means the agent supports HTTP MCP server transports.

</ResponseField>
<ResponseField name="sse" type={<><span><a href="#mcpssecapabilities">McpSseCapabilities</a></span><span> | null</span></>} >
Agent supports `McpServer::Sse`.
<ResponseField name="stdio" type={<><span><a href="#mcpstdiocapabilities">McpStdioCapabilities</a></span><span> | null</span></>} >
Agent supports `McpServer::Stdio`.

Optional. Omitted or `null` both mean the agent does not advertise support.
Supplying `\{\}` means the agent supports SSE MCP server transports.
Supplying `\{\}` means the agent supports stdio MCP server transports.

</ResponseField>

Expand Down Expand Up @@ -4189,37 +4189,6 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d
</Expandable>
</ResponseField>

<ResponseField name="sse" type="object">
SSE transport configuration

Only available when the Agent capabilities include `mcp.sse`.

<Expandable title="Properties">

<ResponseField name="_meta" type={"object | null"} >
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
these keys.

See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)

</ResponseField>
<ResponseField name="headers" type={<a href="#httpheader">HttpHeader[]</a>} required>
HTTP headers to set when making requests to the MCP server.
</ResponseField>
<ResponseField name="name" type={"string"} required>
Human-readable name identifying this MCP server.
</ResponseField>
<ResponseField name="type" type={"string"} required>
The discriminator value. Must be `"sse"`.
</ResponseField>
<ResponseField name="url" type={"string"} required>
URL to the MCP server.
</ResponseField>

</Expandable>
</ResponseField>

<ResponseField name="acp" type="object">
**UNSTABLE**

Expand Down Expand Up @@ -4257,10 +4226,10 @@ on the same ACP connection.
</Expandable>
</ResponseField>

<ResponseField name="stdio">
<ResponseField name="stdio" type="object">
Stdio transport configuration

All Agents MUST support this transport.
Only available when the Agent capabilities include `mcp.stdio`.

<Expandable title="Properties">

Expand All @@ -4284,6 +4253,34 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d
<ResponseField name="name" type={"string"} required>
Human-readable name identifying this MCP server.
</ResponseField>
<ResponseField name="type" type={"string"} required>
The discriminator value. Must be `"stdio"`.
</ResponseField>

</Expandable>
</ResponseField>

<ResponseField name="other" type="object">
Custom or future MCP server transport configuration.

Values beginning with `_` are reserved for implementation-specific
extensions. Unknown values that do not begin with `_` are reserved for
future ACP variants.

Receivers that do not understand this transport should preserve the raw
payload when storing, replaying, proxying, or forwarding session setup
data, and otherwise ignore it or reject the server configuration.

<Expandable title="Properties">

<ResponseField name="type" type={"string"} required>
Custom or future MCP server transport type.

Values beginning with `_` are reserved for implementation-specific
extensions. Unknown values that do not begin with `_` are reserved for
future ACP variants.

</ResponseField>

</Expandable>
</ResponseField>
Expand Down Expand Up @@ -4362,32 +4359,6 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d
URL to the MCP server.
</ResponseField>

## <span class="font-mono">McpServerSse</span>

SSE transport configuration for MCP.

**Type:** Object

**Properties:**

<ResponseField name="_meta" type={"object | null"} >
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
these keys.

See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)

</ResponseField>
<ResponseField name="headers" type={<a href="#httpheader">HttpHeader[]</a>} required>
HTTP headers to set when making requests to the MCP server.
</ResponseField>
<ResponseField name="name" type={"string"} required>
Human-readable name identifying this MCP server.
</ResponseField>
<ResponseField name="url" type={"string"} required>
URL to the MCP server.
</ResponseField>

## <span class="font-mono">McpServerStdio</span>

Stdio transport configuration for MCP.
Expand Down Expand Up @@ -4417,11 +4388,11 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d
Human-readable name identifying this MCP server.
</ResponseField>

## <span class="font-mono">McpSseCapabilities</span>
## <span class="font-mono">McpStdioCapabilities</span>

Capabilities for SSE MCP server transports.
Capabilities for stdio MCP server transports.

Supplying `\{\}` means the agent supports SSE MCP server transports.
Supplying `\{\}` means the agent supports stdio MCP server transports.

**Type:** Object

Expand Down
71 changes: 16 additions & 55 deletions docs/protocol/v2/draft/session-setup.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,7 @@ Clients create a new session by calling the `session/new` method with:
"cwd": "/home/user/project",
"mcpServers": [
{
"type": "stdio",
"name": "workspace-tools",
"command": "/path/to/mcp-server",
"args": ["--stdio"],
Expand Down Expand Up @@ -125,6 +126,7 @@ To load an existing session, Clients **MUST** call the `session/load` method wit
"cwd": "/home/user/project",
"mcpServers": [
{
"type": "stdio",
"name": "workspace-tools",
"command": "/path/to/mcp-server",
"args": ["--mode", "workspace"],
Expand Down Expand Up @@ -244,6 +246,7 @@ To resume an existing session without replaying prior messages, Clients
"cwd": "/home/user/project",
"mcpServers": [
{
"type": "stdio",
"name": "workspace-tools",
"command": "/path/to/mcp-server",
"args": ["--mode", "workspace"],
Expand Down Expand Up @@ -397,15 +400,19 @@ When `session.additionalDirectories` is in use, the session's effective root set

The [Model Context Protocol (MCP)](https://modelcontextprotocol.io) allows Agents to access external tools and data sources. When creating a session, Clients **MAY** include connection details for MCP servers that the Agent should connect to.

MCP servers can be connected to using different transports. All Agents **MUST** support the stdio transport, while HTTP and SSE transports are optional capabilities that can be checked during initialization.

While they are not required to by the spec, new Agents **SHOULD** support the HTTP transport to ensure compatibility with modern MCP servers.
MCP servers can be connected to using different transports. Agents advertise supported transports during initialization using `mcp.stdio`, `mcp.http`, and any extension-specific transport capabilities.

### 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.

#### Stdio Transport

All Agents **MUST** support connecting to MCP servers via stdio (standard input/output). This is the default transport mechanism.
When the Agent supports `mcp.stdio`, Clients can specify MCP servers configurations using the stdio transport.

<ParamField path="type" type="string" required>
Must be `"stdio"` to indicate stdio transport
</ParamField>

<ParamField path="name" type="string" required>
A human-readable identifier for the server
Expand Down Expand Up @@ -436,6 +443,7 @@ Example stdio transport configuration:

```json
{
"type": "stdio",
"name": "workspace-tools",
"command": "/path/to/mcp-server",
"args": ["--stdio"],
Expand Down Expand Up @@ -497,56 +505,9 @@ Example HTTP transport configuration:
}
```

#### SSE Transport

When the Agent supports `mcp.sse`, Clients can specify MCP servers configurations using the SSE transport.

<Warning>This transport was deprecated by the MCP spec.</Warning>

<ParamField path="type" type="string" required>
Must be `"sse"` to indicate SSE transport
</ParamField>

<ParamField path="name" type="string" required>
A human-readable identifier for the server
</ParamField>

<ParamField path="url" type="string" required>
The URL of the SSE endpoint
</ParamField>

<ParamField path="headers" type="HttpHeader[]" required>
HTTP headers to include when establishing the SSE connection

<Expandable title="HttpHeader">
<ParamField path="name" type="string">
The name of the HTTP header.
</ParamField>
<ParamField path="value" type="string">
The value to set for the HTTP header.
</ParamField>
</Expandable>
</ParamField>

Example SSE transport configuration:

```json
{
"type": "sse",
"name": "event-stream",
"url": "https://events.example.com/mcp",
"headers": [
{
"name": "X-API-Key",
"value": "apikey456"
}
]
}
```

### Checking Transport Support

Before using HTTP or SSE transports, Clients **MUST** verify the Agent's capabilities during initialization:
Before using stdio or HTTP transports, Clients **MUST** verify the Agent's capabilities during initialization:

```json highlight={7-10}
{
Expand All @@ -556,16 +517,16 @@ Before using HTTP or SSE transports, Clients **MUST** verify the Agent's capabil
"protocolVersion": 2,
"capabilities": {
"mcp": {
"http": {},
"sse": {}
"stdio": {},
"http": {}
}
}
}
}
```

If `mcp.stdio` is omitted or `null`, the Agent does not support stdio transport.
If `mcp.http` is omitted or `null`, the Agent does not support HTTP transport.
If `mcp.sse` is omitted or `null`, the Agent does not support SSE transport.
Supplying `{}` means the Agent supports the corresponding transport.

Agents **SHOULD** connect to all MCP servers specified by the Client.
Expand Down
19 changes: 8 additions & 11 deletions docs/protocol/v2/initialization.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,8 +65,8 @@ The Agent **MUST** respond with the chosen [protocol version](#protocol-version)
"embeddedContext": {}
},
"mcp": {
"http": {},
"sse": {}
"stdio": {},
"http": {}
}
},
"agentInfo": {
Expand Down Expand Up @@ -157,21 +157,18 @@ Optionally, they **MAY** support richer types of [content](/protocol/v2/content)

#### MCP capabilities

<ResponseField name="stdio" type="McpStdioCapabilities Object">
The Agent supports connecting to MCP servers over stdio. Omitted or `null`
means the Agent does not advertise support. Supplying `{}` means the Agent
supports stdio MCP server transports.
</ResponseField>

<ResponseField name="http" type="McpHttpCapabilities Object">
The Agent supports connecting to MCP servers over HTTP. Omitted or `null`
means the Agent does not advertise support. Supplying `{}` means the Agent
supports HTTP MCP server transports.
</ResponseField>

<ResponseField name="sse" type="McpSseCapabilities Object">
The Agent supports connecting to MCP servers over SSE. Omitted or `null` means
the Agent does not advertise support. Supplying `{}` means the Agent supports
SSE MCP server transports.

Note: This transport has been deprecated by the MCP spec.

</ResponseField>

#### Authentication Capabilities

<ResponseField name="logout" type="LogoutCapabilities Object">
Expand Down
Loading