Default draft protocol support: sessionless + handshake-less (SEP-2575 + SEP-2567) (#1610)

src/ModelContextProtocol.Core/Protocol/DiscoverRequestParams.cs

@@ -0,0 +1,16 @@
+namespace ModelContextProtocol.Protocol;
+
+/// <summary>
+/// Represents the parameters used with a <see cref="RequestMethods.ServerDiscover"/> request.
+/// </summary>
+/// <remarks>
+/// <para>
+/// The discover RPC takes no payload of its own. Per-request metadata
+/// (protocol version, client info, client capabilities) flows through the
+/// inherited <see cref="RequestParams.Meta"/> property under the
+/// <c>io.modelcontextprotocol/*</c> keys defined by the draft protocol revision (SEP-2575).
+/// </para>
+/// </remarks>
+public sealed class DiscoverRequestParams : RequestParams
+{
+}

src/ModelContextProtocol.Core/Protocol/DiscoverResult.cs

@@ -0,0 +1,67 @@
+using System.Text.Json.Serialization;
+
+namespace ModelContextProtocol.Protocol;
+
+/// <summary>
+/// Represents the result returned from a <see cref="RequestMethods.ServerDiscover"/> request.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Introduced by the draft protocol revision (SEP-2575) as the canonical way for a client
+/// to learn what a server supports without performing the legacy <c>initialize</c> handshake.
+/// </para>
+/// </remarks>
+public sealed class DiscoverResult : Result, ICacheableResult
+{
+    /// <summary>
+    /// Gets or sets the list of MCP protocol version strings that the server supports.
+    /// </summary>
+    /// <remarks>
+    /// The client should choose a version from this list for use in subsequent requests.
+    /// </remarks>
+    [JsonPropertyName("supportedVersions")]
+    public required IList<string> SupportedVersions { get; set; }
+
+    /// <summary>
+    /// Gets or sets the capabilities of the server.
+    /// </summary>
+    [JsonPropertyName("capabilities")]
+    public required ServerCapabilities Capabilities { get; set; }
+
+    /// <summary>
+    /// Gets or sets information about the server implementation.
+    /// </summary>
+    [JsonPropertyName("serverInfo")]
+    public required Implementation ServerInfo { get; set; }
+
+    /// <summary>
+    /// Gets or sets optional instructions describing how to use the server and its features.
+    /// </summary>
+    /// <remarks>
+    /// This can be used by clients to improve an LLM's understanding of the server,
+    /// for example by including it in a system prompt.
+    /// </remarks>
+    [JsonPropertyName("instructions")]
+    public string? Instructions { get; set; }
+
+    /// <inheritdoc />
+    /// <remarks>
+    /// Spec PR #2855 makes <c>ttlMs</c> a required field on <see cref="DiscoverResult"/>. The
+    /// server emits a safe default (<see cref="TimeSpan.Zero"/>, i.e. immediately stale) on
+    /// draft sessions when the application has not set an explicit value, preserving today's
+    /// "do not cache" behavior while satisfying the wire requirement.
+    /// </remarks>
+    [JsonPropertyName("ttlMs")]
+    [JsonConverter(typeof(TimeSpanMillisecondsConverter))]
+    public TimeSpan? TimeToLive { get; set; }
+
+    /// <inheritdoc />
+    /// <remarks>
+    /// Spec PR #2855 makes <c>cacheScope</c> a required field on <see cref="DiscoverResult"/>. The
+    /// server emits a safe default (<see cref="Protocol.CacheScope.Private"/>) on draft sessions
+    /// when the application has not set an explicit value.
+    /// </remarks>
+    [JsonPropertyName("cacheScope")]
+    [JsonConverter(typeof(CacheScopeConverter))]
+    public CacheScope? CacheScope { get; set; }
+}

src/ModelContextProtocol.Core/Protocol/ICacheableResult.cs

@@ -7,8 +7,9 @@ namespace ModelContextProtocol.Protocol;
 /// <remarks>
 /// <para>
 /// This interface corresponds to the <c>CacheableResult</c> type in the Model Context Protocol
-/// schema and is implemented by the results of <c>tools/list</c>, <c>prompts/list</c>,
-/// <c>resources/list</c>, <c>resources/templates/list</c>, and <c>resources/read</c>.
+/// schema and is implemented by the results of <c>server/discover</c>, <c>tools/list</c>,
+/// <c>prompts/list</c>, <c>resources/list</c>, <c>resources/templates/list</c>, and
+/// <c>resources/read</c>.
 /// </para>
 /// <para>
 /// The TTL is a freshness hint, not a guarantee. It supplements rather than replaces the existing

src/ModelContextProtocol.Core/Protocol/JsonRpcMessage.cs

@@ -83,6 +83,7 @@ public abstract class JsonRpcMessage
             // Local variables for parsed message data
             bool hasJsonRpc = false;
             RequestId id = default;
+            bool hasId = false;
             string? method = null;
             JsonNode? parameters = null;
             JsonRpcErrorDetail? error = null;
@@ -118,6 +119,7 @@ public abstract class JsonRpcMessage
 
                     case "id":
                         id = JsonSerializer.Deserialize(ref reader, options.GetTypeInfo<RequestId>());
+                        hasId = true;
                         break;
 
                     case "method":
@@ -153,6 +155,16 @@ public abstract class JsonRpcMessage
             // Determine message type based on presence of id and method properties
             if (method is not null)
             {
+                if (hasId && id.Id is null)
+                {
+                    // A request that carries an explicit `id: null` is malformed. The MCP base protocol
+                    // states "Unlike base JSON-RPC, the ID MUST NOT be null", and a null id does NOT denote
+                    // a notification — per JSON-RPC 2.0 a Notification is a Request object *without* an id
+                    // member. Reject it rather than silently downgrading to a notification (which would
+                    // drop the malformed id and skip sending any response).
+                    throw new JsonException("Request id must not be null. Per MCP, a request id must be a non-null string or number; omit the id member entirely to send a notification.");
+                }
+
                 if (id.Id is not null)
                 {
                     // Messages with both method and id are requests
@@ -165,7 +177,7 @@ public abstract class JsonRpcMessage
                 }
                 else
                 {
-                    // Messages with a method but no id are notifications
+                    // Messages with a method but no id member are notifications
                     return new JsonRpcNotification
                     {
                         Method = method,
@@ -200,6 +212,19 @@ public abstract class JsonRpcMessage
                 throw new JsonException("Response must have either result or error");
             }
 
+            if (error is not null)
+            {
+                // Per JSON-RPC 2.0, when an error occurs before the request id can be determined
+                // (e.g. parse error or invalid request), the server MUST respond with id=null.
+                // Accept null-id error responses so callers can recognize the structured signal
+                // (e.g. an HTTP 400 body whose JSON-RPC envelope carries a non-modern error code).
+                return new JsonRpcError
+                {
+                    Id = id,
+                    Error = error
+                };
+            }
+
             // Error: Messages with neither id nor method are invalid
             throw new JsonException("Invalid JSON-RPC message format");
         }

src/ModelContextProtocol.Core/Protocol/JsonRpcMessageContext.cs

@@ -85,4 +85,35 @@ public sealed class JsonRpcMessageContext
     /// to flow the protocol version header so the server can determine client capabilities.
     /// </remarks>
     public string? ProtocolVersion { get; set; }
+
+    /// <summary>
+    /// Gets or sets the client info derived from the per-request
+    /// <c>_meta/io.modelcontextprotocol/clientInfo</c> field.
+    /// </summary>
+    /// <remarks>
+    /// Introduced by the draft protocol revision (SEP-2575). When the request was made under the draft revision,
+    /// the server uses this in lieu of the value previously captured during the <c>initialize</c> handshake.
+    /// </remarks>
+    public Implementation? ClientInfo { get; set; }
+
+    /// <summary>
+    /// Gets or sets the client capabilities derived from the per-request
+    /// <c>_meta/io.modelcontextprotocol/clientCapabilities</c> field.
+    /// </summary>
+    /// <remarks>
+    /// Introduced by the draft protocol revision (SEP-2575). Per the spec, the server MUST NOT infer client
+    /// capabilities from previous requests; the authoritative value is the one declared on each request.
+    /// </remarks>
+    public ClientCapabilities? ClientCapabilities { get; set; }
+
+    /// <summary>
+    /// Gets or sets the per-request log level derived from the
+    /// <c>_meta/io.modelcontextprotocol/logLevel</c> field.
+    /// </summary>
+    /// <remarks>
+    /// Introduced by the draft protocol revision (SEP-2575). Replaces the legacy
+    /// <see cref="RequestMethods.LoggingSetLevel"/> RPC. When absent, the server MUST NOT emit log notifications
+    /// for the request.
+    /// </remarks>
+    public LoggingLevel? LogLevel { get; set; }
 }

src/ModelContextProtocol.Core/Protocol/MetaKeys.cs

@@ -0,0 +1,76 @@
+namespace ModelContextProtocol.Protocol;
+
+/// <summary>
+/// Provides constants for well-known <c>_meta</c> field keys defined by the MCP protocol and its extensions.
+/// </summary>
+public static class MetaKeys
+{
+    /// <summary>
+    /// The metadata key used to carry the MCP protocol version in a request's <c>_meta</c> field.
+    /// </summary>
+    /// <remarks>
+    /// Introduced by the draft protocol revision (SEP-2575). For HTTP transports, the value MUST
+    /// match the <c>MCP-Protocol-Version</c> header. Servers reject mismatched versions with
+    /// <see cref="McpErrorCode.UnsupportedProtocolVersion"/>.
+    /// </remarks>
+    public const string ProtocolVersion = "io.modelcontextprotocol/protocolVersion";
+
+    /// <summary>
+    /// The metadata key used to identify the client software in a request's <c>_meta</c> field.
+    /// </summary>
+    /// <remarks>
+    /// Introduced by the draft protocol revision (SEP-2575). Carries an <see cref="Protocol.Implementation"/>
+    /// describing the client; replaces the <c>clientInfo</c> previously sent only with <c>initialize</c>.
+    /// </remarks>
+    public const string ClientInfo = "io.modelcontextprotocol/clientInfo";
+
+    /// <summary>
+    /// The metadata key used to declare client capabilities in a request's <c>_meta</c> field.
+    /// </summary>
+    /// <remarks>
+    /// Introduced by the draft protocol revision (SEP-2575). Carries a <see cref="Protocol.ClientCapabilities"/>
+    /// describing what optional features the client supports for this specific request. Servers MUST NOT
+    /// infer capabilities from previous requests.
+    /// </remarks>
+    public const string ClientCapabilities = "io.modelcontextprotocol/clientCapabilities";
+
+    /// <summary>
+    /// The metadata key used to specify the desired log level for a request's resulting log notifications.
+    /// </summary>
+    /// <remarks>
+    /// Introduced by the draft protocol revision (SEP-2575). Carries a <see cref="Protocol.LoggingLevel"/>.
+    /// Replaces the legacy <see cref="RequestMethods.LoggingSetLevel"/> RPC. When absent, the server
+    /// MUST NOT send log notifications for the request.
+    /// </remarks>
+    public const string LogLevel = "io.modelcontextprotocol/logLevel";
+
+    /// <summary>
+    /// The metadata key used to associate a notification with the request ID of an active
+    /// <see cref="RequestMethods.SubscriptionsListen"/> subscription.
+    /// </summary>
+    /// <remarks>
+    /// Introduced by the draft protocol revision (SEP-2575). Allows clients to demultiplex notifications
+    /// belonging to different subscriptions on a shared channel (especially STDIO).
+    /// </remarks>
+    public const string SubscriptionId = "io.modelcontextprotocol/subscriptionId";
+
+    /// <summary>
+    /// The metadata key used to associate requests, responses, and notifications with a task.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This constant defines the key <c>"io.modelcontextprotocol/related-task"</c> used in the
+    /// <c>_meta</c> field to associate messages with their originating task across the entire
+    /// request lifecycle.
+    /// </para>
+    /// <para>
+    /// For example, an elicitation that a task-augmented tool call depends on must share the
+    /// same related task ID with that tool call's task.
+    /// </para>
+    /// <para>
+    /// For <c>tasks/get</c>, <c>tasks/list</c>, and <c>tasks/cancel</c> operations, this
+    /// metadata should not be included as the taskId is already present in the message structure.
+    /// </para>
+    /// </remarks>
+    public const string RelatedTask = "io.modelcontextprotocol/related-task";
+}

src/ModelContextProtocol.Core/Protocol/MissingRequiredClientCapabilityErrorData.cs

@@ -0,0 +1,21 @@
+using System.Text.Json.Serialization;
+
+namespace ModelContextProtocol.Protocol;
+
+/// <summary>
+/// Represents the payload for the <see cref="McpErrorCode.MissingRequiredClientCapability"/> JSON-RPC error.
+/// </summary>
+/// <remarks>
+/// Introduced by the draft protocol revision (SEP-2575). When a server cannot fulfill a request because
+/// the client did not declare a required capability in its per-request
+/// <c>_meta/io.modelcontextprotocol/clientCapabilities</c> field, it MUST return this error so clients
+/// know which capabilities to advertise on a retry.
+/// </remarks>
+public sealed class MissingRequiredClientCapabilityErrorData
+{
+    /// <summary>
+    /// Gets or sets the client capabilities the server requires to process the request.
+    /// </summary>
+    [JsonPropertyName("requiredCapabilities")]
+    public required ClientCapabilities RequiredCapabilities { get; set; }
+}

src/ModelContextProtocol.Core/Protocol/NotificationMethods.cs

@@ -152,5 +152,15 @@ public static class NotificationMethods
     /// Each notification carries a complete task state for the current status, identical to what
     /// <c>tasks/get</c> would have returned at that moment.
     /// </remarks>
-    public const string TaskStatusNotification = "notifications/tasks";
+    public const string TaskStatusNotification = "notifications/tasks/status";
+
+    /// <summary>
+    /// The name of the notification sent first on a <see cref="RequestMethods.SubscriptionsListen"/>
+    /// response stream to indicate which notification types the server agreed to deliver.
+    /// </summary>
+    /// <remarks>
+    /// Introduced by the draft protocol revision (SEP-2575). The notification's params mirror the shape
+    /// of the requested notifications and include only the entries the server actually supports.
+    /// </remarks>
+    public const string SubscriptionsAcknowledgedNotification = "notifications/subscriptions/acknowledged";
 }

