Elicit information from the user via out-of-band URL navigation (URL mode). This method directs the user to an external URL where sensitive interactions can occur without passing data through the MCP client. Use this for: - Collecting sensitive credentials (API keys, passwords) - OA
(
session: ServerSession,
message: str,
url: str,
elicitation_id: str,
related_request_id: RequestId | None = None,
)
| 121 | |
| 122 | |
| 123 | async def elicit_url( |
| 124 | session: ServerSession, |
| 125 | message: str, |
| 126 | url: str, |
| 127 | elicitation_id: str, |
| 128 | related_request_id: RequestId | None = None, |
| 129 | ) -> UrlElicitationResult: |
| 130 | """Elicit information from the user via out-of-band URL navigation (URL mode). |
| 131 | |
| 132 | This method directs the user to an external URL where sensitive interactions can |
| 133 | occur without passing data through the MCP client. Use this for: |
| 134 | - Collecting sensitive credentials (API keys, passwords) |
| 135 | - OAuth authorization flows with third-party services |
| 136 | - Payment and subscription flows |
| 137 | - Any interaction where data should not pass through the LLM context |
| 138 | |
| 139 | The response indicates whether the user consented to navigate to the URL. |
| 140 | The actual interaction happens out-of-band. When the elicitation completes, |
| 141 | the server should send an ElicitCompleteNotification to notify the client. |
| 142 | |
| 143 | Args: |
| 144 | session: The server session |
| 145 | message: Human-readable explanation of why the interaction is needed |
| 146 | url: The URL the user should navigate to |
| 147 | elicitation_id: Unique identifier for tracking this elicitation |
| 148 | related_request_id: Optional ID of the request that triggered this elicitation |
| 149 | |
| 150 | Returns: |
| 151 | UrlElicitationResult indicating accept, decline, or cancel |
| 152 | """ |
| 153 | result = await session.elicit_url( |
| 154 | message=message, |
| 155 | url=url, |
| 156 | elicitation_id=elicitation_id, |
| 157 | related_request_id=related_request_id, |
| 158 | ) |
| 159 | |
| 160 | if result.action == "accept": |
| 161 | return AcceptedUrlElicitation() |
| 162 | elif result.action == "decline": |
| 163 | return DeclinedElicitation() |
| 164 | elif result.action == "cancel": |
| 165 | return CancelledElicitation() |
| 166 | else: # pragma: no cover |
| 167 | # This should never happen, but handle it just in case |
| 168 | raise ValueError(f"Unexpected elicitation action: {result.action}") |