agents 0.19.0 → 0.20.1

package/dist/react.d.ts

@@ -2,7 +2,7 @@ import {
   Y as MCPServersState,
   _ as AgentToolRunState,
   g as AgentToolRunPart
-} from "./agent-tool-types-BNUGGBzQ.js";
+} from "./agent-tool-types-BC-WFlsz.js";
 import { ClientParameters } from "./serializable.js";
 import {
   AgentConnectionError,

package/dist/serializable.d.ts

@@ -1,4 +1,4 @@
-import { st as StreamingResponse } from "./agent-tool-types-BNUGGBzQ.js";
+import { st as StreamingResponse } from "./agent-tool-types-BC-WFlsz.js";
 
 //#region src/serializable.d.ts
 type SerializablePrimitive = undefined | null | string | number | boolean;

package/dist/sub-routing.d.ts

@@ -1,10 +1,10 @@
 import {
-  an as SUB_PREFIX,
-  cn as parseSubAgentPath,
-  ln as routeSubAgentRequest,
-  on as SubAgentPathMatch,
-  sn as getSubAgentByName
-} from "./agent-tool-types-BNUGGBzQ.js";
+  cn as SubAgentPathMatch,
+  dn as routeSubAgentRequest,
+  ln as getSubAgentByName,
+  sn as SUB_PREFIX,
+  un as parseSubAgentPath
+} from "./agent-tool-types-BC-WFlsz.js";
 export {
   SUB_PREFIX,
   SubAgentPathMatch,

package/dist/workflows.d.ts

@@ -1,4 +1,4 @@
-import { O as Agent } from "./agent-tool-types-BNUGGBzQ.js";
+import { O as Agent } from "./agent-tool-types-BC-WFlsz.js";
 import {
   C as WorkflowStatus,
   S as WorkflowRejectedError,

package/docs/human-in-the-loop.md

@@ -25,13 +25,14 @@ Human-in-the-loop (HITL) patterns allow agents to pause execution and wait for h
 
 Agents SDK supports multiple human-in-the-loop patterns. Choose based on your use case:
 
-| Use Case               | Pattern           | Best For                                           | Example                                                                                                      |
-| ---------------------- | ----------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| Long-running workflows | Workflow Approval | Multi-step processes, durable approval gates       | [examples/workflows/](https://github.com/cloudflare/agents/tree/main/examples/workflows)                     |
-| AIChatAgent tools      | `needsApproval`   | Chat-based tool calls with `@cloudflare/ai-chat`   | [guides/human-in-the-loop/](https://github.com/cloudflare/agents/tree/main/guides/human-in-the-loop)         |
-| OpenAI Agents SDK      | `needsApproval`   | Using OpenAI's agent SDK with conditional approval | [openai-sdk/human-in-the-loop/](https://github.com/cloudflare/agents/tree/main/openai-sdk/human-in-the-loop) |
-| Client-side tools      | `onToolCall`      | Tools that need browser APIs or user interaction   | Pattern below                                                                                                |
-| MCP Servers            | Elicitation       | MCP tools requesting structured user input         | [examples/mcp-elicitation/](https://github.com/cloudflare/agents/tree/main/examples/mcp-elicitation)         |
+| Use Case               | Pattern               | Best For                                           | Example                                                                                                        |
+| ---------------------- | --------------------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| Long-running workflows | Workflow Approval     | Multi-step processes, durable approval gates       | [examples/workflows/](https://github.com/cloudflare/agents/tree/main/examples/workflows)                       |
+| AIChatAgent tools      | `needsApproval`       | Chat-based tool calls with `@cloudflare/ai-chat`   | [guides/human-in-the-loop/](https://github.com/cloudflare/agents/tree/main/guides/human-in-the-loop)           |
+| OpenAI Agents SDK      | `needsApproval`       | Using OpenAI's agent SDK with conditional approval | [openai-sdk/human-in-the-loop/](https://github.com/cloudflare/agents/tree/main/openai-sdk/human-in-the-loop)   |
+| Client-side tools      | `onToolCall`          | Tools that need browser APIs or user interaction   | Pattern below                                                                                                  |
+| Stateless servers      | Stateless Elicitation | Current MCP tools requesting structured input      | [examples/mcp-elicitation-mrtr/](https://github.com/cloudflare/agents/tree/main/examples/mcp-elicitation-mrtr) |
+| Legacy servers         | Legacy Elicitation    | Existing sessionful MCP deployments                | [examples/mcp-elicitation/](https://github.com/cloudflare/agents/tree/main/examples/mcp-elicitation)           |
 
 ### Decision Guide
 
@@ -452,85 +453,64 @@ See the complete example: [openai-sdk/human-in-the-loop/](https://github.com/clo
 
 ### MCP Elicitation
 
-When building MCP servers with `McpAgent`, you can request additional user input during tool execution using **elicitation**. The MCP client (like Claude Desktop) renders a form based on your JSON Schema and returns the user's response.
+**Stateless Elicitation** uses multi-round-trip requests (MRTR). A handler returns `inputRequired(...)`; the client gathers the requested input and retries with SDK-managed state. No Worker remains suspended while the user responds.
 
 ```typescript
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { Agent } from "agents";
-
-export class MyMcpAgent extends Agent<Env, State> {
-  server = new McpServer({
-    name: "my-mcp-server",
-    version: "1.0.0"
-  });
-
-  onStart() {
-    this.server.registerTool(
-      "increase-counter",
-      {
-        description: "Increase the counter by a user-specified amount",
-        inputSchema: {
-          confirm: z.boolean().describe("Do you want to increase the counter?")
-        }
-      },
-      async ({ confirm }, extra) => {
-        if (!confirm) {
-          return { content: [{ type: "text", text: "Cancelled." }] };
-        }
-
-        // Request additional input from the user
-        const userInput = await this.server.server.elicitInput(
-          {
-            message: "By how much do you want to increase the counter?",
-            requestedSchema: {
-              type: "object",
-              properties: {
-                amount: {
-                  type: "number",
-                  title: "Amount",
-                  description: "The amount to increase the counter by"
-                }
-              },
-              required: ["amount"]
-            }
-          },
-          { relatedRequestId: extra.requestId }
-        );
-
-        // Check if user accepted or cancelled
-        if (userInput.action !== "accept" || !userInput.content) {
-          return { content: [{ type: "text", text: "Cancelled." }] };
-        }
+import {
+  McpServer,
+  acceptedContent,
+  inputRequired
+} from "@modelcontextprotocol/server";
+import { createMcpHandler } from "agents/mcp/server";
+import { z } from "zod";
 
-        // Use the input
-        const amount = Number(userInput.content.amount);
-        this.setState({
-          ...this.state,
-          counter: this.state.counter + amount
+function createServer() {
+  const server = new McpServer({ name: "my-server", version: "1.0.0" });
+  server.registerTool(
+    "ask-name",
+    { inputSchema: z.object({}) },
+    async (_args, context) => {
+      const answer = acceptedContent(
+        context.mcpReq.inputResponses,
+        "name",
+        z.object({ name: z.string() })
+      );
+      if (!answer) {
+        return inputRequired({
+          inputRequests: {
+            name: inputRequired.elicit({
+              message: "What is your name?",
+              requestedSchema: {
+                type: "object",
+                properties: { name: { type: "string" } },
+                required: ["name"]
+              }
+            })
+          }
         });
-
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Counter increased by ${amount}, now at ${this.state.counter}`
-            }
-          ]
-        };
       }
+      return { content: [{ type: "text", text: `Hello ${answer.name}` }] };
+    }
+  );
+  return server;
+}
+
+export default {
+  fetch(request, env, ctx) {
+    return createMcpHandler(createServer, { legacy: "reject" })(
+      request,
+      env,
+      ctx
     );
   }
-}
+} satisfies ExportedHandler;
 ```
 
-**Key differences from other patterns:**
+The MCP client renders the JSON Schema form and the original operation remains pending from the application's perspective while the SDK completes the rounds.
 
-- Used by **MCP servers** exposing tools to clients, not agents calling tools
-- Uses **JSON Schema** for structured form-based input
-- The **MCP client** (Claude Desktop, etc.) handles UI rendering
-- Returns `{ action: "accept" | "decline", content: {...} }`
+See the [Stateless Elicitation example](https://github.com/cloudflare/agents/tree/main/examples/mcp-elicitation-mrtr).
 
-See the complete example: [examples/mcp-elicitation/](https://github.com/cloudflare/agents/tree/main/examples/mcp-elicitation)
+**Legacy Elicitation** in existing Legacy deployments uses pushed `elicitation/create` requests over a stateful transport. See the explicitly legacy [examples/mcp-elicitation/](https://github.com/cloudflare/agents/tree/main/examples/mcp-elicitation) example when retaining `McpAgent` or `createLegacyMcpHandler` with `WorkerTransport`.
 
 ## State Patterns for Approvals
 
@@ -647,15 +627,16 @@ async submitForApproval(request: ApprovalRequest): Promise<string> {
 
 ## Complete Examples
 
-| Pattern           | Location                                                                                                     | Description                                        |
-| ----------------- | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------- |
-| Workflow approval | [examples/workflows/](https://github.com/cloudflare/agents/tree/main/examples/workflows)                     | Multi-step task processing with approval gate      |
-| AIChatAgent tools | [guides/human-in-the-loop/](https://github.com/cloudflare/agents/tree/main/guides/human-in-the-loop)         | Chat tool approval with needsApproval + onToolCall |
-| OpenAI Agents SDK | [openai-sdk/human-in-the-loop/](https://github.com/cloudflare/agents/tree/main/openai-sdk/human-in-the-loop) | Conditional tool approval with modal               |
-| MCP Elicitation   | [examples/mcp-elicitation/](https://github.com/cloudflare/agents/tree/main/examples/mcp-elicitation)         | MCP server requesting structured user input        |
+| Pattern               | Location                                                                                                       | Description                                        |
+| --------------------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
+| Workflow approval     | [examples/workflows/](https://github.com/cloudflare/agents/tree/main/examples/workflows)                       | Multi-step task processing with approval gate      |
+| AIChatAgent tools     | [guides/human-in-the-loop/](https://github.com/cloudflare/agents/tree/main/guides/human-in-the-loop)           | Chat tool approval with needsApproval + onToolCall |
+| OpenAI Agents SDK     | [openai-sdk/human-in-the-loop/](https://github.com/cloudflare/agents/tree/main/openai-sdk/human-in-the-loop)   | Conditional tool approval with modal               |
+| Stateless Elicitation | [examples/mcp-elicitation-mrtr/](https://github.com/cloudflare/agents/tree/main/examples/mcp-elicitation-mrtr) | Stateless multi-round input                        |
+| Legacy Elicitation    | [examples/mcp-elicitation/](https://github.com/cloudflare/agents/tree/main/examples/mcp-elicitation)           | Stateful pushed input requests                     |
 
 For detailed API documentation, see:
 
 - [Workflows](./workflows.md) - `waitForApproval()`, `approveWorkflow()`, `rejectWorkflow()`
-- [MCP Servers](./mcp-servers.md) - `elicitInput()` for MCP elicitation
+- [MCP Servers](./mcp-servers.md) - `inputRequired()` and legacy `elicitInput()`
 - [Callable Methods](./callable-methods.md) - `@callable()` decorator for approval endpoints

package/docs/mcp-client.md

@@ -15,6 +15,12 @@ The MCP client capability lets your agent:
 
 ## Quick Start
 
+Install the exact MCP client peer used by this Agents release:
+
+```sh
+pnpm add agents @modelcontextprotocol/client@2.0.0
+```
+
 ```typescript
 import { Agent } from "agents";
 
@@ -95,6 +101,20 @@ await this.addMcpServer("internal", "https://internal-mcp.example.com/mcp", {
 });
 ```
 
+### Legacy OAuth metadata compatibility
+
+SDK v2 validates authorization-server metadata issuers by default. A trusted Legacy server with known mismatched RFC 8414 metadata can opt out explicitly:
+
+```typescript
+await this.addMcpServer("legacy", "https://legacy.example.com/mcp", {
+  transport: {
+    skipIssuerMetadataValidation: true
+  }
+});
+```
+
+This weakens OAuth mix-up protection. Do not enable it for unknown servers or as a general fallback.
+
 ### Retry Options
 
 Configure retry behavior for connection and reconnection attempts:
@@ -111,9 +131,13 @@ await this.addMcpServer("github", "https://mcp.github.com/mcp", {
 
 These options are persisted and used when reconnecting after hibernation or after OAuth completion. Default: 3 attempts, 500ms base delay, 5s max delay. See [Retries](./retries.md) for more details.
 
-### Elicitation
+### Protocol negotiation and elicitation
+
+Agents uses the MCP v2 client and automatically negotiates the protocol version for every connection. It uses `server/discover` with Stateless servers and falls back to the `initialize` handshake on the same connection for Legacy Streamable HTTP, SSE, and RPC servers.
 
-MCP servers can request input from the client during a tool call (`elicitation/create`). To respond, configure an elicitation handler before MCP connections are registered or restored:
+MCP servers can request input from the client during `callTool`, `getPrompt`, or `readResource`. Stateless Elicitation returns an `input_required` result and completes through MRTR: the MCP SDK invokes the configured `elicitation/create` handler, sends its response, and continues the original request. Agents does not expose an intermediate continuation; the original call stays pending while human input is collected and eventually resolves to the ordinary tool, prompt, or resource result. Legacy Elicitation on Legacy servers continues to use pushed `elicitation/create` requests. Both generations share the same handlers.
+
+Configure elicitation handlers before MCP connections are registered or restored:
 
 ```typescript
 import { Agent } from "agents";
@@ -136,6 +160,8 @@ class MyAgent extends Agent<Env> {
 
 The advertised modes are persisted with each MCP server, so a connection restored from storage after hibernation re-advertises the same modes at the handshake; the handlers themselves re-attach when `onStart()` runs. Configuring a handler after an MCP connection is already active updates the in-memory handler, but the server only sees new advertised elicitation modes after that connection reconnects.
 
+Handlers and pending calls are memory-only. A Durable Object hibernation or isolate restart does not preserve an in-flight interactive call; callers must retry it after the connection is restored. Agents intentionally does not persist in-flight Stateless `requestState` or implement a manual/resumable continuation layer.
+
 Connections advertise only the elicitation modes with configured handlers at the `initialize` handshake: configure `form` to advertise form-mode elicitation, `url` to advertise url-mode elicitation (MCP spec 2025-11-25 — url mode is used for sensitive flows like OAuth URLs), or both to advertise both modes. Without handlers, connections advertise no elicitation capability, so spec-compliant servers use their non-elicitation fallbacks instead of sending requests the agent cannot answer.
 
 To override the advertised modes, declare them explicitly — an explicit declaration always wins and is persisted with the server options, surviving hibernation:
@@ -416,7 +442,7 @@ function Dashboard() {
     onMcpUpdate: (mcpState) => {
       setTools(mcpState.tools);
       setServers(mcpState.servers);
-    }
+    },
   });
 
   return (
@@ -429,10 +455,8 @@ function Dashboard() {
       ))}
 
       <h2>Available Tools ({tools.length})</h2>