src/ModelContextProtocol.Core/Protocol/RequestId.cs

@@ -66,7 +66,8 @@ public readonly struct RequestId : IEquatable<RequestId>
             {
                 JsonTokenType.String => new(reader.GetString()!),
                 JsonTokenType.Number => new(reader.GetInt64()),
-                _ => throw new JsonException("requestId must be a string or an integer"),
+                JsonTokenType.Null => default,
+                _ => throw new JsonException("requestId must be a string, integer, or null"),
             };
         }
 
@@ -86,7 +87,11 @@ public readonly struct RequestId : IEquatable<RequestId>
                     return;
 
                 case null:
-                    writer.WriteStringValue(string.Empty);
+                    // A null Id represents a JSON-RPC error response whose request id could not be
+                    // determined (JSON-RPC 2.0 §5; the MCP base protocol permits an error response to a
+                    // malformed request to carry a null id). Emit JSON null — not "" — so the wire form
+                    // is spec-conformant and round-trips losslessly with the Null-accepting Read above.
+                    writer.WriteNullValue();
                     return;
             }
         }

src/ModelContextProtocol.Core/Protocol/RequestMethods.cs

@@ -151,4 +151,42 @@ public static class RequestMethods
     /// Cancellation is cooperative — the server decides whether and when to honor it.
     /// </remarks>
     public const string TasksCancel = "tasks/cancel";
