Sync docs for PR #752: Upgrade MCP SDK to v1.25.1

This sync updates the documentation to reflect the following changes from
cloudflare/agents PR #752:

## API Changes

### WorkerTransportOptions (mcp-handler-api.mdx)
- Added `onsessionclosed` callback that fires when a session is closed via
  DELETE request
- Added `eventStore` option for SSE resumability support, enabling clients to
  reconnect and resume using Last-Event-ID header
- Added `retryInterval` option to control client reconnection timing for
  polling behavior
- Added `closeSSEStream()` method to WorkerTransport class for implementing
  polling behavior during long-running operations
- Updated `sessionIdGenerator` description to clarify it can return undefined
  for stateless mode

### MCPTransportOptions (mcp-client-api.mdx)
- Added `connectionTimeoutMs` option (default: 15000ms) to prevent infinite
  hangs when connecting to MCP servers. Particularly useful when proxies strip
  SSE newline terminators.

### New Example (transport.mdx)
- Added documentation for the new `mcp-server` example showing how to use
  `WebStandardStreamableHTTPServerTransport` from the MCP SDK directly without
  the agents package. This is the simplest way to create stateless MCP servers
  on Cloudflare Workers.

Related PR: cloudflare/agents#752

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <[email protected]>

Author: github-actions[bot]

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

@@ -63,6 +63,7 @@ async addMcpServer(
     transport?: {
       headers?: HeadersInit;
       type?: "sse" | "streamable-http" | "auto";
+      connectionTimeoutMs?: number;
     };
   }
 ): Promise<
