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

[Kehrlann]

This is a tracking issue for modelcontextprotocol/modelcontextprotocol#887

[embesozzi]

It would be a valuable feature to support out-of-band interactions in the context of authentication or JIT authorization for users with the OAuth 2.0 Device Authorization Grant [1]

[1] https://datatracker.ietf.org/doc/html/rfc8628

[sainathreddyb]

I am working on implementing this should have a PR shortly

[Kehrlann]

@sainathreddyb please discuss the design here before fleshing out a full PR.

[sainathreddyb]

Hey @Kehrlann, here's the design I'm proposing. Happy to iterate.

Context: The TypeScript SDK already implements URL mode elicitation. The Java SDK has the capability plumbing (#731) but not the actual protocol flow.

Approach: Flat record (matching TypeScript runtime behavior)

I considered two options:

1. Sealed interface (ElicitRequestFormParams | ElicitRequestURLParams with @JsonTypeInfo) — gives compile-time type safety but breaks the existing handler signature Function<ElicitRequest, Mono<ElicitResult>> and every createElicitation() call site. The Content interface uses this pattern, but it was designed that way from the start.

2. Flat record (add mode, url, elicitationId to existing ElicitRequest) — zero breaking changes, matches how the TypeScript SDK actually works at runtime (elicitInput() takes the union and switches on mode). Tradeoff: no compile-time enforcement that URL mode can't have requestedSchema, but the builder validates at runtime.

I went with option 2. The TypeScript SDK doesn't break its handler signature either — it keeps one handler that receives ElicitRequest and branches on params.mode.

Changes :

• McpSchema.ElicitRequest — added mode, url, elicitationId fields. Backward-compat constructors preserved. Builder validates mode="url" requires url+elicitationId.
• McpSchema.ElicitationCompleteNotification — new record for notifications/elicitation/complete
• McpSchema.ErrorCodes.URL_ELICITATION_REQUIRED = -32042
• McpAsyncServerExchange.createElicitation() — now checks URL capability when mode="url"
• McpAsyncServerExchange.sendElicitationComplete() — new method
• McpSyncServerExchange — sync wrapper
• Client side: elicitationCompleteConsumer on builder, notification handler in McpAsyncClient

Open questions for you:

1. Are you OK with the flat record approach, or do you prefer the sealed interface despite the breaking change?
2. Should the builder throw on mode="url" + requestedSchema, or silently ignore requestedSchema?
3. Any naming preferences? (sendElicitationComplete vs notifyElicitationComplete)

[sainathreddyb]

@Kehrlann please let me know if you have need further details on design.
For now created a PR will iterate on it based on feedback #939