+
+    /// <summary>
+    /// The name of the request method sent from the client to discover the server's protocol versions,
+    /// capabilities, and metadata.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This RPC is introduced in the draft protocol revision (SEP-2575) as the canonical way for a client
+    /// to learn what a server supports without performing the legacy <c>initialize</c> handshake.
+    /// </para>
+    /// <para>
+    /// The server's response includes its supported protocol versions, capabilities, implementation
+    /// information, and optional usage instructions.
+    /// </para>
+    /// <para>
+    /// Servers SHOULD implement this method. Legacy clients MAY ignore it. Draft-revision clients
+    /// typically call this once during connection establishment.
+    /// </para>
+    /// </remarks>
+    public const string ServerDiscover = "server/discover";
+
+    /// <summary>
+    /// The name of the request method sent from the client to open a long-lived subscription for
+    /// receiving server-to-client notifications outside of a specific request's response stream.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This RPC is introduced in the draft protocol revision (SEP-2575) and replaces the unsolicited
+    /// HTTP GET endpoint and the legacy <see cref="ResourcesSubscribe"/> / <see cref="ResourcesUnsubscribe"/>
+    /// request methods.
+    /// </para>
+    /// <para>
+    /// The request opens a response stream on which the server first sends a
+    /// <see cref="NotificationMethods.SubscriptionsAcknowledgedNotification"/> describing the granted
+    /// notifications, and then streams matching notifications until the subscription is cancelled.
+    /// </para>
+    /// </remarks>
+    public const string SubscriptionsListen = "subscriptions/listen";
 }