@@ -82,6 +83,7 @@ async addMcpServer(
   - **`transport`** — Transport layer configuration:
     - **`headers`** — Custom HTTP headers for authentication
     - **`type`** — Transport type: `"sse"`, `"streamable-http"`, or `"auto"` (tries streamable-http first, falls back to sse)
+    - **`connectionTimeoutMs`** — Connection timeout in milliseconds. Default: 15000 (15 seconds). If the connection does not complete within this time, it will fail. Timeouts are often caused by proxies that strip SSE newline terminators, causing the parser to hang.
 
 #### Returns
 

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

@@ -61,8 +61,11 @@ interface CreateMcpHandlerOptions extends WorkerTransportOptions {
 	sessionIdGenerator?: () => string;
 	enableJsonResponse?: boolean;
 	onsessioninitialized?: (sessionId: string) => void;
+	onsessionclosed?: (sessionId: string) => void;
 	corsOptions?: CORSOptions;
 	storage?: MCPStorageApi;
+	eventStore?: EventStore;
+	retryInterval?: number;
 }
 ```
 
@@ -259,6 +262,7 @@ class WorkerTransport implements Transport {
 	): Promise<void>;
 	async start(): Promise<void>;
 	async close(): Promise<void>;
+	closeSSEStream(requestId: RequestId): void;
 }
 ```
 
@@ -269,6 +273,7 @@ interface WorkerTransportOptions {
 	/**
 	 * Function that generates a unique session ID.
 	 * Called when a new session is initialized.
+	 * Return undefined to disable session management (stateless mode).
 	 */
 	sessionIdGenerator?: () => string;
 
@@ -285,6 +290,12 @@ interface WorkerTransportOptions {
 	 */
 	onsessioninitialized?: (sessionId: string) => void;
 
+	/**
+	 * Callback invoked when a session is closed via DELETE request.
+	 * Receives the session ID that was closed.
+	 */
+	onsessionclosed?: (sessionId: string) => void;
+
 	/**
 	 * CORS configuration for cross-origin requests.
 	 * Configures Access-Control-* headers.
@@ -297,6 +308,18 @@ interface WorkerTransportOptions {
 	 * so it survives hibernation/restart.
 	 */
 	storage?: MCPStorageApi;
+
+	/**
+	 * Event store for resumability support.
+	 * If provided, enables clients to reconnect and resume messages using Last-Event-ID.
+	 */
+	eventStore?: EventStore;
+
+	/**
+	 * Retry interval in milliseconds to suggest to clients in SSE retry field.
+	 * Controls client reconnection timing for polling behavior.
+	 */
+	retryInterval?: number;
 }
 ```
 
@@ -344,6 +367,23 @@ const transport = new WorkerTransport({
 
 </TypeScriptExample>
 
+#### onsessionclosed
+
+A callback that fires when a session is explicitly closed via DELETE request. This allows you to perform cleanup operations when a client terminates the session.
+
+<TypeScriptExample>
+
+```ts
+const transport = new WorkerTransport({
+	onsessionclosed: (sessionId) => {
+		console.log(`MCP session closed: ${sessionId}`);
+		// Perform cleanup operations
+	},
+});
+```
+
+</TypeScriptExample>
+
 #### corsOptions
 
 Configure CORS headers for cross-origin requests.
@@ -409,6 +449,88 @@ const transport = new WorkerTransport({
 
 </TypeScriptExample>
 
+#### eventStore
+
+An event store for SSE resumability support. When provided, clients can reconnect and resume from where they left off using the `Last-Event-ID` header. This is useful for handling temporary network interruptions without losing messages.
+
+```ts
+interface EventStore {
+	storeEvent(streamId: string, message: JSONRPCMessage): Promise<EventId>;
+	replayEventsAfter(
+		lastEventId: EventId,
+		handler: { send: (eventId: EventId, message: JSONRPCMessage) => Promise<void> }
+	): Promise<string>;
+	getStreamIdForEventId?(eventId: EventId): Promise<string | undefined>;
+}
+```
+
+<TypeScriptExample>
+
+```ts
+// Example: In-memory event store (use persistent storage in production)
+class InMemoryEventStore implements EventStore {
+	private events: Map<string, Array<{ id: string; message: JSONRPCMessage }>> = new Map();
+	private eventCounter = 0;
+
+	async storeEvent(streamId: string, message: JSONRPCMessage): Promise<string> {
+		const eventId = `event-${++this.eventCounter}`;
+		const streamEvents = this.events.get(streamId) || [];
+		streamEvents.push({ id: eventId, message });
+		this.events.set(streamId, streamEvents);
+		return eventId;
+	}
+
+	async replayEventsAfter(
+		lastEventId: string,
+		handler: { send: (eventId: string, message: JSONRPCMessage) => Promise<void> }
+	): Promise<string> {
+		// Implementation details omitted for brevity
+		return streamId;
+	}
+}
+
+const transport = new WorkerTransport({
+	eventStore: new InMemoryEventStore(),
+});
+```
+
+</TypeScriptExample>
+
+#### retryInterval
+
+Suggests to MCP clients how long to wait (in milliseconds) before reconnecting after a connection is closed. This is sent in the SSE retry field and enables polling behavior for long-running operations.
+
+<TypeScriptExample>
+
+```ts
+const transport = new WorkerTransport({
+	retryInterval: 5000, // Suggest clients reconnect after 5 seconds
+});
+```
+
+</TypeScriptExample>
+
+#### closeSSEStream
+
+Close an SSE stream for a specific request, triggering client reconnection. Use this to implement polling behavior during long-running operations - the client will reconnect after the retry interval specified in the priming event.
+
+This method is useful when you want to control when clients poll for updates rather than keeping connections open continuously.
+
+<TypeScriptExample>
+
+```ts
+import { WorkerTransport } from "agents/mcp";
+
+const transport = new WorkerTransport({
+	retryInterval: 3000, // Client will reconnect after 3 seconds
+});
+
+// Close the stream to trigger reconnection and polling
+transport.closeSSEStream(requestId);
+```
+
+</TypeScriptExample>
+
 ## 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

@@ -30,9 +30,57 @@ You can use the "Deploy to Cloudflare" button to create a remote MCP server.
 
 [![Deploy to Workers](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/agents/tree/main/examples/mcp-worker)
 
-#### Remote MCP server (without authentication)
+#### Remote MCP server (using MCP SDK directly)
 
-Create an MCP server using `createMcpHandler`. View the [complete example on GitHub](https://github.com/cloudflare/agents/tree/main/examples/mcp-worker).
+The simplest way to create a stateless MCP server on Cloudflare Workers is to use `WebStandardStreamableHTTPServerTransport` from the `@modelcontextprotocol/sdk` directly, without the agents package. View the [complete example on GitHub](https://github.com/cloudflare/agents/tree/main/examples/mcp-server).
+
+<TypeScriptExample>
+
+```ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import { z } from "zod";
+
+const server = new McpServer({
+	name: "Hello MCP Server",
+	version: "1.0.0",
+});
+
+server.registerTool(
+	"hello",
+	{
+		description: "Returns a greeting message",
+		inputSchema: { name: z.string().optional() },
+	},
+	async ({ name }) => {
+		return {
+			content: [{ text: `Hello, ${name ?? "World"}!`, type: "text" }],
+		};
+	},
+);
+
+const transport = new WebStandardStreamableHTTPServerTransport();
+server.connect(transport);
+
+export default {
+	fetch: async (request: Request) => {
+		if (request.method === "OPTIONS") {
+			return new Response(null, { headers: corsHeaders });
+		}
+		return await transport.handleRequest(request);
+	},
+};
+```
+
+</TypeScriptExample>
+
+:::note
+This approach is ideal for stateless MCP servers. If you need session state, authentication, or integration with the Agents SDK, use `createMcpHandler` instead.
+:::
+
+#### Remote MCP server (using createMcpHandler)
+
+Create an MCP server using `createMcpHandler`. This approach provides integration with the Agents SDK and supports both stateless and stateful servers. View the [complete example on GitHub](https://github.com/cloudflare/agents/tree/main/examples/mcp-worker).
 
 <TypeScriptExample>