Skip to content

SEP-1036: URL Mode Elicitation for secure out-of-band interactions #1036

Closed

Description

@nbarbettini

Preamble

Title: URL Mode Elicitation for Secure Out-of-Band Interactions
Authors: Nate Barbettini (@nbarbettini) and Wils Dawson (@wdawson)
Status: proposal
Type: Standards Track
Created: 2025-07-22 (originally proposed pre-SEP; 2025-07-01)

Abstract

This SEP introduces a new url mode for the existing elicitation client capability, enabling secure out-of-band interactions that bypass the MCP client. URL mode elicitation addresses sensitive use cases that form mode elicitation cannot, such as gathering sensitive credentials, performing OAuth flows for external (3rd-party) authorization, and handling payments, without exposing sensitive data to the MCP client. By directing users to trusted URLs in their browser, this mode maintains security boundaries while enabling rich integrations with third-party services.

Motivation

The current MCP specification (2025-06-18) provides an elicitation mechanism for gathering non-sensitive information from users through structured, in-band requests (most commonly imagined as the MCP client rendering a form to collect data from the end-user). However, several critical use cases require interactions that must not pass through the MCP client:

  1. Sensitive data collection: API keys, passwords, and other credentials must never transit through intermediary systems.
  2. External authorization: MCP servers often need to access third-party APIs on behalf of users. The MCP authorization specification only covers client-to-server authorization, not server-to-third-party authorization. The Security Best Practices document explicitly forbids token passthrough, requiring a secure mechanism for external (3rd-party) OAuth flows. This was a particularly important motivating factor emerging from discussions in Multi-user Authorization #234 and [RFC] Update the Authorization specification for MCP servers #284.
  3. Payment and Subscription Flows: Financial transactions require PCI compliance and secure payment processing that cannot be achieved through in-band data collection.

Without a standardized mechanism for these interactions, MCP servers must resort to non-standard workarounds or insecure practices like requesting API keys through in-band, form-style elicitation. This SEP addresses these gaps by introducing a URL elicitation mode that leverages established web security patterns to handle sensitive interactions securely.

URL elicitation is fundamentally different from MCP authorization. URL elicitation is not for authorizing the MCP client's access to the MCP server (that's handled directly by MCP authorization). Instead, it's used when the MCP server needs to obtain sensitive information or third-party authorization on behalf of the user. The MCP client's bearer token remains unchanged, and the client's only responsibility is to provide the user with context about the elicitation URL the server wants them to open.

Specification

Overview

Elicitation is updated to support two modes:

  • Form mode (in-band): Servers can request structured data from users with optional JSON schemas to validate responses (no change here, other than adding a name to the existing capability)
  • URL mode (out-of-band): Servers can direct users to external URLs for sensitive interactions that must not pass through the MCP client

Capabilities

Clients that support elicitation MUST declare the elicitation capability during initialization:

{
  "capabilities": {
    "elicitation": {
      "form": {},
      "url": {}
    }
  }
}

For backwards compatibility, an empty capabilities object is equivalent to declaring support for form mode only:

{
  "capabilities": {
    "elicitation": {},
  },
}

Clients declaring the elicitation capability MUST support at least one mode (form or url).

Form Elicitation Requests

The only change from the existing specification is the addition of a mode field in the elicitation/create request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "elicitation/create",
  "params": {
    "mode": "form", // New field
    "message": "Please provide your GitHub username",
    "requestedSchema": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        }
      },
      "required": ["name"]
    }
  }
}

URL Elicitation Requests

URL elicitation requests MUST specify mode: "url" and include these parameters:

Name Type Description
url string The URL that the user should navigate to.
elicitationId string A unique identifier for the elicitation.
message string A human-readable message explaining why the interaction is needed.

Example: OAuth Authorization Flow

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "elicitation/create",
  "params": {
    "mode": "url",
    "elicitationId": "550e8400-e29b-41d4-a716-446655440000",
    "url": "https://github.com/login/oauth/authorize?client_id=abc123&state=xyz789&scope=repo",
    "message": "Please authorize access to your GitHub repositories to continue."
  }
}

Response Actions

URL elicitation responses use the same three-action model as form elicitation:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "action": "accept" // or "decline" or "cancel"
  }
}

The response with action: "accept" indicates that the user has consented to the interaction. The interaction occurs out of band and the client is not aware of the outcome unless the server sends a completion notification.

Completion Notifications

Servers SHOULD send a notifications/elicitation/complete notification when an
out-of-band interaction started by URL mode elicitation is completed. This allows clients to react programmatically if appropriate.

  • The notification MUST only be sent to the client that initiated the elicitation request.
  • The notification MUST include the elicitationId established in the original elicitation/create request.
  • Clients MUST ignore notifications referencing unknown or already-completed IDs.
  • If a completion notification never arrives, clients SHOULD provide a manual way for the user to continue the interaction.

Clients MAY use the notification to automatically retry requests that received a URL elicitation required error, update the user interface, or otherwise continue an interaction. However, because delivery of the notification is not guaranteed, clients must not wait indefinitely for a notification from the server.

