Agents can handle MCP elicitation requests

Agents connected to Model Context Protocol (MCP) servers with addMcpServer can now handle elicitation requests.

Elicitation lets an MCP server request user input while it handles a tool call. Form mode collects structured, non-sensitive data. URL mode asks for consent before opening an out-of-band flow, such as third-party authorization or payment.

sequenceDiagram
    participant User
    participant Agent as Agent (MCP client)
    participant Server as MCP server
    participant Browser

    Server->>Agent: elicitation/create
    Agent->>User: Show server, reason, and input or URL
    User->>Agent: Submit, open, decline, or cancel
    Agent->>Browser: Open URL after consent (URL mode)
    Agent->>Server: accept, decline, or cancel
    Server-->>Agent: Optional URL completion notification

Register a handler for each mode your Agent supports in onStart():

• JavaScript

  <div><div><span>import </span><span>{</span><span><span> </span><span>Agent</span><span> </span></span><span>}</span><span> from </span><span>"agents"</span><span>;</span></div></div><div><div>
  </div></div><div><div><span>export</span><span> </span><span>class</span><span> </span><span>MyAgent</span><span> </span><span>extends</span><span> </span><span>Agent</span><span> </span><span>{</span></div></div><div><div><span>  </span><span>onStart</span><span>()</span><span> </span><span>{</span></div></div><div><div><span>    </span><span>this</span><span>.</span><span>mcp</span><span>.</span><span>configureElicitationHandlers</span><span>(</span><span>{</span></div></div><div><div><span>      </span><span>form</span><span>:</span><span> </span><span>(</span><span>request</span><span>,</span><span> </span><span>serverId</span><span>)</span><span> </span><span>=></span><span> </span><span>this</span><span>.</span><span>forwardToUser</span><span>(</span><span>request</span><span>,</span><span> </span><span>serverId</span><span>)</span><span>,</span></div></div><div><div><span>      </span><span>url</span><span>:</span><span> </span><span>(</span><span>request</span><span>,</span><span> </span><span>serverId</span><span>)</span><span> </span><span>=></span><span> </span><span>this</span><span>.</span><span>forwardToUser</span><span>(</span><span>request</span><span>,</span><span> </span><span>serverId</span><span>)</span><span>,</span></div></div><div><div><span>    </span><span>}</span><span>)</span><span>;</span></div></div><div><div><span>  </span><span>}</span></div></div><div><div>
  </div></div><div><div><span>  </span><span>forwardToUser</span><span>(</span><span>request</span><span>,</span><span> </span><span>serverId</span><span>)</span><span> </span><span>{</span></div></div><div><div><span>    </span><span>// Show the request in your UI and resolve after the user responds.</span></div></div><div><div><span>    </span><span>throw</span><span> </span><span>new</span><span> </span><span>Error</span><span>(</span></div></div><div><div><span>      </span><span>`Implement elicitation for </span><span>${</span><span>serverId</span><span>}</span><span>: </span><span>${</span><span>request</span><span>.</span><span>params</span><span>.</span><span>message</span><span>}</span><span>`</span><span>,</span></div></div><div><div><span><span>    </span></span><span>)</span><span>;</span></div></div><div><div><span>  </span><span>}</span></div></div><div><div><span>}</span></div></div>

• TypeScript

  <div><div><span>import </span><span>{</span><span><span> </span><span>Agent</span><span> </span></span><span>}</span><span> from </span><span>"agents"</span><span>;</span></div></div><div><div><span>import type </span><span>{</span><span><span> </span><span>ElicitRequest</span></span><span>,</span><span><span> </span><span>ElicitResult</span><span> </span></span><span>}</span><span> from </span><span>"agents/mcp"</span><span>;</span></div></div><div><div>
  </div></div><div><div><span>export</span><span> </span><span>class</span><span> </span><span>MyAgent</span><span> </span><span>extends</span><span> </span><span>Agent</span><span><</span><span>Env</span><span>></span><span> </span><span>{</span></div></div><div><div><span>  </span><span>onStart</span><span>()</span><span> </span><span>{</span></div></div><div><div><span>    </span><span>this</span><span>.</span><span>mcp</span><span>.</span><span>configureElicitationHandlers</span><span>(</span><span>{</span></div></div><div><div><span>      </span><span>form</span><span>:</span><span> </span><span>(</span><span>request</span><span>,</span><span> </span><span>serverId</span><span>)</span><span> </span><span>=></span><span> </span><span>this</span><span>.</span><span>forwardToUser</span><span>(</span><span>request</span><span>,</span><span> </span><span>serverId</span><span>)</span><span>,</span></div></div><div><div><span>      </span><span>url</span><span>:</span><span> </span><span>(</span><span>request</span><span>,</span><span> </span><span>serverId</span><span>)</span><span> </span><span>=></span><span> </span><span>this</span><span>.</span><span>forwardToUser</span><span>(</span><span>request</span><span>,</span><span> </span><span>serverId</span><span>)</span><span>,</span></div></div><div><div><span>    </span><span>}</span><span>)</span><span>;</span></div></div><div><div><span>  </span><span>}</span></div></div><div><div>
  </div></div><div><div><span>  </span><span>private</span><span> </span><span>forwardToUser</span><span>(</span></div></div><div><div><span>    </span><span>request</span><span>:</span><span> </span><span>ElicitRequest</span><span>,</span></div></div><div><div><span>    </span><span>serverId</span><span>:</span><span> </span><span>string</span><span>,</span></div></div><div><div><span>  </span><span>)</span><span>:</span><span> </span><span>Promise</span><span><</span><span>ElicitResult</span><span>></span><span> </span><span>{</span></div></div><div><div><span>    </span><span>// Show the request in your UI and resolve after the user responds.</span></div></div><div><div><span>    </span><span>throw</span><span> </span><span>new</span><span> </span><span>Error</span><span>(</span></div></div><div><div><span>      </span><span>`Implement elicitation for </span><span>${</span><span>serverId</span><span>}</span><span>: </span><span>${</span><span>request</span><span>.</span><span>params</span><span>.</span><span>message</span><span>}</span><span>`</span><span>,</span></div></div><div><div><span><span>    </span></span><span>)</span><span>;</span></div></div><div><div><span>  </span><span>}</span></div></div><div><div><span>}</span></div></div>

Connections advertise only the modes with configured handlers. An Agent without handlers advertises no elicitation capability, which lets the server use its fallback. The SDK stores the advertised modes with each MCP server registration so they survive Durable Object hibernation. Callback functions remain in memory and reattach when onStart() runs.

For implementation details and a browser forwarding pattern, refer to MCP client elicitation. The mcp-client and mcp-elicitation examples implement both sides.

Upgrade

To update to this release:

<span>npm</span><span> i agents@latest</span>

<span>yarn</span><span> add agents@latest</span>

<span>pnpm</span><span> add agents@latest</span>

<span>bun</span><span> add agents@latest</span>