Skip to content

feat: elicit-me example #26453

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 2 commits into
base: production
Choose a base branch
from
Open

feat: elicit-me example #26453

wants to merge 2 commits into from
+1,085 −0

Conversation

@threepointone
Copy link
Contributor

@threepointone threepointone commented Nov 12, 2025 •
edited by mattzcarey
Loading

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.

Documentation sync from cloudflare/agents PR #620
cloudflare/agents#620

@threepointone threepointone mentioned this pull request Nov 12, 2025
Merged
@github-actions github-actions bot added size/m product:agents Build and deploy AI-powered Agents on Cloudflare that can act autonomously. labels Nov 12, 2025
@github-actions
Copy link
Contributor

github-actions bot commented Nov 12, 2025 •
edited
Loading

This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:

Pattern Owners
/src/content/docs/agents/ @irvinebroque, @rita3ko, @elithrar, @thomasgauvin, @threepointone, @cloudflare/pcx-technical-writing

@github-actions
Copy link
Contributor

github-actions bot commented Nov 12, 2025 •
edited
Loading

Preview URL: https://6914081f.preview.developers.cloudflare.com
Preview Branch URL: https://sync-docs-pr-620.preview.developers.cloudflare.com

Files with changes (up to 15)

Original Link Updated Link
https://developers.cloudflare.com/agents/guides/mcp-elicitation/ https://sync-docs-pr-620.preview.developers.cloudflare.com/agents/guides/mcp-elicitation/
https://developers.cloudflare.com/agents/model-context-protocol/transport/ https://sync-docs-pr-620.preview.developers.cloudflare.com/agents/model-context-protocol/transport/
https://developers.cloudflare.com/agents/guides/remote-mcp-server/ https://sync-docs-pr-620.preview.developers.cloudflare.com/agents/guides/remote-mcp-server/
https://developers.cloudflare.com/agents/model-context-protocol/mcp-agent-api/ https://sync-docs-pr-620.preview.developers.cloudflare.com/agents/model-context-protocol/mcp-agent-api/
https://developers.cloudflare.com/agents/guides/chatgpt-app/ https://sync-docs-pr-620.preview.developers.cloudflare.com/agents/guides/chatgpt-app/

@threepointone
Copy link
Contributor Author

threepointone commented Nov 12, 2025

Updated with comprehensive API reference documentation:

Changes Added

New Documentation Page

  • mcp-handler-api.mdx: Complete API reference for createMcpHandler and WorkerTransport
    • Documents new authContext option for custom authentication flows
    • Documents new transport option for transport instance reuse
    • Documents new storage option for persistent session state across hibernation
    • Documents TransportState interface
    • Includes complete working example showing persistent MCP server with custom auth

Updated Existing Pages

  • transport.mdx: Added "Advanced Transport Configuration" section linking to the new API reference
  • mcp-agent-api.mdx: Updated hibernation section to reference the new handler API for advanced use cases

Documentation Approach

Following the Diátaxis framework:

  • Created separate Reference documentation for low-level APIs (mcp-handler-api.mdx)
  • Kept How-to guide content in transport.mdx for common transport configuration
  • Added cross-references between pages for easy navigation

This provides clearer separation between simple usage (via McpAgent.serve()) and advanced use cases (via createMcpHandler with custom options).

kodster28
kodster28 reviewed Nov 12, 2025
View reviewed changes
src/content/docs/agents/guides/mcp-elicitation.mdx Outdated

Update your `wrangler.jsonc` to configure Durable Objects:

```jsonc
Copy link
Collaborator

@kodster28 kodster28 Nov 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@whoiskatrin / @threepointone, can y'all update y'alls Claude script to more explicitly use WranglerConfig as a component?

Copy link
Contributor

@whoiskatrin whoiskatrin Nov 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@kodster28 yup, will do

src/content/docs/agents/guides/mcp-elicitation.mdx

The `elicitInput` method requests additional information from the user during tool execution:

```ts
Copy link
Collaborator

@kodster28 kodster28 Nov 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why is this one not also TypeScriptExample?

Copy link
Contributor

@whoiskatrin whoiskatrin Nov 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mattzcarey let's fix this. @kodster28 sorry about this, it's our agent doing this automatically, I will fix the prompt

@kodster28
Copy link
Collaborator

kodster28 commented Nov 12, 2025

We also have some rules at https://github.com/cloudflare/cloudflare-docs/blob/production/.windsurf/rules/general-rules.md that y'all might be able to reuse in y'alls prompt, @whoiskatrin / @threepointone

@threepointone
Copy link
Contributor Author

threepointone commented Nov 13, 2025

Updated documentation to include:

Additional API Documentation

Advanced Handler Configuration

Documented the new configuration options for createMcpHandler:

  • authContext: Explicitly provide authentication information
  • transport: Supply a custom WorkerTransport instance
  • corsOptions: Configure CORS settings
  • route: Specify URL path handling

