Sync docs for PR #620: feat: elicit-me example

This commit syncs documentation changes from cloudflare/agents PR #620.

Changes:
- Add new elicitation.mdx documentation covering MCP elicitation feature
- Update transport.mdx with storage and authContext configuration options
- Update authorization.mdx to reflect new API where auth is accessed via extra.authInfo

Related PR: cloudflare/agents#620

Author: github-actions[bot]

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

@@ -204,9 +204,9 @@ You can implement fine-grained authorization controls for your MCP tools based o
 ```js
 // Create a wrapper function to check permissions
 function requirePermission(permission, handler) {
-  return async (request, context) => {
+  return async (args, extra) => {
     // Check if user has the required permission
-    const userPermissions = context.props.permissions || [];
+    const userPermissions = extra.authInfo?.extra?.permissions || [];
     if (!userPermissions.includes(permission)) {
       return {
         content: [{ type: "text", text: `Permission denied: requires ${permission}` }],
@@ -215,7 +215,7 @@ function requirePermission(permission, handler) {
     }
 
     // If permission check passes, execute the handler
-    return handler(request, context);
+    return handler(args, extra);
   };
 }
 
@@ -231,20 +231,23 @@ async init() {
     "adminAction",
     "Administrative action requiring special permission",
     { /* parameters */ },
-    requirePermission("admin", async (req) => {
+    requirePermission("admin", async (args, extra) => {
       // Only executes if user has "admin" permission
       return {
         content: [{ type: "text", text: "Admin action completed" }]
       };
     })
   );
 
-  // Conditionally register tools based on user permissions
-  if (this.props.permissions?.includes("special_feature")) {
-    this.server.tool("specialTool", "Special feature", {}, async () => {
-      // This tool only appears for users with the special_feature permission
-    });
-  }
+  // Access auth context directly in tools
+  this.server.tool("whoami", "Get current user", {}, async (_, extra) => {
+    const auth = extra.authInfo;
+    const username = auth?.extra?.username || "Unknown";
+
+    return {
+      content: [{ type: "text", text: `Current user: ${username}` }]
+    };
+  });
 }
 ```
 

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

