feat: sep-1036 add URL Mode Elicitation

[devcrocod]

closes #410

How Has This Been Tested?

integration and unit tests

Breaking Changes

none

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

[Copilot]

Pull request overview

Implements SEP-1036 “URL Mode Elicitation” across the Kotlin MCP client/server/core, enabling out-of-band user interactions (e.g., OAuth) to be initiated via elicitation/create in mode: "url" and completed via notifications/elicitation/complete, plus a dedicated JSON-RPC error code for “URL elicitation required”.

Changes:

• Add URL-mode elicitation request params + capability predicate (supportsUrl) and plumb capability enforcement in server-to-client calls.
• Introduce UrlElicitationRequiredException (JSON-RPC error -32042) and reconstruct it on the client from JSON-RPC errors.
• Add client API for handling elicitation completion notifications, and expand unit/integration coverage for the new flow.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/Server.kt	Re-throws UrlElicitationRequiredException during tool execution so it surfaces as JSON-RPC error -32042 instead of a tool error result.
kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/ClientConnection.kt	Enforces elicitation.url capability before sending URL-mode elicitation requests or completion notifications.
kotlin-sdk-core/src/commonTest/kotlin/io/modelcontextprotocol/kotlin/sdk/types/ElicitationTest.kt	Adds tests for UrlElicitationRequiredException serialization and McpException.fromError reconstruction/degradation behavior.
kotlin-sdk-core/src/commonTest/kotlin/io/modelcontextprotocol/kotlin/sdk/types/CapabilitiesTest.kt	Adds tests for the new supportsUrl predicate behavior.
kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/UrlElicitationRequiredException.kt	Introduces typed exception + payload type for URL-elicitation-required errors (-32042).
kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/McpException.kt	Makes McpException extensible and adds internal fromError factory for reconstructing typed exceptions.
kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/jsonRpc.kt	Adds new JSON-RPC error code constant URL_ELICITATION_REQUIRED = -32042.
kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/elicitation.kt	Adds/extends URL-mode elicitation documentation and keeps URL params modeled with mode = "url".
kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types/capabilities.kt	Adds ClientCapabilities.Elicitation?.supportsUrl extension property.
kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/shared/Protocol.kt	Uses McpException.fromError when converting JSON-RPC errors into exceptions for callers.
kotlin-sdk-core/api/kotlin-sdk-core.api	Updates API dump for new types/consts and McpException becoming non-final.
kotlin-sdk-client/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/client/Client.kt	Adds setElicitationCompleteHandler and updates elicitation handler docs for URL mode.
kotlin-sdk-client/api/kotlin-sdk-client.api	Updates API dump for new client method setElicitationCompleteHandler.
integration-test/src/jvmTest/kotlin/io/modelcontextprotocol/kotlin/sdk/server/ClientConnectionTest.kt	Updates integration test client capabilities to advertise elicitation.url.
integration-test/src/commonTest/kotlin/io/modelcontextprotocol/kotlin/sdk/client/ClientTest.kt	Adds end-to-end integration tests for URL-mode elicitation, completion notifications, and -32042 typed exception surfacing.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.