MCP form vs URL elicitation: how to request user data safely

Use form mode for a small set of non-secret structured answers that the user can review and submit in the MCP client: environment name, report format, date range, or parameter confirmation. URL mode is appropriate when the interaction involves a password, API key, access token, payment credentials, or third-party authorization. Those values are entered outside the client and are not returned in ElicitResult content.

Elicitation is not permission for the model to act and does not replace authorization. It only gives the server a controlled way to request user participation during an originating request. After the response, the server rechecks identity, scope, business policy, and current object state. If the authoritative system already knows the value, or the question is unnecessary for execution, do not elicit it: every extra prompt adds friction and phishing surface.

• Non-secret primitive fields → form mode.
• Credentials, payment, or external OAuth → URL mode.
• Approval for a consequential action → a separate policy/approval gate, not an arbitrary form field.
• Client did not advertise the required mode → controlled fallback or refusal.
• Authoritative value already exists → read it from the system of record.

The client advertises elicitation capability during initialization and the supported form and/or URL modes. An empty elicitation object is compatible with form-only behavior; the server must not interpret it as URL support. Store the session capability manifest together with the negotiated protocol and implementation versions, then check the required mode before elicitation/create. An application name or a button seen in one client does not prove compatibility in another deployment.

Server-to-client elicitation must be associated with an originating client request such as tools/call or resources/read. Do not build an independent channel for unsolicited prompts. The router determines the requirement before any side effect starts: form-supported, URL-supported, no-elicitation fallback, or blocked. If a workflow cannot obtain a credential safely without URL mode, the correct fallback is an out-of-band setup link or a clear refusal, not asking for the secret in a text field.

A form request contains a human-readable message and restricted JSON Schema: a flat object with primitive properties. The restriction is useful because it keeps elicitation as a short interaction rather than a hidden application-form platform. Names, descriptions, defaults, enum labels, and required fields should explain the consequence of the answer. Do not put clickable URLs into form fields and do not request secrets even if the schema can technically accept a string.

The client lets the user review, edit, accept, decline, or cancel the response and validates content against the schema. The server repeats schema and domain validation: range, tenant membership, object existence, current version, and allowed transitions. Accept means the user submitted values; it does not automatically approve a later high-risk action. Decline ends the request without a hidden default, while cancel must not be interpreted as a negative business decision.

• Collect only the fields needed for the current request.
• Separate schema validity from business authorization.
• Do not log full content without a retention purpose and data classification.
• After decline or cancel, do not repeat the prompt in an endless agent loop.

A URL request contains mode, message, an opaque elicitationId, and a URL. The client displays the full address and highlights the domain, asks for explicit consent, does not prefetch metadata, and opens the flow in a secure browser context where neither the client nor the LLM can see entered data. The server does not place PII, credentials, or a pre-authenticated bearer capability in the URL. HTTPS is the production baseline; suspicious Unicode or Punycode hosts require a warning or blocking policy.

ElicitResult accept in URL mode only means the user agreed to navigate to the address. It does not prove that OAuth, payment, or credential setup completed. The server keeps a separate state record keyed by elicitationId and bound to the authoritative user, client/session context, intended provider, expiry, and a one-time nonce. Completion is confirmed by a server-side callback or another authoritative system. An elicitation/complete notification may wake the client, but manual retry or cancel remains available if the notification is lost.

MCP authorization protects client access to the MCP server. URL elicitation solves a different problem: the server asks the user to connect a downstream service or complete a secure out-of-band interaction. The bearer token between client and MCP server does not change through this flow. Never send a downstream token back through model context, a tool result, or form content; the server stores the credential in a managed vault and binds it to verified identity and scope.

The connect URL must resist phishing relay. The server verifies that the browser user is the same authoritative subject for whom the elicitation was created instead of trusting an email address or name from a query parameter. State and nonce are single-use, short-lived, and bound to the provider and redirect target. The callback validates issuer, audience, state, and allowed redirect URI. Reopening the URL, switching users, or using an expired record completes without attaching a credential.

• MCP token → client-to-server access.
• Downstream grant → server-to-third-party access for a specific user or tenant.
• elicitationId → correlation handle, not proof of identity or completion.
• Browser session + verified subject → authoritative binding.

Contract tests cover initialization with form-only, URL-only, both modes, and no elicitation; omitted mode as form; unsupported mode; accept, decline, and cancel; schema rejection; unknown or duplicate completion IDs; and request association. URL cases verify that the client does not prefetch the address, shows the host, requires consent, and does not return external content in the protocol result. Form cases block password, token, API key, and payment fixtures regardless of their field names.

Security tests try to change elicitationId, tenant, provider, redirect, state, and browser subject; replay a callback; use an expired URL; substitute a Punycode host; or recover a secret from logs or traces. Recovery tests lose the accept response, completion notification, and originating retry. Assertions require idempotent resume: a repeated tool request first reconciles elicitation state and the downstream connection instead of creating a second OAuth grant or payment.

• Hard gate → secret in a form, automatic navigation, identity mismatch, or credential leakage.
• Protocol gate → request without association or a mode without capability.
• Recovery gate → lost notification must not create a duplicate external effect.
• UX gate → server, purpose, domain, and decline/cancel are clear before consent.

Start with form mode for a reversible read-only workflow containing two or three non-secret fields. Measure completion, decline/cancel, validation failures, repeated prompts, and time-to-resume without recording raw values in general telemetry. Then add one URL flow to an allowlisted HTTPS origin with a pinned redirect policy, verified identity binding, expiry, replay protection, vault storage, audit evidence, and a kill switch.

Promote the canary only after contract, privacy, phishing, recovery, and accessibility gates pass. Rollback blocks new elicitation requests, preserves reconciliation for in-flight records, revokes unfinished state handles, and restores a documented manual setup path. Retest after a change to the MCP revision, SDK/client, capability manifest, browser container, identity provider, downstream OAuth configuration, or data classification. The verdict always applies to a specific client-server-flow combination, never to the universal safety of URL mode.