feat: add URL mode elicitation and typed schema definitions per MCP (#660)

Add URL mode elicitation support and typed `PrimitiveSchemaDefinition`
hierarchy to align with MCP specification 2025-11-25

closes #540 

## How Has This Been Tested?
unit/integration/conformance

## Breaking Changes
- `ElicitRequestParams` changed from `data class` to `sealed interface`.
A deprecated factory function preserves source compatibility for
`ElicitRequestParams(message, requestedSchema)`.
- `RequestedSchema.properties` changed from `JsonObject` to `Map<String,
PrimitiveSchemaDefinition>`.
- `ElicitRequest.requestedSchema` is deprecated, use `(params as
ElicitRequestFormParams).requestedSchema`.

## Types of changes
- [ ] Bug fix (non-breaking change which fixes an issue)
- [x] New feature (non-breaking change which adds functionality)
- [x] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update

## Checklist
- [x] I have read the [MCP
Documentation](https://modelcontextprotocol.io)
- [x] My code follows the repository's style guidelines
- [x] New and existing tests pass locally
- [x] I have added appropriate error handling
- [x] I have added or updated documentation as needed

Author: devcrocod

conformance-test/run-conformance.sh

@@ -9,7 +9,7 @@ set -uo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" || exit 1; pwd)"
 PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." || exit 1; pwd)"
 
-CONFORMANCE_VERSION="0.1.15"
+CONFORMANCE_VERSION="0.1.16"
 PORT="${MCP_PORT:-3001}"
 SERVER_URL="http://localhost:${PORT}/mcp"
 RESULTS_DIR="$SCRIPT_DIR/results"

conformance-test/src/main/kotlin/io/modelcontextprotocol/kotlin/sdk/conformance/ConformanceTools.kt

@@ -10,6 +10,7 @@ import io.modelcontextprotocol.kotlin.sdk.shared.TransportSendOptions
 import io.modelcontextprotocol.kotlin.sdk.types.ClientCapabilities
 import io.modelcontextprotocol.kotlin.sdk.types.CreateMessageRequest
 import io.modelcontextprotocol.kotlin.sdk.types.CreateMessageResult
+import io.modelcontextprotocol.kotlin.sdk.types.ElicitRequestFormParams
 import io.modelcontextprotocol.kotlin.sdk.types.ElicitRequestParams
 import io.modelcontextprotocol.kotlin.sdk.types.ElicitResult
 import io.modelcontextprotocol.kotlin.sdk.types.EmptyJsonObject
@@ -35,6 +36,7 @@ import io.modelcontextprotocol.kotlin.sdk.types.Root
 import io.modelcontextprotocol.kotlin.sdk.types.RootsListChangedNotification
 import io.modelcontextprotocol.kotlin.sdk.types.SUPPORTED_PROTOCOL_VERSIONS
 import io.modelcontextprotocol.kotlin.sdk.types.ServerCapabilities
+import io.modelcontextprotocol.kotlin.sdk.types.StringSchema
 import io.modelcontextprotocol.kotlin.sdk.types.TextContent
 import io.modelcontextprotocol.kotlin.sdk.types.Tool
 import io.modelcontextprotocol.kotlin.sdk.types.ToolSchema
@@ -48,7 +50,6 @@ import kotlinx.coroutines.test.runTest
 import kotlinx.coroutines.withTimeout
 import kotlinx.serialization.json.buildJsonObject
 import kotlinx.serialization.json.put
-import kotlinx.serialization.json.putJsonObject
 import kotlin.coroutines.cancellation.CancellationException
 import kotlin.test.Test
 import kotlin.test.assertEquals
@@ -953,11 +954,7 @@ class ClientTest {
             serverSession.createElicitation(
                 message = "Please provide your GitHub username",
                 requestedSchema = ElicitRequestParams.RequestedSchema(
-                    properties = buildJsonObject {
-                        putJsonObject("name") {
-                            put("type", "string")
-                        }
-                    },
+                    properties = mapOf("name" to StringSchema()),
                     required = listOf("name"),
                 ),
             )
@@ -1061,11 +1058,7 @@ class ClientTest {
 
         val elicitationMessage = "Please provide your GitHub username"
         val requestedSchema = ElicitRequestParams.RequestedSchema(
-            properties = buildJsonObject {
-                putJsonObject("name") {
-                    put("type", "string")
-                }
-            },
+            properties = mapOf("name" to StringSchema()),
             required = listOf("name"),
         )
 
@@ -1076,7 +1069,8 @@ class ClientTest {
 
         client.setElicitationHandler { request ->
             assertEquals(elicitationMessage, request.params.message)
-            assertEquals(requestedSchema, request.params.requestedSchema)
+            val formParams = request.params as ElicitRequestFormParams
+            assertEquals(requestedSchema, formParams.requestedSchema)
 
             ElicitResult(
                 action = elicitationResultAction,

integration-test/src/commonTest/kotlin/io/modelcontextprotocol/kotlin/sdk/client/ClientTest.kt

@@ -4,6 +4,7 @@ import io.modelcontextprotocol.kotlin.sdk.ExperimentalMcpApi
 import kotlinx.serialization.json.JsonObject
 import kotlinx.serialization.json.JsonObjectBuilder
 import kotlinx.serialization.json.buildJsonObject
+import kotlinx.serialization.json.decodeFromJsonElement
 import kotlin.contracts.ExperimentalContracts
 import kotlin.contracts.InvocationKind
 import kotlin.contracts.contract
@@ -223,6 +224,9 @@ public class ElicitRequestedSchemaBuilder @PublishedApi internal constructor() {
         val properties = requireNotNull(properties) {
             "Missing required field 'properties'. Use properties { put(\"fieldName\", schema) }"
         }
-        return ElicitRequestParams.RequestedSchema(properties, required)
+        val typedProperties: Map<String, PrimitiveSchemaDefinition> = properties.mapValues { (_, value) ->
+            McpJson.decodeFromJsonElement<PrimitiveSchemaDefinition>(value)
+        }
+        return ElicitRequestParams.RequestedSchema(properties = typedProperties, required = required)
     }
 }

kotlin-sdk-core/api/kotlin-sdk-core.api

@@ -1,23 +1,20 @@
 package io.modelcontextprotocol.kotlin.sdk.types
 
 import kotlinx.serialization.EncodeDefault
-import kotlinx.serialization.ExperimentalSerializationApi
 import kotlinx.serialization.SerialName
 import kotlinx.serialization.Serializable
 import kotlinx.serialization.json.JsonObject
 
 /**
- * A request from the server to elicit additional information from the user via the client.
+ * Represents an `elicitation/create` request from the server to the client.
  *
- * This request type allows servers to prompt users for structured input through forms
- * or dialogs presented by the client. The server defines a schema for the requested data,
- * and the client presents an appropriate UI to collect this information.
+ * Supports two modes: form mode ([ElicitRequestFormParams]) for collecting structured data
+ * in-band, and URL mode ([ElicitRequestURLParams]) for directing the user to an external URL.
  *
- * @property params The elicitation parameters including the message and requested schema.
+ * @property params The elicitation parameters — either form or URL mode.
  */
 @Serializable
 public data class ElicitRequest(override val params: ElicitRequestParams) : ServerRequest {
-    @OptIn(ExperimentalSerializationApi::class)
     @EncodeDefault
     public override val method: Method = Method.Defined.ElicitationCreate
 
@@ -30,8 +27,13 @@ public data class ElicitRequest(override val params: ElicitRequestParams) : Serv
     /**
      * A restricted subset of JSON Schema defining the structure of the requested data.
      */
-    public val requestedSchema: ElicitRequestParams.RequestedSchema
-        get() = params.requestedSchema
+    @Deprecated(
+        "Use (params as ElicitRequestFormParams).requestedSchema",
+        ReplaceWith("(params as ElicitRequestFormParams).requestedSchema"),
+        DeprecationLevel.WARNING,
+    )
+    public val requestedSchema: ElicitRequestParams.RequestedSchema?
+        get() = (params as? ElicitRequestFormParams)?.requestedSchema
 
     /**
      * Metadata for this request. May include a progressToken for out-of-band progress notifications.
@@ -41,55 +43,124 @@ public data class ElicitRequest(override val params: ElicitRequestParams) : Serv
 }
 
 /**
- * Parameters for an elicitation/create request.
+ * Represents the parameters for an `elicitation/create` request.
  *
- * @property message The message to present to the user. This should clearly explain
- * what information is being requested and why.
- * @property requestedSchema A restricted subset of JSON Schema defining the structure
- * of the requested data. Only top-level properties are allowed,
- * without nesting.
- * @property meta Optional metadata for this request. May include a progressToken for
- * out-of-band progress notifications.
+ * Implementations: [ElicitRequestFormParams], [ElicitRequestURLParams].
  */
-@Serializable
-public data class ElicitRequestParams(
-    val message: String,
-    val requestedSchema: RequestedSchema,
-    @SerialName("_meta")
-    override val meta: RequestMeta? = null,
-) : RequestParams {
+@Serializable(with = ElicitRequestParamsSerializer::class)
+public sealed interface ElicitRequestParams : RequestParams {
+    public val message: String
 
     /**
      * A restricted JSON Schema for elicitation requests.
      *
      * Only supports top-level primitive properties without nesting. Each property
      * represents a field in the form or dialog presented to the user.
      *
+     * @property schema Optional URI to a JSON Schema definition.
      * @property properties A map of property names to their schema definitions.
      * Each property must be a primitive type (string, number, boolean).
      * @property required Optional list of property names that must be provided by the user.
      * If omitted, all fields are considered optional.
      * @property type Always "object" for elicitation schemas.
      */
     @Serializable
-    public data class RequestedSchema(val properties: JsonObject, val required: List<String>? = null) {
-        @OptIn(ExperimentalSerializationApi::class)
+    public data class RequestedSchema(
+        @SerialName($$"$schema")
+        val schema: String? = null,
+        val properties: Map<String, PrimitiveSchemaDefinition>,
+        val required: List<String>? = null,
+    ) {
         @EncodeDefault
         val type: String = "object"
     }
 }
 
 /**
- * The client's response to an [ElicitRequest].
+ * Creates an [ElicitRequestFormParams] for backwards compatibility.
+ *
+ * @param message The message to present to the user.
+ * @param requestedSchema The JSON Schema for the requested data.
+ * @param meta Optional request metadata.
+ * @return A configured [ElicitRequestFormParams] instance.
+ */
+@Deprecated(
+    "Use ElicitRequestFormParams instead",
+    ReplaceWith("ElicitRequestFormParams(message, requestedSchema = requestedSchema, meta = meta)"),
+    DeprecationLevel.WARNING,
+)
+@Suppress("FunctionNaming", "FunctionName")
+public fun ElicitRequestParams(
+    message: String,
+    requestedSchema: ElicitRequestParams.RequestedSchema,
+    meta: RequestMeta? = null,
+): ElicitRequestFormParams = ElicitRequestFormParams(
+    message = message,
+    requestedSchema = requestedSchema,
+    meta = meta,
+)
+
+/**
+ * Represents form mode parameters for an `elicitation/create` request.
+ *
+ * Collects non-sensitive structured data from the user via a form presented by the client.
  *
- * Represents the user's action and, if accepted, the submitted form data.
+ * @property message The message to present to the user describing what information is being requested.
+ * @property task If specified, the caller is requesting task-augmented execution. The request
+ *   will return a [CreateTaskResult] immediately, and the actual result can be retrieved
+ *   later via `tasks/result`.
+ * @property requestedSchema A restricted subset of JSON Schema. Only top-level properties
+ *   are allowed, without nesting.
+ * @property meta Optional metadata. May include a progressToken for out-of-band progress notifications.
+ */
+@Serializable
+public data class ElicitRequestFormParams(
+    override val message: String,
+    val task: TaskMetadata? = null,
+    val requestedSchema: ElicitRequestParams.RequestedSchema,
+    @SerialName("_meta")
+    override val meta: RequestMeta? = null,
+) : ElicitRequestParams {
+    @EncodeDefault
+    public val mode: String = "form"
+}
+
+/**
+ * Represents URL mode parameters for an `elicitation/create` request.
+ *
+ * Directs the user to an external URL for out-of-band interactions (e.g., OAuth flows,
+ * payment processing, or entering sensitive credentials) that must not pass through the MCP client.
+ *
+ * @property message The message explaining why the interaction is needed.
+ * @property elicitationId A unique identifier for this elicitation. The client MUST treat
+ *   this ID as an opaque value.
+ * @property url The URL that the user should navigate to.
+ * @property task If specified, the caller is requesting task-augmented execution. The request
+ *   will return a [CreateTaskResult] immediately, and the actual result can be retrieved
+ *   later via `tasks/result`.
+ * @property meta Optional metadata. May include a progressToken for out-of-band progress notifications.
+ */
+@Serializable
+public data class ElicitRequestURLParams(
+    override val message: String,
+    val elicitationId: String,
+    val url: String,
+    val task: TaskMetadata? = null,
+    @SerialName("_meta")
+    override val meta: RequestMeta? = null,
+) : ElicitRequestParams {
+    @EncodeDefault
+    public val mode: String = "url"
+}
+
+/**
+ * Represents the client's response to an [ElicitRequest].
  *
- * @property action The user action in response to the elicitation prompt.
- * @property content The submitted form data, only present when [action] is [Action.Accept].
- * Contains values matching the requested schema, where keys correspond
- * to property names and values are primitives (string, number, or boolean).
+ * @property action The user action in response to the elicitation.
+ * @property content The submitted form data, only present when [action] is [Action.Accept]
+ *   and mode was form. Contains values matching the requested schema. Omitted for
+ *   URL mode responses.
  * @property meta Optional metadata for this response.
- * @throws IllegalArgumentException if content is provided with a non-accept action.
  */
 @Serializable
 public data class ElicitResult(