Add support for URL mode elicitation #1021

halter73 · 2025-11-24T17:57:12Z

This PR adds support URL mode elicitation requests defined by SEP-1036 which is for out-of-band server-to-client elicitations that may involve sensitive data the MCP server doesn't want to give to the MCP client or host.

Fixes #750

halter73 · 2025-11-24T20:02:49Z

src/ModelContextProtocol.Core/McpSessionHandler.cs

+            return urlException;
+        }
+
+        return new McpProtocolException(formattedMessage, errorCode);


Another thing we could do in addition to or instead of throwing a UrlElicitationRequiredException is to always attach the JsonRpcError to a nullable property on McpProtocolExceptions if it was created from one.

That seems better / more general-purpose than a custom exception type.

Do you not like the ability to specifically catch a UrlElicitationRequiredException? The alternative would be to catch all McpProtocolException and then parse the JsonNode Data property.

Maybe I've misunderstood. Why does someone need to catch it? Are we using it for control flow?

Yes. This is tested by UrlElicitationRequired_Exception_Propagates_To_Client. I don't have a proper client sample, but if I did, it would look a lot like the TypeScript one in https://github.com/modelcontextprotocol/typescript-sdk/blob/e6c71bbab1dff7bf0c84eee96e74ef87f82a1dbe/src/examples/client/elicitationUrlExample.ts#L711-L719.

Does that mean the mcp spec dictates that url elicitations be modeled as json rpc errors?

It's either an error or a request. Section 4.2 and 4.3 of the new elicitation spec go over the two flows for URL elicitation.

URL Mode Flow

sequenceDiagram participant UserAgent as User Agent (Browser) participant User participant Client participant Server Note over Server: Server initiates elicitation Server->>Client: elicitation/create (mode: url) Client->>User: Present consent to open URL User-->>Client: Provide consent Client->>UserAgent: Open URL Client->>Server: Accept response Note over User,UserAgent: User interaction UserAgent-->>Server: Interaction complete Server-->>Client: notifications/elicitation/complete (optional) Note over Server: Continue processing with new information

Loading

URL Mode With Elicitation Required Error Flow

sequenceDiagram participant UserAgent as User Agent (Browser) participant User participant Client participant Server Client->>Server: tools/call Note over Server: Server needs authorization Server->>Client: URLElicitationRequiredError Note over Client: Client notes the original request can be retried after elicitation Client->>User: Present consent to open URL User-->>Client: Provide consent Client->>UserAgent: Open URL Note over User,UserAgent: User interaction UserAgent-->>Server: Interaction complete Server-->>Client: notifications/elicitation/complete (optional) Client->>Server: Retry tools/call (optional)

Loading

https://modelcontextprotocol.io/specification/2025-11-25/client/elicitation#message-flow

Ok, in that case it makes sense to keep the exception. I think it's unfortunate that elicitation requests are being modeled as errors.

PederHP · 2025-11-24T20:57:13Z

docs/concepts/elicitation/elicitation.md


