MCP URL elicitation for payments vs a checkout link in the tool result
URL-mode elicitation is MCP's own way to send a user to a payment page. The client, not the model, shows the URL, asks for consent and opens it somewhere neither the client nor the model can read. Returning a checkout URL in a tool result works in every client today, but the model relays the link. If the client declares URL elicitation, use it. Keep the tool-result link as the fallback. In both cases the card goes into the payment provider's page, and the webhook, not the elicitation response, tells you the payment happened.
Most MCP servers that sell something do what our Stripe Checkout guide describes: create a hosted checkout session and return its URL in the tool result. The 2025-11-25 MCP specification added a protocol-level alternative, URL-mode elicitation, and named payment processing as one of its uses. Here is what the spec actually requires, how the two patterns differ, and which one to ship.
What URL-mode elicitation is
Elicitation lets a server ask the user for something in the middle of a tool call. It has two modes:
- Form mode. The server sends a flat JSON schema, and the client renders a form. The data the user types goes back through the client.
- URL mode. The server sends a URL, and the client asks the user whether to open it. What the user does on that page never passes through the client.
The spec draws a hard line between them. Servers must not use form mode for "passwords, API keys, access tokens, or payment credentials", and must use URL mode for those. It defines sensitive as secrets and credentials that grant access or authorize transactions. A name or email in a form is allowed.
URL mode was introduced in 2025-11-25, and the spec warns that its design may change. It already has. The 2026-07-28 revision keeps the same rules but changes the message flow, which is covered below.
What the client must do with the URL
This is where URL mode differs most from a link in a tool result. Under the spec's safe-URL rules, a client:
- must not pre-fetch the URL or its metadata
- must not open it without the user's explicit consent
- must show the full URL before asking for consent, and should highlight the domain
- must open it in a way that doesn't let the client or the model inspect the page or the user's input. The spec's iOS example: SFSafariViewController is fine, WKWebView is not.
The server has rules too. It must not put credentials or personal information in the URL, must not send a URL that is pre-authenticated to a protected resource, and should use HTTPS.
URL elicitation vs a checkout link in the tool result
| URL-mode elicitation | Checkout URL in the tool result | |
|---|---|---|
| Who shows the link | The client, in its own UI | The model, in its reply |
| Consent prompt with the domain | Required by the spec | Up to the model and the client |
| Can the model alter or drop the link? | No. It goes from server to client. | Yes, for example under prompt injection |
| Where the card is typed | Payment provider's page | Payment provider's page |
| Page readable by client or model | Must not be | Depends on how the client opens links |
| Completion signal | Optional notification (2025-11-25) or a retry with requestState (2026-07-28) | The agent polls an order-status tool |
| Client support | Only clients that declare elicitation.url | Every client |
| Server state | Must bind the elicitation to the user, not just a session ID | Order row keyed to the buyer |
The card is safe in both columns, because it's typed into the payment provider's page either way. What URL mode adds is a trustworthy path for the link itself: the user sees the real domain in client UI, approves it, and the model can't swap it for something else.
"Accept" doesn't mean "paid"
Elicitation responses have three actions: accept, decline and cancel. In URL mode, accept only means the user agreed to open the page. The spec says so directly: the interaction happens out of band and the client doesn't know how it ended.
How the server reports completion depends on the spec version:
- 2025-11-25. The server sends
elicitation/createwith a uniqueelicitationId. It may later sendnotifications/elicitation/completewith that ID. It can also refuse a tool call withURLElicitationRequiredError(code-32042), listing the URL elicitations needed before a retry. - 2026-07-28. The server returns an
InputRequiredResultcontaining the elicitation and an optionalrequestState. The client retries the original call with the user's response and that state, and the server either returns the final result or asks again.
For payments, neither signal replaces the webhook. Fulfil when the provider says the charge succeeded, the way you would without MCP. The elicitation flow only decides when the agent asks you again.
What a payment elicitation looks like
Under 2025-11-25, a server that has just created a checkout session would send something like this. The structure follows the spec's own example; the URL and message are ours.
{
"jsonrpc": "2.0",
"id": 7,
"method": "elicitation/create",
"params": {
"mode": "url",
"elicitationId": "ord_8c1f…",
"url": "https://checkout.stripe.com/c/pay/cs_…",
"message": "Pay $10.51 for a $100 MXN Telcel recarga to +52 55 1234 5678"
}
}
Three details matter. The message should state the amount and the item, because it's what the user reads in the consent dialog. The URL carries only an opaque session ID, with no email or phone number in the query string. And the session should expire quickly, so a link that leaks into a log is worth little.
The spec's phishing section is written around OAuth, where the risk is binding someone else's tokens to an attacker's session. A checkout page is lower stakes, since a stranger who opens it can only pay for your order. The rule still applies, though: the server must make sure the person completing the flow is the person it was created for, at least before it shows them anything about the order.
What we do today, and why
cartapi's MCP server uses the tool-result pattern. get_checkout_link and create_topup_checkout return mode: "hosted_checkout", a Stripe checkout_url, its expires_at and, for top-ups, a summary with the detected carrier and the amount delivered. The server instructions tell the agent never to create a checkout without the user's go-ahead, and to hand the URL over rather than visit it. Reasoning in Consent-first checkout.
Two reasons we haven't switched. First, the endpoint is stateless: it creates a fresh MCP server and transport for every HTTP request and keeps no session. The 2025-11-25 flow is a server-to-client request in the middle of a tool call, so we'd have to keep the call open while someone pays, or add per-user elicitation state. The 2026-07-28 flow, with requestState echoed on retry, fits a stateless server much better. Second, a link in the tool result works in every client, while URL mode only works in clients that declare it, and not all of them do.
There's a second funding path that skips the link entirely: a consent envelope. The user pre-authorizes spending ceilings once, and the agent passes an envelope_token. The charge then runs off-session, and an over-limit request comes back as envelope_denied. That replaces the per-purchase page with a per-budget one. It isn't an elicitation feature.
Which to ship: a checklist
- Read the client's capabilities. Under 2025-11-25,
{"elicitation": {"url": {}}}means URL mode is available. An emptyelicitationobject means form mode only. Never send a mode the client didn't declare. - If URL mode is declared, use it for the payment page. Put the amount and item in
message. - Otherwise, return the URL in the tool result. Include the price and item in structured fields, so the model has less reason to paraphrase.
- Never collect a card number, CVC or API key through form mode. The spec forbids it, and you don't want PCI scope in a chat client anyway.
- Fulfil from the webhook, not from
acceptor a completion notification. - Keep the URL clean and short-lived: an opaque ID, no personal information, HTTPS, a short expiry.
- Pin a spec version in your tests. The URL-mode message flow changed between 2025-11-25 and 2026-07-28.
Choosing a payment rail is a separate question from how you show the page. If software pays per request, see x402 vs Stripe Checkout. For where MCP sits next to ACP and A2A, see ACP vs MCP vs A2A.
Frequently asked questions
What is URL mode elicitation in MCP?
A way for a server to ask the client to send the user to a web page, for payment, OAuth or entering a secret, without that interaction passing through the client. It was added in the 2025-11-25 spec. The client must show the full URL, get consent and open it where neither the client nor the model can read it.
Can an MCP server collect card details with form mode?
No. The spec forbids requesting payment credentials, passwords, API keys or tokens through form mode, and requires URL mode for them.
Does an accept response mean the user paid?
No. Accept means they agreed to open the URL. Use the payment provider's webhook to know the charge succeeded.
Is returning a checkout URL in a tool result still acceptable?
Yes. It works in every client, and the card is still typed into the provider's page. The weakness is that the model relays the link, with no client consent prompt showing the domain.
How do I know if a client supports URL elicitation?
Check its declared capabilities: an elicitation.url key under 2025-11-25, or the capability in _meta on each request under 2026-07-28.
Try it
See the tool-result pattern working: add cartapi from the install page and ask your assistant for a gift card, top-up or eSIM, and you'll get a Stripe link back. Building your own server? The REST and MCP reference is in the docs.