What it does
The `elicitation/create` method is sent from the server to the client during an active MCP session whenever the server needs to collect input from the human user before it can proceed. Before issuing the request the server must confirm that the client declared an `elicitation` capability (either `form`, `url`, or both) in its `ClientCapabilities` during `initialize`. Sending the request to an incapable client is a protocol error and will result in a JSON-RPC `-32601` Method not found response. The server constructs an `ElicitRequest` with a `mode` of either `form` or `url`, a human-readable `message` explaining what is needed, and mode-specific fields: `requestedSchema` for form mode (a flat JSON Schema whose properties must be primitive types — string, number, boolean, or enum; nesting is not supported) or `url` plus a stable `elicitationId` for url mode.\n\nOnce the client receives the request it presents the appropriate UI — rendering a form widget from the schema, or opening the target URL in a browser tab — and blocks until the user acts. The client then returns an `ElicitResult` containing an `action` field of `accept`, `decline`, or `cancel`, along with an optional `content` object that is only populated when `action` is `accept` in form mode. The server must branch on all three actions: `accept` means the form data is valid and matches the schema; `decline` is an explicit user refusal (offer an alternative path); `cancel` means the user dismissed the dialog without deciding (consider prompting again or aborting gracefully). For url mode the client sends no inline result; instead, it emits a `notifications/elicitation/complete` notification carrying the `elicitationId` and the final action when the out-of-band flow finishes.\n\nTiming matters: `elicitation/create` is a blocking, correlated JSON-RPC call with an `id`. The server should not issue a second elicitation while one is already pending on the same session, as clients are not required to queue or multiplex concurrent elicitation dialogs. If a tool call is time-bounded (for example, inside a task with a TTL), design elicitation prompts to be brief and confirmatory so users can respond before the task expires.
When to use
Mid-flow when you need user input or confirmation.
When NOT to use
For PII or secrets in form mode — use url mode.
Notes
Capability gate is mandatory
The server must inspect `clientCapabilities.elicitation` before calling `elicitation/create`. If the client did not advertise the capability, the method does not exist on that connection and the call will return `-32601`. Always implement a fallback path — either abort the tool or pass a conservative default — for clients that omit this capability.
Form mode schema is primitive-only
The `requestedSchema` object must be a flat JSON Schema with only primitive property types: `string`, `number`, `integer`, `boolean`, or `string` with an `enum`. Nested objects, arrays, and `$ref` are not supported. Clients validate the schema at render time; sending a complex schema will cause the client to reject the request with `-32602` Invalid params.
URL mode requires a stable elicitationId
For url mode you must supply an `elicitationId` that the client echoes back in the `notifications/elicitation/complete` notification. Generate a per-request UUID and store it server-side so you can correlate the async notification to the original request. If the notification never arrives (user closed the tab, network drop), the server must handle the silence — there is no timeout callback in the protocol; implement your own deadline.
Three-action result — treat each distinctly
Never conflate `decline` with `cancel`. `decline` is a deliberate user refusal; the server should surface an alternative flow or return a meaningful error to the LLM. `cancel` is an ambiguous dismissal — the user may intend to respond later; retry once after a short delay or ask the LLM to rephrase the prompt. `accept` is the only action that carries `content`; always guard with `if action === 'accept'` before reading form data.
Avoid concurrent elicitations
The MCP specification does not require clients to queue multiple simultaneous `elicitation/create` requests. Issue at most one elicitation at a time per session. If your tool logic requires sequential confirmations, wait for the first `ElicitResult` before sending the next request. Sending a second elicitation while the first is still pending may result in the client returning `-32600` or silently dropping the second request depending on the implementation.
Request parameters
| Name | Type | Purpose |
|---|---|---|
| mode | 'form' | 'url' | Form or URL elicitation. |
| message | string | User-facing message. |
| requestedSchema | JSON Schema? | Form mode schema. |
| url | string? | URL mode target. |
| elicitationId | string? | Required for url mode (used in completion notification). |
Response fields
| Name | Type | Purpose |
|---|---|---|
| action | 'accept' | 'decline' | 'cancel' | User's choice. |
| content | object? | Submitted data (form mode + accept). |
Examples
Form elicit
{ "method": "elicitation/create", "params": { "mode": "form", "message": "Confirm?", "requestedSchema": {...} } }Common mistakes
❌ Asking for secrets in form mode
✅ Use url mode for sensitive data.