MCP Elicitation and Multi Round-Trip Requests
On this page
Learning Objective
Let a server ask the user for input partway through an operation, using form and URL elicitation, and implement it with the multi round-trip request pattern introduced in 2026-07-28. Know why sampling and roots were deprecated and what replaces them.
Concept Explanation
Some operations cannot finish with only the arguments the model supplied. A deploy needs a human to confirm. A booking needs the user to choose between two available times. A connection to a third-party service needs the user to sign in. Elicitation is MCP's mechanism for a server to request that information from the user, through the host, without breaking out of the protocol.
There are two modes. Form elicitation sends a message and a small JSON Schema of primitive fields, such as a boolean confirm or an enum of time slots; the host renders a form, and the user can accept with data, decline or cancel. URL elicitation sends the user to a web page for interactions that must not pass through the client or the model at all, such as entering a password, completing an OAuth consent or paying. The data never enters the conversation; the server learns the outcome through its own backend.
Earlier revisions implemented elicitation as a request from the server to the client in the middle of a tool call, which required a persistent connection. The stateless 2026-07-28 revision replaced that with Multi Round-Trip Requests. The server ends the first call by returning a result with resultType input_required, a map of inputRequests keyed by names it chooses, and an opaque requestState. The client resolves each request, for example by showing the form, and then retries the original call with inputResponses and the same requestState. The server sees the answers and finishes. Because everything needed travels in the request, any server instance can handle the retry.
requestState is how the server carries context between rounds without storing it. Since the client returns it, a server must not trust it blindly: the SDKs can sign or encrypt it so tampering is detected. Servers should also treat elicitation as a request for consent, not as authentication; a confirmation tells you the user agreed, not who the user is.
The same revision deprecated three client features that relied on server-initiated requests. Sampling, where a server asked the client's model to generate text, is replaced by servers calling a model provider directly. Roots, where a server asked which directories it may access, is replaced by passing paths as tool parameters or configuration. Protocol logging is replaced by standard error output for stdio and OpenTelemetry for HTTP. Deprecated features keep working for at least twelve months, but new servers should not adopt them.
| Concept | 2026-07-28 behavior | Use for |
|---|---|---|
| Form elicitation | inputRequests entry with message and requestedSchema | Confirmations, choices, small inputs |
| URL elicitation | Sends the user to a URL; data stays out of the conversation | Credentials, OAuth, payments |
| input_required result | resultType plus inputRequests plus requestState | First round of a multi round-trip request |
| Retry | Same request with inputResponses and requestState | Completing the operation |
| Sampling, roots, logging | Deprecated | Call a model directly, pass paths, use stderr or OpenTelemetry |
Worked Example: Confirming a Production Promotion
The TypeScript tool returns inputRequired until the confirmation arrives. The Python version declares the confirmation as a resolver dependency, and the SDK drives the round trips for you.
import { inputRequired, acceptedContent } from '@modelcontextprotocol/server';
import * as z from 'zod/v4';
server.registerTool('promote', {
description: 'Promote the version on staging to production. Asks the user to confirm.',
inputSchema: z.object({ service: z.string() }),
annotations: { idempotentHint: true, openWorldHint: true },
}, async ({ service }, ctx) => {
const staged = DEPLOYS.find((d) => d.service === service && d.env === 'staging');
if (!staged) throw new Error(`Nothing on staging for ${service}. Deploy to staging first.`);
const Confirm = z.object({ confirm: z.boolean() });
const answer = acceptedContent(ctx.mcpReq.inputResponses, 'confirm', Confirm); // undefined on round 1
if (answer?.confirm !== true) {
return inputRequired({ inputRequests: { confirm: inputRequired.elicit({
message: `Promote ${service} v${staged.version} to production?`, requestedSchema: Confirm }) } });
}
return { content: [{ type: 'text', text: `Started promotion of ${service} v${staged.version}.` }] };
});from typing import Annotated
from pydantic import BaseModel, Field
from mcp.server.mcpserver import MCPServer, Elicit, ElicitationResult, AcceptedElicitation, Resolve
mcp = MCPServer("notes")
class Confirm(BaseModel):
confirm: bool = Field(description="Delete the note?")
def ask_confirm(note_id: str) -> Elicit[Confirm]: # a resolver; receives tool args by name
return Elicit(f"Delete note {note_id}?", Confirm)
@mcp.tool()
def delete_note(note_id: str, answer: Annotated[ElicitationResult[Confirm], Resolve(ask_confirm)]) -> str:
"""Delete a note after the user confirms."""
if isinstance(answer, AcceptedElicitation) and answer.data.confirm:
return f"Deleted {note_id}"
return "Cancelled by the user."On the wire, the first tools/call for delete_note returns resultType input_required with an elicitation/create request and an encrypted requestState. The client shows the question and retries with inputResponses, and the second call returns the completed result. The answer parameter never appears in the tool's input schema, so the model cannot fake a confirmation.
Real-World Examples
- Elicitation entered the MCP specification in the 2025-06-18 revision, URL mode followed in 2025-11-25 for credentials and payments that must not pass through the client, and 2026-07-28 moved both onto the multi round-trip pattern so they work on stateless servers.
- Claude Code exposes Elicitation and ElicitationResult hook events, so organizations can log or automatically answer server elicitations in scripted runs.
Review Questions & Answers
When the interaction involves sensitive data or flows that must not pass through the client or the model, such as entering credentials, completing OAuth consent or making a payment. The user completes it on a web page and the data never enters the conversation.
In the first round the server returns a result with resultType input_required, the inputRequests it needs answered and an opaque requestState. In the second round the client retries the original request with inputResponses and the same requestState, and the server completes the operation.
The client holds and returns it, so it could be modified. Servers should sign or encrypt it, as the SDKs can, so tampering is detected.
The answer parameter is filled by a resolver and does not appear in the tool's input schema, so it cannot be supplied as a tool argument. Only the user's response through elicitation can provide it.