-If the user provides the requested information, the ElicitationHandler should return an <xref:ModelContextProtocol.Protocol.ElicitResult> with the action set to "accept" and the content containing the user's input.
-If the user does not provide the requested information, the ElicitationHandler should return an [<xref:ModelContextProtocol.Protocol.ElicitResult> with the action set to "reject" and no content.
+Elicitation is an optional feature so clients declare their support for it in their capabilities as part of the `initialize` request. Clients can support `Form` (in-band), `Url` (out-of-band), or both.


Optional capability? It's a little redundant as almost every capability is optional. Maybe just "Clients declare their support.." ?

Suggested change

Elicitation is an optional feature so clients declare their support for it in their capabilities as part of the `initialize` request. Clients can support `Form` (in-band), `Url` (out-of-band), or both.

Clients declare their support for elicitation in their capabilities as part of the `initialize` request. Clients can support `Form` (in-band), `Url` (out-of-band), or both.

PederHP · 2025-11-24T21:03:12Z

Really like the example. Only downside is it might distract from the fact url mode will usually point at an url that is distinct from the mcp server. I think an ideal sample should be MCP server and separate blazor server with some communication mechanism between them. Just to show it's out of band and the security pattern of the sensitive information never passing through the mcp server. But that's something that can be done later.

halter73 · 2025-11-24T21:32:16Z

Really like the example. Only downside is it might distract from the fact url mode will usually point at an url that is distinct from the mcp server. I think an ideal sample should be MCP server and separate blazor server with some communication mechanism between them. Just to show it's out of band and the security pattern of the sensitive information never passing through the mcp server. But that's something that can be done later.

I accidently pushed the sample. I removed it from this PR. It wasn't fully functional yet, and it didn't use auth for the Blazor form. Later we can add a sample that leverages AddOpenIdConnect and AddCookie pointing to the same OAuth provider as AddMcp, possibly in a different project to show that the URL doesn't need to be hosted by the MCP server. I don't think it's really a problem to have the MCP server host the elicitation URL though. It still serves a purpose of collecting sensitive information from the user without exposing it to the host or client.

docs/concepts/elicitation/elicitation.md

src/ModelContextProtocol.Core/Client/McpClientImpl.cs

stephentoub · 2025-11-25T15:35:28Z

src/ModelContextProtocol.Core/Client/McpClientImpl.cs

+            {
+                // If ElicitationCapability is set but both modes are null, default to form mode for backward compatibility
+                _options.Capabilities.Elicitation.Form = new();
+            }


Seems like this could be simplified slightly to:

_options.Capabilities.Elicitation ??= new(); if (_options.Capabilities.Elicitation.Form is null && _options.Capabilities.Elicitation.Url is null) { // If both modes are null, default to form mode for backward compatibility. _options.Capabilities.Elicitation.Form = new(); }

stephentoub · 2025-11-25T15:42:27Z

src/ModelContextProtocol.Core/Protocol/ElicitationCapability.cs

+
+            var capability = new ElicitationCapability();
+            bool hasForm = false;
+            bool hasUrl = false;


Why do we need these bools rather than just checking whether Form/Url are set?

halter73 added this to the 2025-11-25 Spec Compliance milestone Nov 24, 2025

halter73 requested review from eiriktsarpalis, mikekistler and stephentoub November 24, 2025 17:57

halter73 force-pushed the halter73/750 branch from 0debdd5 to 8ee8b5b Compare November 24, 2025 18:00

halter73 commented Nov 24, 2025

View reviewed changes

Add support for URL mode elicitation

66a0c7e

PederHP reviewed Nov 24, 2025

View reviewed changes

halter73 force-pushed the halter73/750 branch from 31c3125 to 66a0c7e Compare November 24, 2025 21:25

stephentoub reviewed Nov 25, 2025

View reviewed changes

docs/concepts/elicitation/elicitation.md Show resolved Hide resolved

stephentoub reviewed Nov 25, 2025

View reviewed changes

src/ModelContextProtocol.Core/Client/McpClientImpl.cs Show resolved Hide resolved

stephentoub reviewed Nov 25, 2025

View reviewed changes

stephentoub approved these changes Nov 25, 2025

View reviewed changes

This was referenced Nov 25, 2025

Add support for data to McpProtocolException #1028

Open

Add request options bag to high level requests and include Meta #970

Open

	Elicitation is an optional feature so clients declare their support for it in their capabilities as part of the `initialize` request. Clients can support `Form` (in-band), `Url` (out-of-band), or both.
	Clients declare their support for elicitation in their capabilities as part of the `initialize` request. Clients can support `Form` (in-band), `Url` (out-of-band), or both.

Add support for URL mode elicitation #1021

Are you sure you want to change the base?

Add support for URL mode elicitation #1021

Conversation

halter73 commented Nov 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

stephentoub Nov 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

URL Mode Flow

URL Mode With Elicitation Required Error Flow

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

PederHP commented Nov 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

halter73 commented Nov 24, 2025

Uh oh!

Uh oh!

Uh oh!

stephentoub Nov 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

halter73 commented Nov 24, 2025 •

edited

Loading

stephentoub Nov 25, 2025 •

edited

Loading

PederHP commented Nov 24, 2025 •

edited

Loading

stephentoub Nov 25, 2025 •

edited

Loading