-      {tools.map(tool => (
-        <div key={`${tool.serverId}-${tool.name}`}>
-          {tool.name}
-        </div>
+      {tools.map((tool) => (
+        <div key={`${tool.serverId}-${tool.name}`}>{tool.name}</div>
       ))}
     </div>
   );

package/docs/mcp-servers.md

@@ -4,23 +4,27 @@ This guide covers the different ways to create MCP servers with the Agents SDK a
 
 ## Choosing an Approach
 
-| Approach                                       | Stateful? | Requires Durable Objects? | Best for                                       |
-| ---------------------------------------------- | --------- | ------------------------- | ---------------------------------------------- |
-| `createMcpHandler()`                           | No        | No                        | Stateless tools, simplest setup                |
-| `McpAgent`                                     | Yes       | Yes                       | Stateful tools, per-session state, elicitation |
-| Raw `WebStandardStreamableHTTPServerTransport` | No        | No                        | Full control, no SDK dependency                |
+| Approach                                       | Stateful? | Requires Durable Objects? | Best for                                          |
+| ---------------------------------------------- | --------- | ------------------------- | ------------------------------------------------- |
+| `createMcpHandler()`                           | No        | No                        | New servers and the draft MCP protocol            |
+| `McpAgent` (deprecated legacy path)            | Yes       | Yes                       | Existing stateful SDK v1 deployments              |
+| Raw `WebStandardStreamableHTTPServerTransport` | No        | No                        | Low-level control without the Agents HTTP wrapper |
 
-- **`createMcpHandler()`** is the fastest way to get a stateless MCP server running. Use it when your tools do not need per-session state.
-- **`McpAgent`** gives you a Durable Object per session with built-in state management, elicitation support, and both SSE and Streamable HTTP transports.
-- **Raw transport** gives you full control if you want to use the `@modelcontextprotocol/sdk` directly without the Agents SDK helpers.
+- **`createMcpHandler()`** is the current server-development path. It serves draft MCP `2026-07-28` and supports stateless published 2025 clients by default.
+- **`McpAgent`** is a retained, feature-frozen SDK v1 path for existing stateful deployments. New servers should use `createMcpHandler()`.
+- **Raw transport** gives you low-level control if the standard handler lifecycle is not suitable.
 
 ## Stateless MCP Server with `createMcpHandler()`
 
-The simplest way to create an MCP server. No Durable Objects or bindings required:
+The simplest way to create an MCP server. Install the exact SDK v2 server peer, then use the isolated server entry point so legacy Agents transports and MCP clients stay out of your Worker bundle:
+
+```sh
+pnpm add agents @modelcontextprotocol/server@2.0.0 zod
+```
 
 ```typescript
-import { createMcpHandler } from "agents/mcp";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { McpServer } from "@modelcontextprotocol/server";
+import { createMcpHandler } from "agents/mcp/server";
 import { z } from "zod";
 
 function createServer() {
@@ -44,45 +48,77 @@ function createServer() {
 }
 
 export default {
-  fetch: async (request: Request, env: Env, ctx: ExecutionContext) => {
-    const server = createServer();
-    return createMcpHandler(server)(request, env, ctx);
+  fetch(request, env, ctx) {
+    return createMcpHandler(createServer)(request, env, ctx);
   }
-};
+} satisfies ExportedHandler;
 ```
 
-> **Important:** Create a new `McpServer` instance per request. The MCP SDK does not allow connecting an already-connected server to a new transport.
+`createMcpHandler` requires a factory so concurrent Worker requests receive isolated server instances. A function input is always treated as an SDK v2 factory.
 
-### `createMcpHandler` Options
+### `createMcpHandler` options
 
 ```typescript
-createMcpHandler(server, {
-  route: "/mcp",              // path to handle (default: "/mcp")
-  enableJsonResponse: true,   // use JSON responses instead of SSE streaming
-  sessionIdGenerator: () => crypto.randomUUID(),
-  corsOptions: { ... },       // CORS configuration
-  authContext: { props: {} },  // manually set auth context
-  transport: workerTransport   // provide your own WorkerTransport instance
+createMcpHandler(() => createServer(), {
+  route: "/mcp", // exact path to handle (default: "/mcp")
+  corsOptions: {
+    origin: "https://app.example.com"
+  },
+  allowedHostnames: ["mcp.example.com"], // custom-domain Host policy
+  allowedOriginHostnames: ["app.example.com"], // browser Origin policy
+  authContext: { props: {} }, // optional application props override
+  legacy: "stateless", // upstream default; use "reject" for Stateless-only
+  responseMode: "auto" // upstream SDK response shaping
 });
 ```
 
+All upstream SDK v2 handler options pass through. Use `createLegacyMcpHandler` for WorkerTransport, storage, session, and event-store options.
+
+The handler validates every present `Origin` header before serving the request. It rejects malformed, opaque, and non-HTTP origins. Requests without `Origin` remain valid for non-browser MCP clients.
+
+Its default allowlist includes localhost-class origins and the endpoint's `workers.dev` hostname. A concrete `corsOptions.origin` adds that hostname automatically. The handler also applies matching Host checks to localhost and `workers.dev` endpoints. For a custom domain with wildcard CORS, configure `allowedHostnames` and `allowedOriginHostnames` explicitly. Values are hostnames without a scheme or port, and matching ignores the Origin's scheme and port.
+
+Pass `allowedOriginHostnames: "*"` only when equivalent Origin validation runs in trusted middleware before the handler. This explicitly disables the handler's Origin check, including malformed and opaque Origin rejection. MCP HTTP servers are required to validate browser Origins, so do not use this as an unauthenticated public-server shortcut.
+
+### 2025 compatibility and elicitation
+
+The default `legacy: "stateless"` lane supports ordinary 2025 tools, resources, and prompts. It has no session return path for push-style server-to-client requests; attempts to sample, elicit, or list roots fail immediately with guidance to use a sessionful transport.
+
+Applications that must serve both generations can route before `createMcpHandler`: send Stateless requests to a strict handler and Legacy requests to an existing session-addressed Agent or transport. See [`examples/mcp-elicitation-mrtr`](../../examples/mcp-elicitation-mrtr/) for Stateless Elicitation and [`examples/mcp-elicitation`](../../examples/mcp-elicitation/) for Legacy Elicitation.
+
+For an explicit Legacy handler, use the retained Legacy API:
+
+```typescript
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { createLegacyMcpHandler } from "agents/mcp";
+
+const server = new McpServer({ name: "legacy", version: "1.0.0" });
+export default createLegacyMcpHandler(server);
+```
+
+Passing an SDK v1 server directly to `createMcpHandler` still forwards to this API for compatibility, but that overload is deprecated, emits a migration warning, and is removed in the next major release. `createLegacyMcpHandler` and `WorkerTransport` themselves are not deprecated.
+
 ### Accessing Authenticated User Context
 
-When your MCP server is wrapped with `OAuthProvider` from `@cloudflare/workers-oauth-provider`, authenticated user information is available inside tools via `getMcpAuthContext()`:
+When your MCP server is wrapped with `OAuthProvider` from `@cloudflare/workers-oauth-provider`, provider-issued tokens are available through standard SDK v2 `AuthInfo`. The existing `getMcpAuthContext()` application-props helper remains supported:
 
 ```typescript
-import { createMcpHandler, getMcpAuthContext } from "agents/mcp";
+import { createMcpHandler, getMcpAuthContext } from "agents/mcp/server";
 
 server.registerTool(
   "whoami",
   { description: "Returns the authenticated user" },
-  async () => {
+  async (context) => {
     const auth = getMcpAuthContext();
     return {
       content: [
         {
           type: "text",
-          text: auth ? JSON.stringify(auth.props) : "Not authenticated"
+          text: JSON.stringify({
+            clientId: context.http?.authInfo?.clientId,
+            scopes: context.http?.authInfo?.scopes,
+            props: auth?.props
+          })
         }
       ]
     };
@@ -90,11 +126,11 @@ server.registerTool(
 );
 ```
 
-The `OAuthProvider` sets `ctx.props` on the execution context, which `createMcpHandler` automatically picks up and makes available via `getMcpAuthContext()`.
+Do not log or return `context.http.authInfo.token`. External-token resolvers continue providing `getMcpAuthContext().props` but do not synthesize incomplete standard metadata.
 
-## Stateful MCP Server with `McpAgent`
+## Stateful MCP Server with `McpAgent` (legacy)
 
-`McpAgent` gives each client session its own Durable Object with persistent state. Use this when your tools need to track per-session data.
+`McpAgent` gives each client session its own Durable Object with persistent state. It remains available for existing SDK v1 deployments but is deprecated and feature-frozen; new servers should use the stateless handler or explicitly compose a separate legacy route where a session is required.
 
 ### Writing TinyMCP
 
@@ -428,76 +464,77 @@ The `jurisdiction` option accepts any value supported by [Cloudflare's Durable O
 
 ## Elicitation (Human-in-the-Loop)
 
-MCP servers can request additional input from the user during a tool call using elicitation. This is useful for confirmation dialogs, requesting amounts, or any interactive tool flow.
+MCP servers can request additional input during a tool call. The implementation differs by protocol generation.
+
+### Stateless Elicitation
 
-Elicitation is supported via `McpAgent` (which manages the request/response lifecycle through Durable Object storage) or via `WorkerTransport` (for stateful non-McpAgent setups).
+For Stateless Elicitation, return `inputRequired(...)`. The client gathers the input and retries the request with SDK-managed `requestState` and `inputResponses`; the Worker does not suspend while a person responds.
 
 ```typescript
-import { McpAgent } from "agents/mcp";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import {
+  McpServer,
+  acceptedContent,
+  inputRequired
+} from "@modelcontextprotocol/server";
+import { createMcpHandler } from "agents/mcp/server";
 import { z } from "zod";
 
-export class MyMCP extends McpAgent<Env, { counter: number }> {
-  server = new McpServer({ name: "Elicitation Demo", version: "1.0.0" });
-
-  initialState = { counter: 0 };
-
-  async init() {
-    this.server.registerTool(
-      "increase-counter",
-      {
-        description: "Increase the counter",
-        inputSchema: {
-          confirm: z.boolean().describe("Do you want to increase the counter?")
-        }
-      },
-      async ({ confirm }, extra) => {
-        if (!confirm) {
-          return { content: [{ type: "text", text: "Cancelled." }] };
-        }
-
-        const result = await this.server.server.elicitInput(
-          {
-            message: "By how much?",
-            requestedSchema: {
-              type: "object",
-              properties: {
-                amount: { type: "number", title: "Amount" }
-              },
-              required: ["amount"]
-            }
-          },
-          { relatedRequestId: extra.requestId }
-        );
-
-        if (result.action !== "accept" || !result.content?.amount) {
-          return { content: [{ type: "text", text: "Cancelled." }] };
-        }
-
-        const amount = Number(result.content.amount);
-        this.setState({ counter: this.state.counter + amount });
-
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Counter increased by ${amount}, now ${this.state.counter}`
-            }
-          ]
-        };
+function createServer() {
+  const server = new McpServer({
+    name: "Stateless Elicitation Demo",
+    version: "1.0.0"
+  });
+  server.registerTool(
+    "ask-name",
+    { inputSchema: z.object({}) },
+    async (_args, context) => {
+      const answer = acceptedContent(
+        context.mcpReq.inputResponses,
+        "name",
+        z.object({ name: z.string() })
+      );
+      if (!answer) {
+        return inputRequired({
+          inputRequests: {
+            name: inputRequired.elicit({
+              message: "What is your name?",
+              requestedSchema: {
+                type: "object",
+                properties: { name: { type: "string" } },
+                required: ["name"]
+              }
+            })
+          }
+        });
       }
-    );
-  }
+      return { content: [{ type: "text", text: `Hello ${answer.name}` }] };
+    }
+  );
+  return server;
 }
 
