feat: elicit-me example #620

mattzcarey · 2025-10-31T20:18:07Z

Things to think about with this pattern:

AuthContext
This is really annoying because the types we get from props are not the same as the auth types in the extra param in tools etc. At the moment you can access them with asyncLocalStorage
Storage
The storage interface is pretty extensible. It would be cool to have patterns with kv or even cookies and no DO at all. This would tee us up very well for the stateless by default SEP coming soon to MCP.

changeset-bot · 2025-10-31T20:18:11Z

⚠️ No Changeset found

Latest commit: 5731ffe

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

pkg-pr-new · 2025-10-31T20:20:30Z

Open in StackBlitz

npm i https://pkg.pr.new/cloudflare/agents@620

commit: 5731ffe

claude · 2025-11-12T11:55:05Z

Claude Code Review

PR Summary: Adds MCP elicitation support with persistent transport state, comprehensive tests, and refactored example.

Issues Found

1. Type mismatch in elicitation example (examples/mcp-elicitation/src/index.ts:49)

The example uses server.registerTool() but mixes Zod with JSON Schema incorrectly. The inputSchema expects a JSON Schema object, not Zod. Line 54 has:
inputSchema: { confirm: z.boolean().describe(...) }

Should be JSON Schema:
inputSchema: {
type: "object",
properties: {
confirm: { type: "boolean", description: "..." }
},
required: ["confirm"]
}

2. Incorrect schema property (examples/mcp-elicitation/src/index.ts:73)

minLength: 1 is for strings, not numbers. Should be minimum: 1 or removed.

3. Race condition potential (packages/agents/src/mcp/worker-transport.ts:522-523)

saveState() called immediately after sync initialization. If restoreState() async call has not completed, could cause state conflicts.

4. Potential memory leak (packages/agents/src/mcp/worker-transport.ts:332)

keepAlive interval might not clear if client aborts before cleanup. Try-catch helps but does not guarantee clearing.

5. Error loses context (examples/mcp-elicitation/src/index.ts:108)

console.log(error) followed by generic message loses debugging info.

Testing Coverage

Excellent: 690 lines covering CORS, protocol versions, sessions, storage, errors

Architecture

Clean separation: handler routes, transport manages protocol. Storage abstraction enables persistence.

Recommendation

Fix type/schema issues (1-2) before merge. Issues 3-5 are edge cases worth noting.

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

threepointone · 2025-11-12T11:58:09Z

📚 Documentation sync PR created: cloudflare/cloudflare-docs#26453

threepointone

stamping, but with notes on storage usage

packages/agents/src/mcp/worker-transport.ts

threepointone · 2025-11-12T12:00:44Z

think you need to run npm i and update package lock to pass CI

examples/mcp-elicitation/src/index.ts

examples/mcp-worker-authenticated/src/index.ts

threepointone · 2025-11-12T12:53:09Z

📚 Documentation Sync Complete

Documentation has been updated in the cloudflare-docs repository to reflect the changes in this PR.

Documentation PR

cloudflare-docs PR: cloudflare/cloudflare-docs#26453

Changes Documented

This PR introduces several new MCP handler configuration options for advanced use cases:

New API Options

authContext option in createMcpHandler - Allows explicit auth context injection for custom authentication flows
transport option in createMcpHandler - Enables transport instance reuse across multiple handler calls
storage option in WorkerTransport - Enables persistent session state across Durable Object hibernation
TransportState interface - Public interface for transport state structure

Documentation Added

New page: mcp-handler-api.mdx - Comprehensive API reference for createMcpHandler and WorkerTransport
Updated: transport.mdx - Added "Advanced Transport Configuration" section
Updated: mcp-agent-api.mdx - Referenced new handler API for advanced hibernation use cases

The documentation follows the Diátaxis framework with clear separation between reference documentation (new API page) and how-to guides (existing transport page).

🤖 This comment was automatically generated by the documentation sync workflow

- Add persistent transport state documentation to transport.mdx - Add new guide for MCP elicitation support - Update chatgpt-app.mdx with clarifying comment Synced from: cloudflare/agents#620

threepointone · 2025-11-12T13:05:21Z

📚 Documentation Sync

A documentation PR has been created/updated in cloudflare-docs to sync these changes:

PR: cloudflare/cloudflare-docs#26453