src/ModelContextProtocol.Core/Protocol/SubscriptionsAcknowledgedNotificationParams.cs

@@ -0,0 +1,27 @@
+using System.Text.Json.Serialization;
+
+namespace ModelContextProtocol.Protocol;
+
+/// <summary>
+/// Represents the parameters sent with a <see cref="NotificationMethods.SubscriptionsAcknowledgedNotification"/>.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Introduced by the draft protocol revision (SEP-2575). This notification is the first message on a
+/// <see cref="RequestMethods.SubscriptionsListen"/> response stream and informs the client which
+/// subset of requested notification types the server has agreed to deliver.
+/// </para>
+/// </remarks>
+public sealed class SubscriptionsAcknowledgedNotificationParams
+{
+    /// <summary>
+    /// Gets or sets the notification subscriptions the server has agreed to honor.
+    /// </summary>
+    /// <remarks>
+    /// Only includes notification types the server actually supports. If the client requested an
+    /// unsupported notification type (e.g., <c>promptsListChanged</c> when the server has no prompts),
+    /// it is omitted from this set.
+    /// </remarks>
+    [JsonPropertyName("notifications")]
+    public required SubscriptionsListenNotifications Notifications { get; set; }
+}

src/ModelContextProtocol.Core/Protocol/SubscriptionsListenRequestParams.cs

@@ -0,0 +1,71 @@
+using System.Text.Json.Serialization;
+
+namespace ModelContextProtocol.Protocol;
+
+/// <summary>
+/// Represents the parameters used with a <see cref="RequestMethods.SubscriptionsListen"/> request.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Introduced by the draft protocol revision (SEP-2575). The client uses this request to open a
+/// long-lived channel for receiving notifications outside the context of a specific request.
+/// </para>
+/// <para>
+/// Per-request metadata (protocol version, client info, client capabilities, optional log level)
+/// flows through the inherited <see cref="RequestParams.Meta"/> property under the
+/// <c>io.modelcontextprotocol/*</c> keys.
+/// </para>
+/// </remarks>
+public sealed class SubscriptionsListenRequestParams : RequestParams
+{
+    /// <summary>
+    /// Gets or sets the notifications the client wants to receive on this subscription stream.
+    /// </summary>
+    /// <remarks>
+    /// Each notification type is opt-in; the server MUST NOT send notification types the client
+    /// has not explicitly requested here. The server's
+    /// <see cref="NotificationMethods.SubscriptionsAcknowledgedNotification"/> reports the subset
+    /// of requested notifications the server actually supports.
+    /// </remarks>
+    [JsonPropertyName("notifications")]
+    public required SubscriptionsListenNotifications Notifications { get; set; }
+}
+
+/// <summary>
+/// Describes the set of notification types a client wants to receive (or that a server has agreed
+/// to deliver) for a <see cref="RequestMethods.SubscriptionsListen"/> subscription.
+/// </summary>
+public sealed class SubscriptionsListenNotifications
+{
+    /// <summary>
+    /// Gets or sets a value indicating whether to receive
+    /// <see cref="NotificationMethods.ToolListChangedNotification"/> notifications.
+    /// </summary>
+    [JsonPropertyName("toolsListChanged")]
+    public bool? ToolsListChanged { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether to receive
+    /// <see cref="NotificationMethods.PromptListChangedNotification"/> notifications.
+    /// </summary>
+    [JsonPropertyName("promptsListChanged")]
+    public bool? PromptsListChanged { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether to receive
+    /// <see cref="NotificationMethods.ResourceListChangedNotification"/> notifications.
+    /// </summary>
+    [JsonPropertyName("resourcesListChanged")]
+    public bool? ResourcesListChanged { get; set; }
+
+    /// <summary>
+    /// Gets or sets the list of resource URIs to subscribe to for
+    /// <see cref="NotificationMethods.ResourceUpdatedNotification"/> notifications.
+    /// </summary>
+    /// <remarks>
+    /// Replaces the legacy <see cref="RequestMethods.ResourcesSubscribe"/> /
+    /// <see cref="RequestMethods.ResourcesUnsubscribe"/> RPCs from prior protocol revisions.
+    /// </remarks>
+    [JsonPropertyName("resourceSubscriptions")]
+    public IList<string>? ResourceSubscriptions { get; set; }
+}

src/ModelContextProtocol.Core/Protocol/UnsupportedProtocolVersionErrorData.cs

@@ -0,0 +1,26 @@
+using System.Text.Json.Serialization;
+
+namespace ModelContextProtocol.Protocol;
+
+/// <summary>
+/// Represents the payload for the <see cref="McpErrorCode.UnsupportedProtocolVersion"/> JSON-RPC error.
+/// </summary>
+/// <remarks>
+/// Introduced by the draft protocol revision (SEP-2575). When a server receives a request whose
+/// declared protocol version it does not implement, it MUST return this error so clients can
+/// fall back to a mutually supported version.
+/// </remarks>
+public sealed class UnsupportedProtocolVersionErrorData
+{
+    /// <summary>
+    /// Gets or sets the protocol version strings that the server supports.
+    /// </summary>
+    [JsonPropertyName("supported")]
+    public required IList<string> Supported { get; set; }
+
+    /// <summary>
+    /// Gets or sets the protocol version requested by the client.
+    /// </summary>
+    [JsonPropertyName("requested")]
+    public required string Requested { get; set; }
+}