docs: sync agents PR #720 - protocol version validation in worker transport

src/content/docs/agents/model-context-protocol/mcp-handler-api.mdx

@@ -230,7 +230,6 @@ export default {
 With persistent storage, the transport preserves:
 
 - Session ID across reconnections
-- Protocol version negotiation state
 - Initialization status
 
 This allows MCP clients to reconnect and resume their session in the event of a connection loss.
@@ -386,7 +385,6 @@ interface MCPStorageApi {
 interface TransportState {
 	sessionId?: string;
 	initialized: boolean;
-	protocolVersion?: ProtocolVersion;
 }
 ```
 
@@ -409,6 +407,20 @@ const transport = new WorkerTransport({
 
 </TypeScriptExample>
 
+## Protocol Version Validation
+
+The `WorkerTransport` validates the `MCP-Protocol-Version` header on incoming requests but does not track or enforce version consistency after initialization. This stateless approach aligns with the transport's design philosophy.
+
+### How validation works
+
+- **Header present and supported**: Request is accepted
+- **Header present and unsupported**: Returns 400 Bad Request with error message
+- **Header missing**: Request is accepted (defaults to SDK-negotiated version)
+
+The transport only validates that explicitly provided version headers are in the list of supported protocol versions. Protocol version negotiation and semantic versioning is handled by the MCP SDK during the initialization handshake, not by the transport layer.
+
+This means clients can send different supported protocol versions across requests without error, though this is not recommended in practice. The transport trusts the SDK to handle version negotiation correctly and only rejects truly unsupported versions.
+
 ## Authentication Context
 
 When using [OAuth authentication](/agents/model-context-protocol/authorization/) with `createMcpHandler`, user information is made available to your MCP tools through `getMcpAuthContext()`. Under the hood this uses `AsyncLocalStorage` to pass the request to the tool handler, keeping the authentication context available.

src/content/docs/agents/model-context-protocol/transport.mdx

@@ -102,6 +102,21 @@ If you have an existing MCP server using the `McpAgent` class:
 - **Using state?** Use `createMcpHandler` with a `WorkerTransport` inside an [Agent](/agents/) class. See [Stateful MCP Servers](/agents/model-context-protocol/mcp-handler-api#stateful-mcp-servers) for details.
 - **Need SSE support?** Continue using `McpAgent` with `serveSSE()` for legacy client compatibility. See the [McpAgent API reference](/agents/model-context-protocol/mcp-agent-api/).
 
+## Protocol version validation
+
+The Agents SDK transport implementation follows a stateless approach to MCP protocol version validation. During the initialization handshake, the SDK negotiates the protocol version according to the MCP specification. After initialization, the transport validates protocol versions as follows:
+
+- **When the `MCP-Protocol-Version` header is present**: The version must be in the list of supported protocol versions, or the request is rejected with a 400 Bad Request error.
+- **When the `MCP-Protocol-Version` header is absent**: The request is accepted and uses the version negotiated during initialization.
+
+This stateless validation approach means:
+
+- Clients are not required to send the `MCP-Protocol-Version` header on subsequent requests after initialization.
+- The transport does not enforce version consistency across requests. Clients may use different supported protocol versions in different requests (though this is not recommended).
+- Only explicitly unsupported protocol versions are rejected.
+
+This design aligns with the stateless nature of HTTP transports and delegates protocol-level version semantics to the MCP SDK.
+
 ### Testing with MCP clients
 
 You can test your MCP server using an MCP client that supports remote connections, or use [`mcp-remote`](https://www.npmjs.com/package/mcp-remote), an adapter that lets MCP clients that only support local connections work with remote MCP servers.