docs: add MCP elicitation guide and transport storage API

Synced from cloudflare/agents#620

Changes:
- Add comprehensive elicitation documentation with examples
- Document new WorkerTransport storage API for session persistence
- Update transport docs with MCPStorageApi and TransportState interfaces
- Simplify MCP elicitation example (removed complex UI demo)

Related PR: cloudflare/agents#620

Author: Cloudflare AI Agent

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

@@ -0,0 +1,331 @@
+---
+pcx_content_type: concept
+title: Elicitation
+tags:
+  - MCP
+sidebar:
+  order: 7
+---
+
+import { Render, TypeScriptExample } from "~/components";
+
+[Elicitation](https://spec.modelcontextprotocol.io/specification/2025-03-26/client/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 clarification, confirmation, or additional details.
+
+## What is Elicitation?
+
+Elicitation provides a standardized way for MCP servers to:
+
+- Request user confirmation before performing sensitive operations
+- Collect additional information that wasn't included in the initial tool call
+- Present forms for structured data input
+- Enable interactive, multi-step workflows
+
+The MCP client (like Claude Desktop) presents elicitation requests to users through appropriate UI elements (buttons, forms, etc.) and returns the user's response to the server.
+
+## Using Elicitation in MCP Servers
+
+When building MCP servers with the Agents SDK, you can use the built-in `elicitInput()` method from the MCP SDK to request user input during tool execution.
+
+### Basic Example
+
+Here's a simple example that uses elicitation to request user confirmation and collect additional information:
+
+<TypeScriptExample>
+
+```ts title="src/index.ts"
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { createMcpHandler, WorkerTransport, type TransportState } from "agents/mcp";
+import { Agent, getAgentByName } from "agents";
+import { z } from "zod";
+import { CfWorkerJsonSchemaValidator } from "@modelcontextprotocol/sdk/validation/cfworker-provider.js";
+
+const STATE_KEY = "mcp_transport_state";
+
+type Env = {
+  MyAgent: DurableObjectNamespace<MyAgent>;
+};
+
+interface State {
+  counter: number;
+}
+
+export class MyAgent extends Agent<Env, State> {
+  server = new McpServer(
+    {
+      name: "elicitation-demo",
+      version: "1.0.0"
+    },
+    {
+      jsonSchemaValidator: new CfWorkerJsonSchemaValidator()
+    }
+  );
+
+  // Create transport with storage for session persistence
+  transport = new WorkerTransport({
+    sessionIdGenerator: () => this.name,
+    storage: {
+      get: () => {
+        return this.ctx.storage.kv.get<TransportState>(STATE_KEY);
+      },
+      set: (state: TransportState) => {
+        this.ctx.storage.kv.put<TransportState>(STATE_KEY, state);
+      }
+    }
+  });
+
+  initialState = {
+    counter: 0
+  };
+
+  onStart(): void | Promise<void> {
+    // Register a tool that uses elicitation
+    this.server.registerTool(
+      "increase-counter",
+      {
+        description: "Increase the counter with user confirmation",
+        inputSchema: {
+          confirm: z.boolean().describe("Do you want to increase the counter?")
+        }
+      },
+      async ({ confirm }) => {
+        if (!confirm) {
+          return {
+            content: [{ type: "text", text: "Counter increase cancelled." }]
+          };
+        }
+
+        try {
+          // Use elicitation to ask for the increment amount
+          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",
+                  minimum: 1
+                }
+              },
+              required: ["amount"]
+            }
+          });
+
+          // Handle the user's response
+          if (result.action !== "accept" || !result.content) {
+            return {
+              content: [{ type: "text", text: "Counter increase cancelled." }]
+            };
+          }
+
+          // Update state with the user-provided amount
+          const amount = Number(result.content.amount);
+          if (amount) {
+            this.setState({
+              ...this.state,
+              counter: this.state.counter + amount
+            });
+
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: `Counter increased by ${amount}, current value is ${this.state.counter}`
+                }
+              ]
+            };
+          }
+
+          return {
+            content: [
+              { type: "text", text: "Invalid amount provided." }
+            ]
+          };
+        } catch (error) {
+          console.error(error);
+          return {
+            content: [{ type: "text", text: "Counter increase failed." }]
+          };
+        }
+      }
+    );
+  }
+
+  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 Schema
+
+The `requestedSchema` follows JSON Schema format and supports various input types:
+
+### Boolean Confirmation
+
+```ts
+{
+  type: "object",
+  properties: {
+    confirmed: {
+      type: "boolean",
+      title: "Confirm action",
+      description: "Check to confirm"
+    }
+  },
+  required: ["confirmed"]
+}
+```
+
+### Text Input
+
+```ts
+{
+  type: "object",
+  properties: {
+    username: {
+      type: "string",
+      title: "Username",
+      description: "Enter your username"
+    },
+    email: {
+      type: "string",
+      format: "email",
+      title: "Email Address"
+    }
+  },
+  required: ["username", "email"]
+}
+```
+
+### Dropdown Selection
+
+```ts
+{
+  type: "object",
+  properties: {
+    role: {
+      type: "string",
+      title: "User Role",
+      enum: ["viewer", "editor", "admin"],
+      enumNames: ["Viewer", "Editor", "Administrator"]
+    }
+  },
+  required: ["role"]
+}
+```
+
+### Numeric Input
+
+```ts
+{
+  type: "object",
+  properties: {
+    amount: {
+      type: "number",
+      title: "Amount",
+      description: "Enter an amount",
+      minimum: 1,
+      maximum: 100
+    }
+  },
+  required: ["amount"]
+}
+```
+
+## Handling Elicitation Responses
+
+The `elicitInput()` method returns a result with an `action` field:
+
+- `"accept"`: User accepted and provided data (available in `result.content`)
+- `"decline"`: User explicitly declined the request
+- `"cancel"`: User dismissed the request without a choice
+
+```ts
+const result = await this.server.server.elicitInput({
+  message: "Are you sure?",
+  requestedSchema: { /* ... */ }
+});
+
+if (result.action === "accept" && result.content) {
+  // User accepted and provided data
+  const userData = result.content;
+  // Process the data...
+} else if (result.action === "decline") {
+  // User explicitly declined
+  return { content: [{ type: "text", text: "Action declined." }] };
+} else {
+  // User cancelled (dismissed)
+  return { content: [{ type: "text", text: "Action cancelled." }] };
+}
+```
+
+## Session Persistence with Storage
+
+When using elicitation with the Agents SDK, you should provide a storage implementation to persist session state across requests. This is important because elicitation involves multiple round trips between the server and client.
+
+The storage API uses two methods:
+
+- `get()`: Retrieve stored transport state
+- `set(state)`: Persist transport state
+
+```ts
+const transport = new WorkerTransport({
+  sessionIdGenerator: () => this.name,
+  storage: {
+    get: () => {
+      return this.ctx.storage.kv.get<TransportState>(STATE_KEY);
+    },
+    set: (state: TransportState) => {
+      this.ctx.storage.kv.put<TransportState>(STATE_KEY, state);
+    }
+  }
+});
+```
+
+This ensures that:
+- Session IDs are preserved across requests
+- The transport state remains consistent during elicitation flows
+- Multiple elicitation requests can be handled sequentially
+
+## Best Practices
+
+1. **Validate user input**: Always validate the data returned from elicitation requests before using it.
+
+2. **Provide clear messages**: Use descriptive messages and titles to explain what information you're requesting and why.
+
+3. **Handle all response types**: Check for `accept`, `decline`, and `cancel` actions to handle all user responses appropriately.
+
+4. **Use appropriate input types**: Choose the right schema type (boolean, string, number, enum) for the data you need.
+
+5. **Keep forms simple**: Request only essential information in each elicitation to avoid overwhelming users.
+
+6. **Provide defaults**: Use JSON Schema defaults where appropriate to suggest common values.
+
+## Client Support
+
+Elicitation requires MCP client support. Currently supported by:
+
+- Claude Desktop (version 0.7.0+)
+- Other MCP clients implementing the [MCP elicitation specification](https://spec.modelcontextprotocol.io/specification/2025-03-26/client/elicitation/)
+
+Check your MCP client's documentation for specific elicitation support details.
+
+## Related Resources
+
+- [MCP Elicitation Specification](https://spec.modelcontextprotocol.io/specification/2025-03-26/client/elicitation/)
+- [MCP Elicitation Example](https://github.com/cloudflare/agents/tree/main/examples/mcp-elicitation)
+- [MCP Server API Reference](/agents/model-context-protocol/mcp-agent-api/)