Cross-references

  • Added link from McpAgent hibernation section to persistent transport state documentation
  • Added reference to MCP Elicitation guide from the remote MCP server guide

These additions complement the initial sync and provide complete coverage of the API changes in cloudflare/agents#620.

🤖 Generated with Claude Code

@threepointone
Copy link
Contributor Author

threepointone commented Nov 13, 2025

Documentation Sync Update

✅ Updated documentation synced from cloudflare/agents#620

Changes in this update:

  • Added comprehensive MCP elicitation guide () with:

    • Complete explanation of what elicitation is and when to use it
    • Practical code examples showing elicitation in action
    • Different schema types (boolean, text, dropdown, numeric)
    • Response handling patterns (accept/decline/cancel)
    • Session persistence integration

  • Updated transport documentation with storage API details (already present in previous commits)

New Documentation

📄 MCP Elicitation Guide

  • Explains the MCP elicitation feature for interactive tool workflows
  • Shows how to request user input during tool execution
  • Demonstrates session persistence with the storage API
  • Includes complete working examples with the Agents SDK

Key APIs Documented

  • MCPStorageApi interface for session persistence
  • TransportState type for transport state structure
  • WorkerTransport storage option for Durable Object integration
  • elicitInput() method for requesting user input

Related Resources

docs: add MCP elicitation guide and transport configuration
c7de600 
- 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
Copy link
Contributor Author

threepointone commented Nov 13, 2025

📚 Documentation Updated

This PR has been updated with documentation for the changes in cloudflare/agents#620

New Documentation

  • MCP Elicitation Guide (/agents/guides/mcp-elicitation.mdx)
    • Comprehensive guide for requesting user input during tool execution
    • Covers all schema types, response handling, and best practices
    • Includes examples for state persistence with hibernation

Updated Documentation

  • Transport Configuration (/agents/model-context-protocol/transport.mdx)
    • Added "Advanced Transport Configuration" section
    • Documents new createMcpHandler options (storage, authContext, transport)
    • Complete examples for state persistence and custom transports

Summary

The example was simplified from a complex React client-server demo to a focused server-side elicitation example. The documentation now covers the new powerful features for state persistence and custom transport configuration that enable elicitation to work reliably with Durable Object hibernation.

🔗 Original PR: cloudflare/agents#620

@github-actions
Copy link
Contributor

github-actions bot commented Nov 13, 2025 •
edited
Loading

CI run failed: build logs

docs: add MCP elicitation and transport configuration documentation
96c9779 
- 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
@mattzcarey mattzcarey self-assigned this Nov 13, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@whoiskatrin whoiskatrin whoiskatrin left review comments

@kodster28 kodster28 kodster28 left review comments

@irvinebroque irvinebroque Awaiting requested review from irvinebroque irvinebroque is a code owner

@rita3ko rita3ko Awaiting requested review from rita3ko rita3ko is a code owner

@elithrar elithrar Awaiting requested review from elithrar elithrar is a code owner

@thomasgauvin thomasgauvin Awaiting requested review from thomasgauvin thomasgauvin is a code owner

@patriciasantaana patriciasantaana Awaiting requested review from patriciasantaana

@pedrosousa pedrosousa Awaiting requested review from pedrosousa

@angelampcosta angelampcosta Awaiting requested review from angelampcosta

@marciocloudflare marciocloudflare Awaiting requested review from marciocloudflare

@dcpena dcpena Awaiting requested review from dcpena

@GregBrimble GregBrimble Awaiting requested review from GregBrimble

@mikenomitch mikenomitch Awaiting requested review from mikenomitch

@WalshyDev WalshyDev Awaiting requested review from WalshyDev

@korinne korinne Awaiting requested review from korinne

@Oxyjun Oxyjun Awaiting requested review from Oxyjun

@jonesphillip jonesphillip Awaiting requested review from jonesphillip

@aninibread aninibread Awaiting requested review from aninibread

@harshil1712 harshil1712 Awaiting requested review from harshil1712

@sejoker sejoker Awaiting requested review from sejoker

@maxvp maxvp Awaiting requested review from maxvp

@nikitacano nikitacano Awaiting requested review from nikitacano

@ranbel ranbel Awaiting requested review from ranbel

At least 1 approving review is required to merge this pull request.

Assignees

@elithrar elithrar

@irvinebroque irvinebroque

@rita3ko rita3ko

@thomasgauvin thomasgauvin

@mattzcarey mattzcarey

Labels

product:agents Build and deploy AI-powered Agents on Cloudflare that can act autonomously. size/m

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

8 participants

@threepointone @kodster28 @whoiskatrin @elithrar @irvinebroque @rita3ko @thomasgauvin @mattzcarey