Documentation changes:

✅ New guide: MCP Elicitation - Complete tutorial showing how to build MCP servers with user input elicitation
✅ Updated Transport documentation with new persistent state management API
✅ Updated ChatGPT app guide with clarifications

The docs PR is ready for review and covers:

New WorkerTransport storage API for persistent session state
New createMcpHandler options (authContext, transport)
Simplified elicitation example walkthrough

threepointone · 2025-11-13T11:29:32Z

Documentation Sync Complete

Documentation for this PR has been synced to cloudflare-docs.

What was documented

New API Features:

WorkerTransport storage persistence: Added comprehensive documentation for the new storage option that allows persisting transport state (session ID, initialization status, protocol version) across hibernation cycles
createMcpHandler configuration options: Documented the new authContext, transport, corsOptions, and route configuration options

Cross-references:

Linked McpAgent hibernation documentation to persistent transport state guide
Added reference to the new MCP Elicitation guide in the remote MCP server setup

Examples:

Referenced the simplified mcp-elicitation example that demonstrates the elicitation API

Documentation PR

cloudflare/cloudflare-docs#26453

🤖 Generated with Claude Code

threepointone · 2025-11-13T11:30:03Z

Documentation Sync

A documentation sync PR has been created in cloudflare-docs to reflect the changes in this PR.

Documentation PR: cloudflare/cloudflare-docs#26453

Changes synced:

Added documentation for WorkerTransport persistent storage API
Documented new createMcpHandler configuration options (authContext, transport)
Added TransportState interface reference
Explained advanced handler configuration patterns

Once this PR is merged, please review and merge the documentation PR.

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

threepointone · 2025-11-13T12:56:35Z

📚 Documentation Sync Complete

The documentation for this PR has been synced to cloudflare/cloudflare-docs.

Documentation PR

🔗 cloudflare/cloudflare-docs#26453

What was documented

New Documentation

MCP Elicitation Guide - Comprehensive guide explaining how to use elicitation in MCP servers
- Interactive tool workflows with user input requests
- Form-based data collection
- Boolean confirmations and multi-field forms
- Response handling patterns

API Reference Updates

WorkerTransport Storage API - Session state persistence
MCPStorageApi Interface - Storage contract for persisting transport state
TransportState Type - Structure for session state (sessionId, initialized, protocolVersion)
createMcpHandler Options - Updated with new authContext and transport parameters

Updated Content

Transport Documentation - Added storage persistence section with examples
Example Update - Documented simplified elicitation example (removed complex UI demo)

Files Changed in Docs Repo

✨ NEW: src/content/docs/agents/model-context-protocol/elicitation.mdx
📝 UPDATED: src/content/docs/agents/model-context-protocol/transport.mdx

Review the Documentation

View the full documentation changes in the PR above. The docs PR includes:

Complete code examples using the new APIs
Best practices for using elicitation
Integration patterns with Agent storage
Client compatibility information

This comment was automatically generated by the documentation sync workflow.

- Add comprehensive guide for MCP elicitation (user input) - Document new createMcpHandler options (storage, authContext, transport) - Add examples for state persistence and custom transport configuration - Cover elicitation schema types and response handling Related to cloudflare/agents#620

threepointone · 2025-11-13T13:03:13Z

📚 Documentation synced to cloudflare-docs

Documentation has been synced to: cloudflare/cloudflare-docs#26453

Documentation Added/Updated:

New Guide: MCP Elicitation - Comprehensive guide for user input during tool execution
Updated: Transport Configuration - Added advanced configuration options

The documentation covers:

New createMcpHandler options (storage, authContext, transport)
State persistence for hibernation support
Complete elicitation examples with all schema types
Best practices and migration guidance

- Add comprehensive elicitation guide with examples - Document createMcpHandler configuration options - Add storage persistence documentation for transport state - Include code examples for all new features Related to cloudflare/agents#620

threepointone · 2025-11-13T13:31:23Z

📚 Documentation Sync

Documentation has been updated to reflect the changes in this PR.

Documentation PR: cloudflare/cloudflare-docs#26453

Changes included:

✅ New elicitation guide with comprehensive examples
✅ Updated transport documentation with createMcpHandler configuration options
✅ Added storage persistence documentation for transport state
✅ Code examples for all new features

The documentation covers:

How to use elicitation for interactive user input
All supported input types (boolean, text, email, number, select, multi-field forms)
Best practices for elicitation
New storage option for state persistence across hibernation
New authContext and transport configuration options
Complete working examples

feat: elicit-me example

8bd94d3

threepointone and others added 4 commits November 3, 2025 13:43

peepeepoopoo

36cf350

add val

8cdf98f

rename

a925873

storage api for persistance

bebf7f8

mattzcarey marked this pull request as ready for review November 12, 2025 11:52

Merge branch 'main' into elicit-me

8728ee1

threepointone mentioned this pull request Nov 12, 2025

feat: elicit-me example cloudflare/cloudflare-docs#26453

Open

threepointone approved these changes Nov 12, 2025

View reviewed changes

packages/agents/src/mcp/worker-transport.ts Outdated Show resolved Hide resolved

mattzcarey commented Nov 12, 2025

View reviewed changes

examples/mcp-elicitation/src/index.ts Outdated Show resolved Hide resolved

mattzcarey commented Nov 12, 2025

View reviewed changes

examples/mcp-elicitation/src/index.ts Outdated Show resolved Hide resolved

mattzcarey commented Nov 12, 2025

View reviewed changes

examples/mcp-worker-authenticated/src/index.ts Show resolved Hide resolved

mattzcarey marked this pull request as draft November 12, 2025 12:40

mattzcarey added 2 commits November 12, 2025 12:45

reset auth example

7df8eb6

fix: lock

8604b36

storage interface

8753a63

mattzcarey added 2 commits November 13, 2025 11:23

remove any

01d7a8f

fix: types

99adf27

fix: transport types

018202e

add some tests for this

5731ffe

mattzcarey marked this pull request as ready for review November 13, 2025 13:04

mattzcarey mentioned this pull request Nov 13, 2025

Add an optional durableObjectName field to serve/serveSSE methods for persistent routing across MCP sessions #536

Open

mattzcarey merged commit b21e8ae into main Nov 13, 2025
6 checks passed

mattzcarey deleted the elicit-me branch November 13, 2025 13:26

mattzcarey mentioned this pull request Nov 13, 2025

Version Packages #638

Merged

feat: elicit-me example #620

feat: elicit-me example #620

Uh oh!

Conversation

mattzcarey commented Oct 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot bot commented Oct 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

pkg-pr-new bot commented Oct 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

claude bot commented Nov 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Claude Code Review

Issues Found

1. Type mismatch in elicitation example (examples/mcp-elicitation/src/index.ts:49)

2. Incorrect schema property (examples/mcp-elicitation/src/index.ts:73)

3. Race condition potential (packages/agents/src/mcp/worker-transport.ts:522-523)

4. Potential memory leak (packages/agents/src/mcp/worker-transport.ts:332)

5. Error loses context (examples/mcp-elicitation/src/index.ts:108)

Testing Coverage

Architecture

Recommendation

Uh oh!

threepointone commented Nov 12, 2025

Uh oh!

threepointone left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

threepointone commented Nov 12, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

threepointone commented Nov 12, 2025

📚 Documentation Sync Complete

Documentation PR

Changes Documented

New API Options

Documentation Added

Uh oh!

threepointone commented Nov 12, 2025

Documentation changes:

Uh oh!

threepointone commented Nov 13, 2025

Documentation Sync Complete

What was documented

Documentation PR

Uh oh!

threepointone commented Nov 13, 2025

Documentation Sync

Changes synced:

Uh oh!

threepointone commented Nov 13, 2025

📚 Documentation Sync Complete

Documentation PR

What was documented

New Documentation

API Reference Updates

Updated Content

Files Changed in Docs Repo

Review the Documentation

Uh oh!

threepointone commented Nov 13, 2025

📚 Documentation synced to cloudflare-docs

Documentation Added/Updated:

Uh oh!

Uh oh!

threepointone commented Nov 13, 2025

📚 Documentation Sync

Changes included:

Uh oh!

Reviewers

Assignees

Labels

Projects

mattzcarey commented Oct 31, 2025 •

edited

Loading

changeset-bot bot commented Oct 31, 2025 •

edited

Loading

pkg-pr-new bot commented Oct 31, 2025 •

edited

Loading

claude bot commented Nov 12, 2025 •

edited

Loading