-export default MyMCP.serve("/mcp");
+export default {
+  fetch(request, env, ctx) {
+    return createMcpHandler(createServer, { legacy: "reject" })(
+      request,
+      env,
+      ctx
+    );
+  }
+} satisfies ExportedHandler;
 ```
 
-See the [`examples/mcp-elicitation`](https://github.com/cloudflare/agents/tree/main/examples/mcp-elicitation) example for a full working demo.
+See [`examples/mcp-elicitation-mrtr`](https://github.com/cloudflare/agents/tree/main/examples/mcp-elicitation-mrtr) for a two-round Stateless Elicitation example.
+
+### Legacy Elicitation
+
+Existing Legacy deployments send pushed `elicitation/create` requests over a session-addressed response stream. Use `McpAgent` or `createLegacyMcpHandler` with `WorkerTransport` when that behavior must be retained.
+
+See [`examples/mcp-elicitation`](https://github.com/cloudflare/agents/tree/main/examples/mcp-elicitation) for form- and URL-mode Legacy Elicitation with Durable Object state and SSE replay.
 
 ## WorkerTransport
 
-`WorkerTransport` is a server-side transport for running MCP servers in stateless Workers while optionally persisting session state. It is used internally by `createMcpHandler()` but can also be used directly for advanced scenarios like stateful sessions without `McpAgent`.
+`WorkerTransport` is the retained Agents transport for stateful Legacy deployments. Use it with `createLegacyMcpHandler` for persistent sessions, storage, event replay, and other explicit legacy configurations. The Stateless handler's Legacy compatibility lane uses the SDK v2 web-standard transport instead and does not import `WorkerTransport`.
 
 ```typescript
 import { WorkerTransport, type TransportState } from "agents/mcp";

package/docs/observability.md

@@ -466,8 +466,9 @@ exists:
 | `cloudflare.agents.runtime_context.{key}`                                               | Explicitly included scalar runtime context                              |
 | `cloudflare.agents.tool_context.{tool}.{key}`                                           | Explicitly included scalar context on the executed tool span            |
 | `cloudflare.agents.metadata.{key}`                                                      | Other scalar v6 telemetry metadata                                      |
-| `cloudflare.agents.turn.{request_id,trigger,admission,channel,continuation,generation}` | Think turn context                                                      |
+| `cloudflare.agents.turn.{request_id,trigger,admission,channel,continuation,generation}` | Think turn context, from v6 metadata or v7 runtime context              |
 | `cloudflare.agents.canceled`                                                            | Recognized cancellation, not a failure                                  |
+| `cloudflare.agents.span.truncated`                                                      | Span closed by its invocation ending before the work finished           |
 
 `gen_ai.response.finish_reasons` and `gen_ai.request.stop_sequences` are arrays
 in OTel. Workers' custom `Span.setAttribute` currently accepts only a string,