← cartapi.io blog

MCP URL elicitation for payments vs a checkout link in the tool result

Published 2026-11-15 · Last updated 2026-11-15 · 8 min read · agent commerce protocol
TL;DR

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:

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:

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 elicitationCheckout URL in the tool result
Who shows the linkThe client, in its own UIThe model, in its reply
Consent prompt with the domainRequired by the specUp 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 typedPayment provider's pagePayment provider's page
Page readable by client or modelMust not beDepends on how the client opens links
Completion signalOptional notification (2025-11-25) or a retry with requestState (2026-07-28)The agent polls an order-status tool
Client supportOnly clients that declare elicitation.urlEvery client
Server stateMust bind the elicitation to the user, not just a session IDOrder 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:

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

  1. Read the client's capabilities. Under 2025-11-25, {"elicitation": {"url": {}}} means URL mode is available. An empty elicitation object means form mode only. Never send a mode the client didn't declare.
  2. If URL mode is declared, use it for the payment page. Put the amount and item in message.
  3. Otherwise, return the URL in the tool result. Include the price and item in structured fields, so the model has less reason to paraphrase.
  4. 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.
  5. Fulfil from the webhook, not from accept or a completion notification.
  6. Keep the URL clean and short-lived: an opaque ID, no personal information, HTTPS, a short expiry.
  7. 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.

About the author

Roc Chow

Roc Chow builds cartapi, the commerce layer for AI agents, and runs . The protocol details here are from the MCP specification's 2025-11-25 and 2026-07-28 elicitation pages, read on 2026-11-15. The description of cartapi's own server comes from its source code.

LinkedIn · · cartapi.io