@@ -0,0 +1,261 @@
+---
+pcx_content_type: concept
+title: Elicitation
+tags:
+  - MCP
+sidebar:
+  order: 7
+---
+
+import { Render, TypeScriptExample } from "~/components";
+
+Elicitation is an MCP feature that allows servers to request additional input from users during tool execution. This enables interactive workflows where tools can prompt users for confirmation, collect form data, or gather additional information needed to complete an operation.
+
+## Overview
+
+The [MCP Elicitation specification](https://modelcontextprotocol.io/specification/draft/client/elicitation) defines a standard way for MCP servers to request user input through a structured schema. When a tool needs additional information, it can use `elicitInput()` to:
+
+- Request user confirmation before performing sensitive operations
+- Collect structured form data (text fields, dropdowns, checkboxes)
+- Validate input through JSON Schema
+- Handle user responses (accept, decline, or cancel)
+
+## Basic example
+
+Here's a simple example of an MCP server that uses elicitation to request confirmation before incrementing a counter:
+
+<TypeScriptExample>
+
+```ts title="src/index.ts"
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { createMcpHandler, WorkerTransport } from "agents/mcp";
+import { Agent, getAgentByName } from "agents";
+import { z } from "zod";
+
+interface State {
+  counter: number;
+}
+
+export class MyAgent extends Agent<Env, State> {
+  server = new McpServer({
+    name: "Elicitation Demo",
+    version: "1.0.0"
+  });
+
+  transport = new WorkerTransport({
+    sessionIdGenerator: () => this.name,
+    storage: this.ctx.storage
+  });
+
+  initialState = { counter: 0 };
+
+  onStart() {
+    this.server.registerTool(
+      "increase-counter",
+      {
+        description: "Increase the counter",
+        inputSchema: z.object({
+          amount: z.number().default(1)
+        }).shape
+      },
+      async (args) => {
+        // Request user input via elicitation
+        const result = 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"]
+          }
+        });
+
+        if (result.action !== "accept" || !result.content) {
+          return {
+            content: [{ type: "text", text: "Counter increase cancelled." }]
+          };
+        }
+
+        this.state.counter += Number(result.content.amount);
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Counter increased by ${result.content.amount}, current value is ${this.state.counter}`
+            }
+          ]
+        };
+      }
+    );
+  }
+
+  async onMcpRequest(request: Request) {
+    return createMcpHandler(this.server, {
+      transport: this.transport
+    })(request, this.env, {} as ExecutionContext);
+  }
+}
+
+export default {
+  async fetch(request: Request, env: Env, _ctx: ExecutionContext) {
+    const sessionId = request.headers.get("mcp-session-id") ?? crypto.randomUUID();
+    const agent = await getAgentByName(env.MyAgent, sessionId);
+    return await agent.onMcpRequest(request);
+  }
+};
+```
+
+</TypeScriptExample>
+
+## Elicitation response types
+
+When you call `elicitInput()`, the user can respond in three ways:
+
+- **accept** — User confirmed and provided the requested data
+- **decline** — User explicitly rejected the request
+- **cancel** — User dismissed without making a choice
+
+Your tool should handle all three responses appropriately:
+
+```ts
+const result = await this.server.server.elicitInput({
+  message: "Confirm this action?",
+  requestedSchema: {
+    type: "object",
+    properties: {
+      confirmed: { type: "boolean" }
+    },
+    required: ["confirmed"]
+  }
+});
+
+if (result.action === "accept" && result.content?.confirmed) {
+  // User confirmed - proceed with operation
+  return { content: [{ type: "text", text: "Operation completed!" }] };
+} else if (result.action === "decline") {
+  // User explicitly declined
+  return { content: [{ type: "text", text: "Operation declined." }] };
+} else {
+  // User cancelled or provided invalid data
+  return { content: [{ type: "text", text: "Operation cancelled." }] };
+}
+```
+
+## Form schemas
+
+Elicitation supports various input types through JSON Schema:
+
+### Text input
+```ts
+properties: {
+  username: {
+    type: "string",
+    title: "Username",
+    description: "Enter your username"
+  }
+}
+```
+
+### Email input
+```ts
+properties: {
+  email: {
+    type: "string",
+    format: "email",
+    title: "Email Address"
+  }
+}
+```
+
+### Boolean/checkbox
+```ts
+properties: {
+  confirmed: {
+    type: "boolean",
+    title: "I agree to the terms"
+  }
+}
+```
+
+### Dropdown/select
+```ts
+properties: {
+  role: {
+    type: "string",
+    title: "Role",
+    enum: ["viewer", "editor", "admin"],
+    enumNames: ["Viewer", "Editor", "Admin"]
+  }
+}
+```
+
+## Complex forms
+
+You can combine multiple fields to create complex forms:
+
+```ts
+const userInfo = await this.server.server.elicitInput({
+  message: "Create new user account:",
+  requestedSchema: {
+    type: "object",
+    properties: {
+      username: {
+        type: "string",
+        title: "Username"
+      },
+      email: {
+        type: "string",
+        format: "email",
+        title: "Email Address"
+      },
+      role: {
+        type: "string",
+        title: "Role",
+        enum: ["viewer", "editor", "admin"],
+        enumNames: ["Viewer", "Editor", "Admin"]
+      },
+      sendWelcome: {
+        type: "boolean",
+        title: "Send Welcome Email"
+      }
+    },
+    required: ["username", "email", "role"]
+  }
+});
+```
+
+## Persistent sessions with storage
+
+To maintain elicitation state across server hibernation and restarts, use the `storage` option in `WorkerTransport`:
+
+```ts
+transport = new WorkerTransport({
+  sessionIdGenerator: () => this.name,
+  storage: this.ctx.storage  // Persist transport state
+});
+```
+
+This ensures that:
+- Session IDs survive hibernation
+- Pending elicitation requests are restored after restart
+- Client connections can resume seamlessly
+
+## Working example
+
+For a complete working example, see the [mcp-elicitation example](https://github.com/cloudflare/agents/tree/main/examples/mcp-elicitation) in the Agents SDK repository.
+
+## Client support
+
+Elicitation support varies by MCP client:
+
+- **Claude Desktop** — Full support for elicitation
+- **Cursor** — Supported via [mcp-remote](https://www.npmjs.com/package/mcp-remote)
+- **Windsurf** — Supported via [mcp-remote](https://www.npmjs.com/package/mcp-remote)
+
+Check your MCP client's documentation for specific elicitation capabilities.

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

@@ -105,6 +105,65 @@ To use apiHandlers, update to @cloudflare/workers-oauth-provider v0.0.4 or later
 
 With these few changes, your MCP server will support both transport methods, making it compatible with both existing and new clients.
 
+## Advanced transport configuration
+
+### Persistent sessions with storage
+
+When using `createMcpHandler` with `WorkerTransport`, you can enable session persistence across server hibernation and restarts by providing the `storage` option:
+
+```ts
+import { createMcpHandler, WorkerTransport } from "agents/mcp";
+
+const transport = new WorkerTransport({
+  sessionIdGenerator: () => this.name,
+  storage: this.ctx.storage  // Persist transport state in Durable Object storage
+});
+
+async onMcpRequest(request: Request) {
+  return createMcpHandler(this.server, {
+    transport: this.transport
+  })(request, this.env, {} as ExecutionContext);
+}
+```
+
+This ensures that:
+- Session IDs survive server hibernation
+- Protocol version negotiation is preserved
+- Elicitation state persists across restarts
+- Connections can resume seamlessly
+
+### Custom authentication context
+
+When using `createMcpHandler`, you can provide custom authentication context that will be available to your tools:
+
+```ts
+import { createMcpHandler } from "agents/mcp";
+
+return createMcpHandler(server, {
+  authContext: {
+    props: {
+      userId: "user123",
+      username: "john",
+      email: "[email protected]"
+    }
+  }
+})(request, env, ctx);
+```
+
+Your tools can then access this context via the `extra` parameter:
+
+```ts
+server.tool("whoami", "Get current user", {}, async (_, extra) => {
+  const auth = extra.authInfo;
+  return {
+    content: [{
+      type: "text",
+      text: `User: ${auth?.extra?.username}`
+    }]
+  };
+});
+```
+
 ### Testing with MCP clients
 While most MCP clients have not yet adopted the new Streamable HTTP transport, you can start testing it today using [`mcp-remote`](https://www.npmjs.com/package/mcp-remote), an adapter that lets MCP clients that otherwise only support local connections work with remote MCP servers.