{
  "jsonrpc": "2.0",
  "method": "notifications/elicitation/complete",
  "params": {
    "elicitationId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

URL Elicitation Required Error

When a request cannot be processed until an elicitation is completed, the server MAY return a URLElicitationRequiredError (code -32042) to indicate that a URL mode elicitation is required. The server MUST NOT return this error except when URL mode elicitation is required by the user interaction.

{
  "jsonrpc": "2.0",
  "id": 2,
  "error": {
    "code": -32042,
    "message": "This request requires more information.",
    "data": {
      "elicitations": [
        {
          "mode": "url",
          "elicitationId": "550e8400-e29b-41d4-a716-446655440000",
          "url": "https://oauth.example.com/authorize?client_id=abc123&response_type=code&...",
          "message": "Authorization is required to access your Example Co files."
        }
      ]
    }
  }
}

Any elicitations returned in the error MUST be URL mode elicitations and include an elicitationId.

Returning a URLElicitationRequiredError is equivalent to sending an elicitation/create request. The server may return an error (instead of sending a separate elicitation/create request) as an affordance to the client to make it clear that a particular elicitation is directly related to a failed client request.

The client must treat URLElicitationRequiredError responses as equivalent to elicitation/create requests. Clients may automatically retry the failed request after the elicitation is completed successfully, for example after receiving a completion notification.

Rationale

Design Decisions

Why extend elicitation instead of creating a new mechanism?

Initially, we considered creating a separate mechanism for out-of-band interactions (discussed in #475). However, after discussions with the MCP maintainers, we decided to extend the existing elicitation specification because:

  1. Both mechanisms serve the same fundamental purpose: gathering information from users
  2. Having two similar-but-separate mechanisms for the same purpose is confusing and error-prone
  3. The mode parameter cleanly separates the two interaction patterns

Why can't the client perform the interaction itself?

It is tempting to suggest that the MCP client should perform the interaction itself, e.g. act as an OAuth client to a third-party authorization server. However, there are several reasons why this is not a good idea:

  • If the MCP client obtains user tokens from a third-party authorization server, the MCP server becomes a token passthrough server, which is explicitly forbidden.
  • Similarly, for payment-type flows, the MCP client would need to perform PCI-compliant payment processing, which is not a desired requirement for MCP clients.

Why doesn't the server block (wait) on the elicitation to complete?

URL mode elicitation requests are asynchronous or "disconnected" flows by design, because the kinds of interactions they enable are inherently asynchronous. Payment flows, external authorization, etc. can take minutes or more to complete, and in some cases never complete at all (if abandoned by the end-user).

Why disallow URLs in form mode?

Being very explicit about when URLs can (and cannot) be sent in an elicitation request improves the client's security posture. By clearly stating in the spec that URLs are only allowed in the url field of a URL mode elicitation request, client implementers can implement UX patterns that are consistent with the security model. For example, a client could refuse to render a URL as a clickable hyperlink in a form mode elicitation request, reducing the likelihood of a user clicking on a malicious URL sent by a malicious server.

Alternative Approaches Considered

  1. Token Passthrough: Simply passing the MCP client's token to external services was rejected due to security concerns documented in the Security Best Practices. Having the MCP client obtain additional tokens and passing those to the MCP server was rejected for the same reason.

  2. OAuth-specific Capability: Creating a capability specific to external (3rd-party) authorization with OAuth was considered, but rejected in favor of the more general URL mode elicitation approach that supports multiple use cases.

Community Feedback

This proposal incorporates extensive community feedback from discussions in #475, #234, and #284, as well as the #auth-wg working group on Discord. The community identified the need for:

  • Secure credential collection without client exposure
  • External authorization patterns separate from MCP authorization
  • Payment and subscription flow support
  • Clear security boundaries and trust models

Backward Compatibility

This SEP introduces the following breaking changes:

  1. Capability Declaration: Clients must now specify which elicitation modes they support:

    {
      "capabilities": {
        "elicitation": {
          "form": {},
          "url": {}
        }
      }
    }

    Previously, clients only declared "elicitation": {} without mode specification.

  2. Mode Parameter: All elicitation/create requests must now include a mode parameter ("form" or "url").

Migration Path

To ease migration:

  • Servers SHOULD check client capabilities before sending mode-specific requests
  • Clients MAY initially support only form mode to maintain compatibility
  • Existing form elicitation implementations continue to work with the addition of the mode parameter

Reference Implementation

Client/server implementation in TypeScript: feat/url-elicitation

Explainer video: https://drive.google.com/file/d/1llCFS9wmkK_RUgi5B-zHfUUgy-CNb0n0/view?usp=sharing

Security Implications

This SEP introduces several security considerations:

URL Security Requirements

  1. SSRF Prevention: Clients must validate URLs to prevent Server-Side Request Forgery attacks
  2. Protocol Restrictions: Only HTTPS URLs are allowed for URL elicitation
  3. Domain Validation: Clients must clearly display target domains to users

Trust Boundaries

URL elicitation explicitly creates clear trust boundaries:

  • The MCP client never sees sensitive data obtained by the MCP server via URL elicitation
  • The MCP server must independently verify user identity
  • Third-party services interact directly with users through secure browser contexts

Identity Verification

Servers must verify that the user completing a URL elicitation is the same user who initiated the request. Verifying the identity of the user must not rely on untrusted input (e.g. user input) from the client.

Implementation Requirements

  1. Clients must:

    • Use secure browser contexts that prevent inspection of user inputs
    • Validate URLs for SSRF protection
    • Obtain explicit user consent before opening URLs
    • Clearly display target domains
  2. Servers must:

    • Bind elicitation state to authenticated user sessions
    • Verify user identity at the beginning and end of a URL elicitation flow
    • Implement appropriate rate limiting
  3. Both parties should:

    • Log security events for audit purposes
    • Implement timeout mechanisms for elicitation requests
    • Provide clear error messages for security failures

Relationship to Existing Security Measures

This proposal builds upon and complements existing MCP security measures:

  • Works within the existing MCP authorization framework (MCP authorization is not affected by this proposal)
  • Follows Security Best Practices regarding token handling
  • Maintains separation of concerns between client-server and server-third-party authorization

Activity

  1. self-assigned this
    on Jul 24, 2025
  2. changed the title [-]SEP: URL Mode Elicitation for secure out-of-band interactions[/-] [+]SEP-1036: URL Mode Elicitation for secure out-of-band interactions[/+] on Jul 24, 2025
  3. added
    draftSEP proposal with a sponsor.
    and removed
    in-reviewSEP proposal ready for review.
    on Jul 24, 2025
  4. dsp-ant commented on Aug 1, 2025

    @dsp-ant
    Member

    Is there a demo / reference implementation?

  5. nbarbettini commented on Aug 1, 2025

    @nbarbettini
    ContributorAuthor

    @dsp-ant Not yet, but soon. @wdawson is building one right now. Hopefully that is not a blocker to getting this SEP accepted and into review.

  6. nbarbettini commented on Aug 6, 2025

    @nbarbettini
    ContributorAuthor

    Added a reference implementation branch (TypeScript client/server) above, along with an explainer video. Thanks @wdawson! ❤️

  7. dickhardt commented on Aug 6, 2025

    @dickhardt

    I'm supportive of this SEP

    This SEP does pretty much everything I am proposing in:

    #1299

    I added in a interaction_completion_uri so that non SSE MCP Servers could turn the user experience back to the MCP Client and the Client would then know it should try the call again.

    I'd prefer that interactions were not mixed with elicitations. the name elicitation implies a reis a request and response -- IE the server asks the client to get something from the user and then sends the result back to the server

    A interaction could be a fire and forget

  8. added
    in-reviewSEP proposal ready for review.
    and removed
    draftSEP proposal with a sponsor.
    on Aug 15, 2025
  9. pcarleton commented on Aug 15, 2025

    @pcarleton
    Member

    marking as in-review per discussion in auth meeting (cc @localden )

  10. 9 remaining items

  11. kevinswiber commented on Sep 17, 2025

    @kevinswiber

    For any networking folks coming upon this issue and experiencing confusion by the use of "downstream" in this proposal, allow me to explain.

    Some communities, including the OAuth community, think in terms of a call chain through service dependencies. A client or service initiating a call is higher up the chain (upstream). Services it depends on are lower down the chain (downstream).

    Most networking folks--and certainly HTTP folks--think in terms of packet/request flow. The terms "upstream", "downstream", "inbound", and "outbound" were actually defined in the HTTP/1.1 RFC (1999). In fact, when we think of an "upload" or a "download", there's usually no discrepancy there at all. Moving away from the client is upstream/inbound. Moving towards the client is downstream/outbound.

    So if you're coming to this with a networking mindset, rest assured. You're not stuck in a Mandela Effect. Just flip your mental model for the OAuth context, and you'll be good to go!

  12. dsp-ant commented on Sep 23, 2025

    @dsp-ant
    Member

    @localden @nbarbettini What's the status of this? Can we get the #887 finalized and merged?
    @nbarbettini Are you driving the SDK implementations or at least a subset?

    I want to close this out.

  13. nbarbettini commented on Sep 23, 2025

    @nbarbettini
    ContributorAuthor

    @kevinswiber Thanks for the flag - I am not attached to the term "downstream" in this proposal at all. I think "external" would be just as accurate, and less ambiguous. Fixed, thanks!

  14. nbarbettini commented on Sep 23, 2025

    @nbarbettini
    ContributorAuthor

    @dsp-ant We've updated #887 with all of the feedback from the review meeting, as well as feedback from the client implementors group. @localden can confirm, but I think we are good to go.

    Re: SDK implementations, I will coordinate with @wdawson since he built the prototype SDK impl in TS. Do we hand that prototype over to the client implementors group, or finish it ourselves? What's ideal for you?

  15. nbarbettini commented on Nov 8, 2025

    @nbarbettini
    ContributorAuthor

    Note: Updated this issue description to match the final draft of #887

  16. added
    finalSEP finalized.
    and removed
    acceptedSEP accepted by core maintainers, but still requires final wording and reference implementation.
    on Jan 28, 2026
  17. moved this from Accepted to Final in SEP Review Pipelineon Jan 28, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Type

No type

Projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions