Blog · · 9 min read
Build a durable MCP elicitation state machine

MCP elicitation lets a server request missing user input while a tool workflow is in progress. The request must survive longer than an open dialog. If the user closes the client, retries the tool, finishes an OAuth flow on another device, or returns after the request expires, a naive implementation can ask twice, attach an answer to the wrong run, leak credentials through the client, or replay a real side effect.
Treat elicitation as a durable, user-bound transaction. Store what the operation needs, why it needs it, who may answer, when the request expires, and what evidence allows the original operation to resume. Then make resumption idempotent and verify the product result before reporting success.
Why elicitation needs product state
The MCP elicitation specification supports two modes:
- Form mode collects shallow structured data through the MCP client.
- URL mode sends the user to an external surface for sensitive or third-party interactions.
The protocol also distinguishes accept, decline, and cancel. Those response actions describe what happened at the elicitation boundary. They do not automatically prove that the original product operation completed.
In URL mode, an accept response means the user agreed to visit the external URL. The specification explicitly says it does not mean the external interaction finished. The server must determine completion from securely stored state, a callback, or another authoritative check when the client retries the original request.
A product therefore has at least three pieces of state to coordinate:
- The original operation, such as importing private repositories.
- The input request, such as choosing repositories or authorizing GitHub access.
- The external result, such as an OAuth grant stored for the current user.
If those records exist only in an open request handler, a timeout or process restart breaks the workflow. If they are stored without an identity and operation binding, one user or retry can satisfy another request.
Choose form mode or URL mode before asking
Choose the mode from the data boundary, not UI convenience.
Use form mode for non-sensitive values that may safely pass through the MCP client, such as a date range, environment name, report format, or a choice from a known set. The specification limits form schemas to flat objects with primitive values and supported enum patterns. Clients can generate controls and validate the submitted object against that schema.
Use URL mode when the interaction contains credentials, payment details, access tokens, or another secret that must not pass through the MCP client. The official specification requires URL mode for that class of information. The WorkOS URL-mode walkthrough shows why OAuth, credential entry, and payment setup need a trusted external surface whose outcome is tracked by the server.
Classify each request with this rule:
if field grants access or authorizes a transaction:
mode = URL
elif schema is shallow and client exposure is acceptable:
mode = FORM
else:
redesign the interaction or use a product-owned URL flow
Do not work around form-schema restrictions by relabeling a password as ordinary text. MCP issue #774 documents the implementation pressure this creates when a client rejects password-oriented schemas. The safe response is to move credential collection to a trusted URL flow, not weaken the field description.
Define one input-required contract
Model elicitation as a state machine owned by your product service. The model can decide that information is missing, but it should not own request identity, expiry, resumption, or authorization.
A minimal record looks like this:
type InputRequest = {
id: string;
tenantId: string;
userId: string;
operationId: string;
operationVersion: number;
protocolVersion: string;
mode: "form" | "url";
schemaDigest?: string;
externalStateDigest?: string;
status:
| "pending"
| "accepted"
| "declined"
| "cancelled"
| "expired"
| "completed";
expiresAt: string;
createdAt: string;
resolvedAt?: string;
};
The record should contain references or digests, not submitted secrets. URL-mode credentials belong in the appropriate credential store, bound to the authenticated user. The elicitation record only needs enough evidence to determine whether the prerequisite is satisfied.
Use a constrained transition set:
pending -> accepted | declined | cancelled | expired
accepted -> completed | expired
completed -> terminal
For form mode, accepted and completed may occur in one transaction after schema validation and authorization. For URL mode, keep them separate. The user may accept navigation and never finish the external flow.
Every transition should compare the current status and operation version. A late callback must not revive an expired request or satisfy a newer operation. A second response should return the existing terminal result rather than execute the original action again.
Implement MCP elicitation in seven steps
1. Negotiate capability and protocol version
Read the client capability declaration before creating a request. The specification requires clients that support elicitation to declare at least one supported mode, and servers must not request an unsupported mode.
Protocol version also affects control flow. FastMCP's elicitation documentation describes a strict difference between handshake-era connections and the 2026-07-28 protocol. Older connections can pause a running tool and use a server-initiated callback. The modern protocol returns an input-required result, ends that round, and expects the client to make a later request with the response.
Hide that difference behind one application interface. Both adapters should create or load the same InputRequest record and call the same transition functions.
2. Check what is already known
Before creating an elicitation request, validate the parameters already supplied by the user and inspect current product state. Ask only for missing values.
A GitHub implementation retrospective reports a tool that initially elicited on every invocation, even when the user had already provided some required information. It also describes confusion caused by creating separate interactive and noninteractive tools with similar names. Keep one tool contract and branch inside it based on validated missing fields.
Generate a stable key from the user, operation, operation version, and requested-field set. If a matching pending request exists, return it. Do not create a second prompt because the transport retried.
3. Persist before presenting
Write the input request before returning a form or URL. The response should include an opaque request identifier, not raw database keys or unsigned state.
For a URL flow, create a short-lived, single-use state value. Store only a digest if practical. Bind it to the user, tenant, operation, callback destination, and expiry. On callback, authenticate the external result, compare the binding, consume the state atomically, and record completion.
The client should display which server is requesting input and, for URL mode, the target host. The specification requires clear decline and cancel controls, review of form responses, and user consent before navigating to an external domain.
4. Validate the response at the product boundary
Client-side schema validation improves the interface but is not an authorization boundary. Revalidate form content on the server. Then reload the user, tenant, operation, and current permissions.
Reject a response when:
- the request is expired or terminal;
- the authenticated user does not match the request;
- the operation version changed;
- the schema digest no longer matches;
- the requested choice is no longer available;
- the user's authority was revoked while the prompt was open.
Record decline and cancel as separate outcomes. Decline is an explicit choice. Cancel may mean dismissal, navigation failure, lost connection, or an interrupted client. Your product may offer a later retry for either outcome, but it should not pretend they mean the same thing.
5. Resume through an idempotent operation
A valid response makes the prerequisite available while leaving every earlier completed step untouched.
Load the original operation by operationId, acquire its normal concurrency guard, and compare its version. Resume from the input-required checkpoint. Pass a stable action identifier into every side-effecting API. If the action already has an authoritative receipt, return that receipt instead of dispatching again.
The resumed tool should return one of three truthful states:
- input is still required;
- the operation reached a verified terminal result;
- the operation failed or expired and requires a new user decision.
6. Reconcile URL completion
External callbacks can arrive before or after the client retries. Handle both orders.
If the callback arrives first, mark the prerequisite complete and let the next retry resume. If the retry arrives first, return input-required again with the existing request and a manual retry or cancel control. Do not create a new authorization URL unless the prior request expired or was explicitly invalidated. Issuing a fresh URL on every retry looks safer, but the callback will present the single-use state of the first URL, so replacing it makes an authorization the user already completed fail.
The specification recommends manual controls that let the user retry or cancel the original request because the MCP client may not receive the out-of-band outcome directly. A proposal in MCP issue #2006 also shows the demand for asynchronous interaction that does not block a client indefinitely.
7. Verify before reporting completion
After resumption, read the authoritative product state. For an OAuth connection, confirm that the grant belongs to the expected user and provider. For a purchase, check the order and payment records. For a configuration change, read the stored version.
Do not infer success from a returned HTTP status, an accepted elicitation, or a model summary. Store the verification evidence with the operation result, then produce the user-facing answer.
Example: connect and import private repositories
Suppose an agent receives: "Import issues from my private GitHub repositories."
The tool can parse the requested job, but it lacks two prerequisites: a GitHub grant and a repository selection.
- The product checks for a valid user-bound GitHub grant.
- If absent, it creates a URL-mode request tied to the import operation.
- The user accepts the link and completes OAuth on the product's callback domain.
- The callback stores the grant and marks that prerequisite complete.
- The client retries the original operation.
- The product lists repositories under the new grant and returns a form-mode request with safe repository identifiers.
- The user selects repositories and accepts.
- The product validates current access, stores the selection, and starts one idempotent import.
- The tool reports completion only after the import record contains verified counts and a terminal state.
If the client retries between steps 2 and 4, it receives the same pending URL request. If the user cancels at step 7, no import starts. If repository access changes before step 8, server-side validation rejects the stale selection. If a callback arrives after expiry, it cannot resume the old operation.
Handle retries, stale responses, and late callbacks
Test state disagreement explicitly. MCP issue #2920 reports an elicitation loop in which completed input did not stop repeated prompting. Your duplicate guard should prove that the same response cannot create another request or side effect.
Test these cases as well:
- a client that supports form mode but not URL mode;
- a protocol-version change after reconnect;
- two browser tabs answering the same request;
- a callback after cancellation or expiry;
- a response from the wrong tenant or user;
- revoked authority while a form is open;
- a schema or operation version change before submission;
- a process restart between persistence and presentation;
- a retry after the original side effect succeeded but before its response arrived;
- a URL request accepted without external completion.
For each case, assert both the visible result and the absence of forbidden writes. A failure test that checks only the returned message can miss a duplicate import, charge, or configuration update.
Verify the implementation
Before rollout, capture evidence for these checks:
- Every elicitation maps to one user, tenant, operation, version, and expiry.
- Sensitive values never appear in MCP form content, model context, logs, traces, or the input-request record.
- Unsupported client capabilities fail safely or use a documented product fallback.
- Accept, decline, cancel, expiry, and external completion remain distinct.
- Repeated responses and callbacks are idempotent.
- A stale request cannot satisfy a newer operation.
- A reconnect loads persisted state instead of creating another prompt.
- URL acceptance alone cannot mark the original operation complete.
- Every resumed side effect uses its normal authorization and idempotency controls.
- The final user message is backed by an authoritative postcondition.
Start with one workflow that guesses a missing value or asks users to restart after connecting an account. Add the InputRequest record, implement form and URL adapters, and run the duplicate-response and late-callback tests before enabling elicitation for more tools.