Tighten draft protocol negotiation boundaries (#1692)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Co-authored-by: Tarek Mahmoud Sayed <tarekms@ntdev.microsoft.com>
This commit is contained in:
Stephen Halter
GitHub
parent
a8d374b280
commit
fd38f51e27
13 changed files with 1755 additions and 589 deletions
|
|
@ -294,24 +294,20 @@ internal sealed partial class McpClientImpl : McpClient
|
|||
// handshake. Instead, the client calls server/discover to learn the server's
|
||||
// capabilities and then begins sending normal RPCs that carry protocolVersion /
|
||||
// clientInfo / clientCapabilities in their per-request _meta. A null ProtocolVersion
|
||||
// prefers the 2026-07-28 revision and automatically falls back to the legacy initialize
|
||||
// handshake when the server doesn't support it. The legacy branch below runs only when
|
||||
// prefers the 2026-07-28 revision and automatically falls back to the initialize
|
||||
// handshake when the server doesn't support it. The initialize branch below runs only when
|
||||
// the caller explicitly pins a version that still supports Streamable HTTP sessions (opting out of the default).
|
||||
if (_options.ProtocolVersion is null || McpHttpHeaders.IsJuly2026OrLaterProtocolVersion(_options.ProtocolVersion))
|
||||
if (_options.ProtocolVersion is null || McpProtocolVersions.RequiresPerRequestMetadata(_options.ProtocolVersion))
|
||||
{
|
||||
string preferredVersion = _options.ProtocolVersion ?? McpHttpHeaders.July2026ProtocolVersion;
|
||||
|
||||
// Eagerly set the negotiated version so InjectRequestMetaIfNeeded recognizes us as being
|
||||
// on the 2026-07-28 revision when SendRequestAsync is invoked for server/discover.
|
||||
_negotiatedProtocolVersion = preferredVersion;
|
||||
_sessionHandler.NegotiatedProtocolVersion = preferredVersion;
|
||||
string preferredVersion = _options.ProtocolVersion ?? McpProtocolVersions.July2026ProtocolVersion;
|
||||
|
||||
DiscoverResult? discoverResult = null;
|
||||
bool fallbackToLegacy = false;
|
||||
bool fallbackToInitialize = false;
|
||||
IList<string>? serverSupportedVersions = null;
|
||||
string discoverVersion = preferredVersion;
|
||||
|
||||
// Apply a probe timeout so dual-era clients don't block forever waiting for a
|
||||
// legacy server that silently drops unknown methods (per stdio.mdx fallback rules).
|
||||
// Apply a probe timeout so dual-path clients don't block forever waiting for an
|
||||
// initialize-handshake server that silently drops unknown methods (per stdio.mdx fallback rules).
|
||||
// The probe timeout is configurable via McpClientOptions.DiscoverProbeTimeout and is
|
||||
// always bounded by InitializationTimeout (only applied when it is the tighter bound).
|
||||
var probeTimeout = _options.DiscoverProbeTimeout;
|
||||
|
|
@ -323,75 +319,101 @@ internal sealed partial class McpClientImpl : McpClient
|
|||
|
||||
try
|
||||
{
|
||||
discoverResult = await SendRequestAsync(
|
||||
RequestMethods.ServerDiscover,
|
||||
new DiscoverRequestParams(),
|
||||
McpJsonUtilities.JsonContext.Default.DiscoverRequestParams,
|
||||
McpJsonUtilities.JsonContext.Default.DiscoverResult,
|
||||
cancellationToken: probeCts.Token).ConfigureAwait(false);
|
||||
discoverResult = await SendDiscoverAsync(discoverVersion, probeCts.Token).ConfigureAwait(false);
|
||||
}
|
||||
catch (UnsupportedProtocolVersionException ex)
|
||||
{
|
||||
// Spec-recognized modern-server signal: -32022 with data.supported[]. The server is
|
||||
// modern but doesn't speak our preferred version. Retry with a mutually supported
|
||||
// version from data.supported[] instead of falling back to legacy initialize.
|
||||
fallbackToLegacy = true;
|
||||
// Spec-recognized SEP-2575 signal: -32022 with data.supported[]. The server is
|
||||
// refusing our preferred version. Retry with a supported per-request metadata
|
||||
// version if one exists; otherwise fall back to initialize with the highest
|
||||
// mutually supported initialize-capable version.
|
||||
serverSupportedVersions = (IList<string>)ex.Supported;
|
||||
var retryVersion = serverSupportedVersions
|
||||
.Where(McpProtocolVersions.PerRequestMetadataProtocolVersions.Contains)
|
||||
.OrderByDescending(v => v, StringComparer.Ordinal)
|
||||
.FirstOrDefault();
|
||||
|
||||
if (retryVersion is not null)
|
||||
{
|
||||
if (_options.ProtocolVersion is { } pinnedVersion &&
|
||||
StringComparer.Ordinal.Compare(retryVersion, pinnedVersion) < 0)
|
||||
{
|
||||
throw new McpException(
|
||||
$"The server does not support the requested protocol version '{pinnedVersion}'. " +
|
||||
"Leave McpClientOptions.ProtocolVersion unset to allow automatic fallback to an older version. " +
|
||||
$"Server-supported versions: {string.Join(", ", serverSupportedVersions)}.");
|
||||
}
|
||||
|
||||
discoverVersion = retryVersion;
|
||||
discoverResult = await SendDiscoverAsync(discoverVersion, probeCts.Token).ConfigureAwait(false);
|
||||
}
|
||||
else
|
||||
{
|
||||
fallbackToInitialize = true;
|
||||
}
|
||||
}
|
||||
catch (MissingRequiredClientCapabilityException)
|
||||
{
|
||||
// Spec-recognized modern-server signal: -32021. The server is modern but rejected
|
||||
// Spec-recognized SEP-2575 signal: -32021. The server rejected
|
||||
// our capability set. Surface as-is (no fallback): the user must add capabilities.
|
||||
throw;
|
||||
}
|
||||
catch (McpProtocolException ex) when (ex.ErrorCode == McpErrorCode.HeaderMismatch)
|
||||
{
|
||||
// Spec-recognized modern-server signal: -32020. The server is modern but rejected
|
||||
// Spec-recognized SEP-2575 signal: -32020. The server rejected
|
||||
// our request envelope (e.g., the MCP-Protocol-Version HTTP header didn't match
|
||||
// the body _meta.io.modelcontextprotocol/protocolVersion). Surface as-is (no
|
||||
// fallback): falling back to legacy initialize wouldn't fix a malformed envelope.
|
||||
// fallback): falling back to initialize wouldn't fix a malformed envelope.
|
||||
throw;
|
||||
}
|
||||
catch (McpProtocolException ex) when (
|
||||
ex.ErrorCode == McpErrorCode.InvalidRequest &&
|
||||
ex.Message.Contains(McpHttpHeaders.SessionId, StringComparison.Ordinal))
|
||||
{
|
||||
// Local transport validation: a 2026-07-28+ response must not carry HTTP session state.
|
||||
// This is not evidence of an initialize-handshake server, so do not fall back.
|
||||
throw;
|
||||
}
|
||||
catch (McpProtocolException)
|
||||
{
|
||||
// Per spec PR #2844, the fallback MUST NOT be keyed to a single error code.
|
||||
// Any non-modern JSON-RPC error from the probe indicates a legacy server.
|
||||
// Any non-SEP-2575 JSON-RPC error from the probe indicates an initialize-handshake server.
|
||||
// Common causes include MethodNotFound from a server that has no
|
||||
// server/discover handler, InvalidParams from a server confused by the
|
||||
// SEP-2575 _meta envelope, ParseError from a server that can't handle our
|
||||
// payload shape, or any other transport-defined error. The three modern-server
|
||||
// payload shape, or any other transport-defined error. The three SEP-2575
|
||||
// signals (-32022 UnsupportedProtocolVersion, -32021
|
||||
// MissingRequiredClientCapability, -32020 HeaderMismatch) are caught above and
|
||||
// never reach here.
|
||||
fallbackToLegacy = true;
|
||||
fallbackToInitialize = true;
|
||||
}
|
||||
catch (OperationCanceledException) when (probeCts.IsCancellationRequested && !initializationCts.IsCancellationRequested)
|
||||
{
|
||||
// Probe timeout elapsed without a response. Per stdio.mdx fallback rules, no
|
||||
// response within a reasonable timeout means the server is legacy. Fall back.
|
||||
fallbackToLegacy = true;
|
||||
// response within a reasonable timeout means the server requires initialize. Fall back.
|
||||
fallbackToInitialize = true;
|
||||
}
|
||||
|
||||
if (discoverResult is not null && !discoverResult.SupportedVersions.Contains(preferredVersion))
|
||||
if (discoverResult is not null && !discoverResult.SupportedVersions.Contains(discoverVersion))
|
||||
{
|
||||
// Server is reachable and supports server/discover, but doesn't support the
|
||||
// 2026-07-28 version. Fall back to legacy initialize with the highest
|
||||
// mutually-supported version from supportedVersions[].
|
||||
fallbackToLegacy = true;
|
||||
// version we are using. Fall back to initialize with the highest
|
||||
// mutually-supported initialize-capable version from supportedVersions[].
|
||||
fallbackToInitialize = true;
|
||||
serverSupportedVersions = discoverResult.SupportedVersions;
|
||||
}
|
||||
|
||||
if (fallbackToLegacy)
|
||||
if (fallbackToInitialize)
|
||||
{
|
||||
// Reset negotiated state and try legacy initialize.
|
||||
// Reset negotiated state and try initialize.
|
||||
_negotiatedProtocolVersion = null;
|
||||
_sessionHandler.NegotiatedProtocolVersion = null;
|
||||
|
||||
string fallbackVersion = serverSupportedVersions?
|
||||
.Where(McpSessionHandler.SupportedProtocolVersions.Contains)
|
||||
.Where(McpProtocolVersions.InitializeHandshakeProtocolVersions.Contains)
|
||||
.OrderByDescending(v => v, StringComparer.Ordinal)
|
||||
.FirstOrDefault()
|
||||
?? McpHttpHeaders.November2025ProtocolVersion;
|
||||
?? McpProtocolVersions.November2025ProtocolVersion;
|
||||
|
||||
// A non-null ProtocolVersion is also the minimum: refuse to fall back below the
|
||||
// explicitly requested version. String.Compare is the spec's prescribed ordering
|
||||
|
|
@ -403,11 +425,11 @@ internal sealed partial class McpClientImpl : McpClient
|
|||
$"The server does not support the requested protocol version '{pinnedVersion}'. " +
|
||||
"Leave McpClientOptions.ProtocolVersion unset to allow automatic fallback to an older version. " +
|
||||
(serverSupportedVersions is null
|
||||
? "The server appears to be a legacy server that requires the deprecated initialize handshake."
|
||||
? "The server appears to require the initialize handshake."
|
||||
: $"Server-supported versions: {string.Join(", ", serverSupportedVersions)}."));
|
||||
}
|
||||
|
||||
await PerformLegacyInitializeAsync(fallbackVersion, initializationCts.Token).ConfigureAwait(false);
|
||||
await PerformInitializeHandshakeAsync(fallbackVersion, initializationCts.Token).ConfigureAwait(false);
|
||||
}
|
||||
else
|
||||
{
|
||||
|
|
@ -422,14 +444,29 @@ internal sealed partial class McpClientImpl : McpClient
|
|||
_serverInfo = discoverResult.ServerInfo;
|
||||
_serverInstructions = discoverResult.Instructions;
|
||||
}
|
||||
|
||||
async Task<DiscoverResult> SendDiscoverAsync(string protocolVersion, CancellationToken cancellationToken)
|
||||
{
|
||||
// Eagerly set the negotiated version so InjectRequestMetaIfNeeded recognizes us as being
|
||||
// on a per-request metadata revision when SendRequestAsync is invoked for server/discover.
|
||||
_negotiatedProtocolVersion = protocolVersion;
|
||||
_sessionHandler.NegotiatedProtocolVersion = protocolVersion;
|
||||
|
||||
return await SendRequestAsync(
|
||||
RequestMethods.ServerDiscover,
|
||||
new DiscoverRequestParams(),
|
||||
McpJsonUtilities.JsonContext.Default.DiscoverRequestParams,
|
||||
McpJsonUtilities.JsonContext.Default.DiscoverResult,
|
||||
cancellationToken: cancellationToken).ConfigureAwait(false);
|
||||
}
|
||||
}
|
||||
else
|
||||
{
|
||||
// Legacy initialize handshake. Reached only when the caller explicitly pinned a
|
||||
// initialize handshake. Reached only when the caller explicitly pinned a
|
||||
// ProtocolVersion that still supports Streamable HTTP sessions (opting out of the default), so
|
||||
// _options.ProtocolVersion is non-null here.
|
||||
string requestProtocol = _options.ProtocolVersion ?? McpHttpHeaders.November2025ProtocolVersion;
|
||||
await PerformLegacyInitializeAsync(requestProtocol, initializationCts.Token).ConfigureAwait(false);
|
||||
string requestProtocol = _options.ProtocolVersion ?? McpProtocolVersions.November2025ProtocolVersion;
|
||||
await PerformInitializeHandshakeAsync(requestProtocol, initializationCts.Token).ConfigureAwait(false);
|
||||
}
|
||||
}
|
||||
catch (OperationCanceledException oce) when (initializationCts.IsCancellationRequested && !cancellationToken.IsCancellationRequested)
|
||||
|
|
@ -449,10 +486,10 @@ internal sealed partial class McpClientImpl : McpClient
|
|||
}
|
||||
|
||||
/// <summary>
|
||||
/// Performs the legacy initialize handshake (initialize request + initialized notification),
|
||||
/// Performs the initialize handshake (initialize request + initialized notification),
|
||||
/// records the negotiated protocol version, and stores the server capabilities/info/instructions.
|
||||
/// </summary>
|
||||
private async Task PerformLegacyInitializeAsync(string requestProtocol, CancellationToken cancellationToken)
|
||||
private async Task PerformInitializeHandshakeAsync(string requestProtocol, CancellationToken cancellationToken)
|
||||
{
|
||||
var initializeResponse = await SendRequestAsync(
|
||||
RequestMethods.Initialize,
|
||||
|
|
@ -479,18 +516,16 @@ internal sealed partial class McpClientImpl : McpClient
|
|||
_serverInstructions = initializeResponse.Instructions;
|
||||
|
||||
// When the user explicitly pinned a version that supports Streamable HTTP sessions, the server MUST respect it.
|
||||
// When the user pinned the 2026-07-28 version but we fell back (e.g., legacy server rejected
|
||||
// server/discover), or when no version was pinned, accept any supported response. This is the
|
||||
// spec-mandated behavior: a 2026-07-28 client must be able to downgrade to whatever
|
||||
// version the server advertises.
|
||||
// When no version was pinned, accept any supported initialize-handshake response. initialize cannot negotiate
|
||||
// the 2026-07-28 and later protocol revisions.
|
||||
bool isResponseProtocolValid;
|
||||
if (_options.ProtocolVersion is { } optionsProtocol && !McpHttpHeaders.IsJuly2026OrLaterProtocolVersion(optionsProtocol))
|
||||
if (_options.ProtocolVersion is { } optionsProtocol && !McpProtocolVersions.IsJuly2026OrLaterProtocolVersion(optionsProtocol))
|
||||
{
|
||||
isResponseProtocolValid = optionsProtocol == initializeResponse.ProtocolVersion;
|
||||
}
|
||||
else
|
||||
{
|
||||
isResponseProtocolValid = McpSessionHandler.SupportedProtocolVersions.Contains(initializeResponse.ProtocolVersion);
|
||||
isResponseProtocolValid = McpProtocolVersions.InitializeHandshakeProtocolVersions.Contains(initializeResponse.ProtocolVersion);
|
||||
}
|
||||
if (!isResponseProtocolValid)
|
||||
{
|
||||
|
|
@ -525,7 +560,7 @@ internal sealed partial class McpClientImpl : McpClient
|
|||
_serverInstructions = resumeOptions.ServerInstructions;
|
||||
_negotiatedProtocolVersion = resumeOptions.NegotiatedProtocolVersion
|
||||
?? _options.ProtocolVersion
|
||||
?? McpHttpHeaders.November2025ProtocolVersion;
|
||||
?? McpProtocolVersions.November2025ProtocolVersion;
|
||||
|
||||
// Update session handler with the negotiated protocol version for telemetry
|
||||
_sessionHandler.NegotiatedProtocolVersion = _negotiatedProtocolVersion;
|
||||
|
|
@ -691,7 +726,7 @@ internal sealed partial class McpClientImpl : McpClient
|
|||
/// <summary>
|
||||
/// Injects the 2026-07-28 protocol's per-request <c>_meta</c> fields (protocol version, client info,
|
||||
/// client capabilities) into the request when this client negotiated the 2026-07-28 or later revision
|
||||
/// (SEP-2575). No-op on a legacy session.
|
||||
/// (SEP-2575). No-op on an initialize-handshake session.
|
||||
/// </summary>
|
||||
private void InjectRequestMetaIfNeeded(JsonRpcRequest request)
|
||||
{
|
||||
|
|
|
|||
|
|
@ -52,16 +52,20 @@ public sealed class McpClientOptions
|
|||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// Supported values are <c>2024-11-05</c>, <c>2025-03-26</c>, <c>2025-06-18</c>, <c>2025-11-25</c>,
|
||||
/// and <c>2026-07-28</c>.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// When <see langword="null"/> (the default), the client prefers the latest revision (<c>2026-07-28</c>),
|
||||
/// which removed the <c>initialize</c> handshake and Streamable HTTP sessions. It probes with
|
||||
/// <c>server/discover</c> and automatically falls back to the legacy <c>initialize</c> handshake,
|
||||
/// downgrading to any version the server advertises, when the server does not support that revision.
|
||||
/// <c>server/discover</c> and automatically falls back to the <c>initialize</c> handshake,
|
||||
/// downgrading to an initialize-capable version the server advertises, when the server does not support that revision.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// When non-<see langword="null"/>, this value is both the requested version and the minimum the client
|
||||
/// will accept: the client requests exactly this version and refuses to downgrade below it, throwing an
|
||||
/// <see cref="McpException"/> instead of falling back. Setting it to <c>2026-07-28</c> therefore disables
|
||||
/// the automatic legacy-server fallback, and setting it to a version that still supports Streamable HTTP
|
||||
/// the automatic initialize-handshake server fallback, and setting it to a version that still supports Streamable HTTP
|
||||
/// sessions, such as <c>2025-11-25</c>, forces the <c>initialize</c> handshake and fails if the server
|
||||
/// negotiates a different version. To try more than one version, leave this unset for automatic fallback
|
||||
/// or retry the connection with a different value.
|
||||
|
|
@ -90,7 +94,7 @@ public sealed class McpClientOptions
|
|||
|
||||
/// <summary>
|
||||
/// Gets or sets the timeout applied to the <c>server/discover</c> probe that the client issues
|
||||
/// before falling back to the legacy <c>initialize</c> handshake.
|
||||
/// before falling back to the <c>initialize</c> handshake.
|
||||
/// </summary>
|
||||
/// <value>
|
||||
/// The probe timeout. The default value is 5 seconds. Use
|
||||
|
|
@ -102,17 +106,17 @@ public sealed class McpClientOptions
|
|||
/// This timeout only has an effect when the client prefers the <c>2026-07-28</c> protocol revision, that is,
|
||||
/// when <see cref="ProtocolVersion"/> is <see langword="null"/> (the default) or <c>2026-07-28</c>.
|
||||
/// In that mode the client first probes the server with a
|
||||
/// <c>server/discover</c> request. A legacy server that predates the <c>2026-07-28</c> revision may
|
||||
/// <c>server/discover</c> request. A server that predates the <c>2026-07-28</c> revision may
|
||||
/// silently drop the unknown method, so the probe is bounded by this timeout; when it elapses the
|
||||
/// client concludes the server is legacy and falls back to the <c>initialize</c> handshake on the
|
||||
/// same connection. When the caller pins a legacy <see cref="ProtocolVersion"/>, no probe is issued
|
||||
/// client concludes the server requires <c>initialize</c> and falls back to that handshake on the
|
||||
/// same connection. When the caller pins an initialize-capable <see cref="ProtocolVersion"/>, no probe is issued
|
||||
/// and this value has no effect.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// The default is intentionally short so that dual-era clients fall back quickly against legacy
|
||||
/// The default is intentionally short so that dual-path clients fall back quickly against initialize-handshake
|
||||
/// servers. Increase it for high-latency environments (for example, cold-start serverless peers or
|
||||
/// satellite links) where a short probe could trigger the legacy fallback before a server on the new revision
|
||||
/// server has had a chance to respond. The probe is always also bounded by
|
||||
/// satellite links) where a short probe could trigger the initialize fallback before a server on the
|
||||
/// per-request metadata revision has had a chance to respond. The probe is always also bounded by
|
||||
/// <see cref="InitializationTimeout"/>, which governs the overall connect budget: if this value is
|
||||
/// greater than or equal to <see cref="InitializationTimeout"/>, the probe is effectively bounded by
|
||||
/// <see cref="InitializationTimeout"/> alone.
|
||||
|
|
|
|||
|
|
@ -67,19 +67,19 @@ internal sealed partial class StreamableHttpClientSessionTransport : TransportBa
|
|||
// Per spec PR #2844 (HTTP backwards compatibility), a 400 Bad Request that carries a
|
||||
// JSON-RPC error envelope means the peer is signalling something application-level about
|
||||
// our request. Surface ANY JSON-RPC error on a 400 as McpProtocolException so the
|
||||
// connect-time logic can react. For example, the three modern protocol error codes
|
||||
// connect-time logic can react. For example, the three per-request metadata protocol error codes
|
||||
// (-32022 UnsupportedProtocolVersion, -32021 MissingRequiredClientCapability,
|
||||
// -32020 HeaderMismatch) lead to typed exceptions, while other codes (e.g. -32600 from
|
||||
// legacy servers that don't understand the SEP-2575 _meta envelope) become generic
|
||||
// McpProtocolException instances and trigger the fallback-to-legacy-initialize path.
|
||||
// initialize-handshake servers that don't understand the SEP-2575 _meta envelope) become generic
|
||||
// McpProtocolException instances and trigger the initialize-handshake fallback path.
|
||||
// Other status codes (401 auth, 403 forbidden, 404 session-not-found, 5xx server) continue
|
||||
// to surface as HttpRequestException to preserve back-compat with transport-layer behaviors.
|
||||
// The three modern protocol error codes are also surfaced for non-400 status codes
|
||||
// The three per-request metadata protocol error codes are also surfaced for non-400 status codes
|
||||
// for robustness. Servers occasionally emit them with 4xx codes other than 400.
|
||||
if (!response.IsSuccessStatusCode &&
|
||||
await TryReadJsonRpcErrorAsync(response, cancellationToken).ConfigureAwait(false) is { } parsedError &&
|
||||
(response.StatusCode == HttpStatusCode.BadRequest ||
|
||||
IsModernProtocolErrorCode((McpErrorCode)parsedError.Error.Code)))
|
||||
IsPerRequestMetadataProtocolErrorCode((McpErrorCode)parsedError.Error.Code)))
|
||||
{
|
||||
throw McpSessionHandler.CreateRemoteProtocolExceptionFromError(parsedError);
|
||||
}
|
||||
|
|
@ -87,7 +87,7 @@ internal sealed partial class StreamableHttpClientSessionTransport : TransportBa
|
|||
await response.EnsureSuccessStatusCodeWithResponseBodyAsync(cancellationToken).ConfigureAwait(false);
|
||||
}
|
||||
|
||||
private static bool IsModernProtocolErrorCode(McpErrorCode code) =>
|
||||
private static bool IsPerRequestMetadataProtocolErrorCode(McpErrorCode code) =>
|
||||
code is McpErrorCode.UnsupportedProtocolVersion
|
||||
or McpErrorCode.MissingRequiredClientCapability
|
||||
or McpErrorCode.HeaderMismatch;
|
||||
|
|
@ -217,7 +217,7 @@ internal sealed partial class StreamableHttpClientSessionTransport : TransportBa
|
|||
if (rpcRequest.Method == RequestMethods.Initialize && rpcResponseOrError is JsonRpcResponse initResponse)
|
||||
{
|
||||
// We've successfully initialized! Copy session-id and protocol version, then start GET request if any.
|
||||
if (response.Headers.TryGetValues("Mcp-Session-Id", out var sessionIdValues))
|
||||
if (response.Headers.TryGetValues(McpHttpHeaders.SessionId, out var sessionIdValues))
|
||||
{
|
||||
SessionId = sessionIdValues.FirstOrDefault();
|
||||
}
|
||||
|
|
@ -528,7 +528,7 @@ internal sealed partial class StreamableHttpClientSessionTransport : TransportBa
|
|||
string? protocolVersion,
|
||||
string? lastEventId = null)
|
||||
{
|
||||
if (sessionId is not null)
|
||||
if (sessionId is not null && McpProtocolVersions.SupportsHttpSessions(protocolVersion))
|
||||
{
|
||||
headers.Add(McpHttpHeaders.SessionId, sessionId);
|
||||
}
|
||||
|
|
|
|||
|
|
@ -55,7 +55,7 @@ public abstract partial class McpSession : IAsyncDisposable
|
|||
/// definition of "is this peer speaking the 2026-07-28 or later revision" used by both the client and server.
|
||||
/// </remarks>
|
||||
internal bool IsJuly2026OrLaterProtocol() =>
|
||||
McpHttpHeaders.IsJuly2026OrLaterProtocolVersion(NegotiatedProtocolVersion);
|
||||
McpProtocolVersions.IsJuly2026OrLaterProtocolVersion(NegotiatedProtocolVersion);
|
||||
|
||||
/// <summary>
|
||||
/// Sends a JSON-RPC request to the connected session and waits for a response.
|
||||
|
|
|
|||
|
|
@ -29,18 +29,10 @@ internal sealed partial class McpSessionHandler : IAsyncDisposable
|
|||
"mcp.server.operation.duration", "MCP request or notification duration as observed on the receiver from the time it was received until the result or ack is sent.");
|
||||
|
||||
/// <summary>
|
||||
/// All protocol versions supported by this implementation. The version constants live on
|
||||
/// All protocol versions supported by this implementation. The era-specific lists live on
|
||||
/// <see cref="McpHttpHeaders"/> so the shared source file is the single source of truth.
|
||||
/// Keep in sync with s_supportedProtocolVersions in StreamableHttpHandler.
|
||||
/// </summary>
|
||||
internal static readonly string[] SupportedProtocolVersions =
|
||||
[
|
||||
"2024-11-05",
|
||||
"2025-03-26",
|
||||
"2025-06-18",
|
||||
McpHttpHeaders.November2025ProtocolVersion,
|
||||
McpHttpHeaders.July2026ProtocolVersion,
|
||||
];
|
||||
internal static readonly string[] SupportedProtocolVersions = McpProtocolVersions.SupportedProtocolVersions;
|
||||
|
||||
/// <summary>
|
||||
/// Checks if the given protocol version supports priming events.
|
||||
|
|
@ -53,7 +45,7 @@ internal sealed partial class McpSessionHandler : IAsyncDisposable
|
|||
/// </remarks>
|
||||
internal static bool SupportsPrimingEvent(string? protocolVersion)
|
||||
{
|
||||
const string MinResumabilityProtocolVersion = McpHttpHeaders.November2025ProtocolVersion;
|
||||
const string MinResumabilityProtocolVersion = McpProtocolVersions.November2025ProtocolVersion;
|
||||
|
||||
if (protocolVersion is null)
|
||||
{
|
||||
|
|
@ -81,7 +73,7 @@ internal sealed partial class McpSessionHandler : IAsyncDisposable
|
|||
return false;
|
||||
}
|
||||
|
||||
return string.Compare(protocolVersion, McpHttpHeaders.July2026ProtocolVersion, StringComparison.Ordinal) >= 0;
|
||||
return string.Compare(protocolVersion, McpProtocolVersions.July2026ProtocolVersion, StringComparison.Ordinal) >= 0;
|
||||
}
|
||||
|
||||
private readonly bool _isServer;
|
||||
|
|
@ -162,7 +154,7 @@ internal sealed partial class McpSessionHandler : IAsyncDisposable
|
|||
(request, jsonRpcRequest, cancellationToken) =>
|
||||
{
|
||||
string? perRequestVersion = jsonRpcRequest?.Context?.ProtocolVersion ?? NegotiatedProtocolVersion;
|
||||
if (McpHttpHeaders.IsJuly2026OrLaterProtocolVersion(perRequestVersion))
|
||||
if (McpProtocolVersions.RequiresPerRequestMetadata(perRequestVersion))
|
||||
{
|
||||
throw new McpProtocolException(
|
||||
$"Method '{RequestMethods.Ping}' is not available on protocol version '{perRequestVersion}'.",
|
||||
|
|
@ -583,8 +575,8 @@ internal sealed partial class McpSessionHandler : IAsyncDisposable
|
|||
// If a transport-level header (e.g., the Streamable HTTP MCP-Protocol-Version header) already
|
||||
// populated this, validate the body _meta matches per SEP-2575. A disagreement is reported with
|
||||
// -32020 HeaderMismatch (the same code used for the Mcp-Method/Mcp-Name header-vs-body checks),
|
||||
// which conformant 2026-07-28 clients recognize as a modern-server signal and surface as-is rather
|
||||
// than mistaking it for a legacy server and falling back to the initialize handshake.
|
||||
// which conformant 2026-07-28 clients recognize as a SEP-2575 signal and surface as-is rather
|
||||
// than mistaking it for an initialize-handshake server and falling back to initialize.
|
||||
if (context.ProtocolVersion is { } existing && !string.Equals(existing, protocolVersionValue, StringComparison.Ordinal))
|
||||
{
|
||||
throw new McpProtocolException(
|
||||
|
|
@ -618,7 +610,7 @@ internal sealed partial class McpSessionHandler : IAsyncDisposable
|
|||
/// </summary>
|
||||
/// <remarks>
|
||||
/// Used by <see cref="Client.McpClient"/> on a 2026-07-28 or later session to carry protocol version, client
|
||||
/// info, and client capabilities on every outgoing request (replacing what the legacy
|
||||
/// info, and client capabilities on every outgoing request (replacing what the
|
||||
/// <c>initialize</c> handshake previously negotiated once).
|
||||
/// </remarks>
|
||||
internal static void InjectRequestMeta(
|
||||
|
|
|
|||
|
|
@ -32,6 +32,7 @@
|
|||
<Compile Include="..\Common\Experimentals.cs" Link="Experimentals.cs" />
|
||||
<Compile Include="..\Common\EncodingUtilities.cs" Link="EncodingUtilities.cs" />
|
||||
<Compile Include="..\Common\McpHttpHeaders.cs" Link="McpHttpHeaders.cs" />
|
||||
<Compile Include="..\Common\McpProtocolVersions.cs" Link="McpProtocolVersions.cs" />
|
||||
<Compile Include="..\Common\HttpResponseMessageExtensions.cs" Link="HttpResponseMessageExtensions.cs" />
|
||||
<Compile Include="..\Common\ServerSentEvents\**\*.cs" Link="ServerSentEvents\%(RecursiveDir)%(FileName)%(Extension)" />
|
||||
</ItemGroup>
|
||||
|
|
|
|||
|
|
@ -8,16 +8,19 @@ namespace ModelContextProtocol.Protocol;
|
|||
/// <remarks>
|
||||
/// <para>
|
||||
/// Introduced by the 2026-07-28 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.
|
||||
/// to learn what a server supports without performing the <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.
|
||||
/// Gets or sets the list of MCP protocol version strings the server supports for subsequent
|
||||
/// per-request metadata requests.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// The client should choose a version from this list for use in subsequent requests.
|
||||
/// The client should choose a version from this list for subsequent requests that carry the
|
||||
/// 2026-07-28-style per-request <c>_meta</c> envelope. Versions that require the
|
||||
/// <c>initialize</c> handshake are negotiated through <c>initialize</c> instead.
|
||||
/// </remarks>
|
||||
[JsonPropertyName("supportedVersions")]
|
||||
public required IList<string> SupportedVersions { get; set; }
|
||||
|
|
|
|||
|
|
@ -22,16 +22,17 @@ namespace ModelContextProtocol.Protocol;
|
|||
public sealed class InitializeRequestParams : RequestParams
|
||||
{
|
||||
/// <summary>
|
||||
/// Gets or sets the version of the Model Context Protocol that the client wants to use.
|
||||
/// Gets or sets the initialize-handshake Model Context Protocol version that the client wants to use.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// Protocol version is specified using a date-based versioning scheme in the format "YYYY-MM-DD".
|
||||
/// The client and server must agree on a protocol version to communicate successfully.
|
||||
/// The client and server must agree on an initialize-capable protocol version to communicate successfully.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// During initialization, the server will check if it supports this requested version. If there's a
|
||||
/// mismatch, the server will reject the connection with a version mismatch error.
|
||||
/// During initialization, the server will check if it supports this requested version. Protocol
|
||||
/// revisions starting with <c>2026-07-28</c> do not use <c>initialize</c>; clients select them with
|
||||
/// <c>server/discover</c> and per-request metadata instead.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// See the <see href="https://spec.modelcontextprotocol.io/specification/">protocol specification</see> for version details.
|
||||
|
|
|
|||
|
|
@ -22,11 +22,11 @@ namespace ModelContextProtocol.Protocol;
|
|||
public sealed class InitializeResult : Result
|
||||
{
|
||||
/// <summary>
|
||||
/// Gets or sets the version of the Model Context Protocol that the server will use for this session.
|
||||
/// Gets or sets the initialize-handshake Model Context Protocol version that the server will use for this session.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// This is the protocol version the server has agreed to use, which should match the client's
|
||||
/// This is the initialize-capable protocol version the server has agreed to use, which should match the client's
|
||||
/// requested version. If there's a mismatch, the client should throw an exception to prevent
|
||||
/// communication issues due to incompatible protocol versions.
|
||||
/// </para>
|
||||
|
|
|
|||
|
|
@ -217,7 +217,7 @@ public abstract class JsonRpcMessage
|
|||
// 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).
|
||||
// (e.g. an HTTP 400 body whose JSON-RPC envelope carries a non-SEP-2575 error code).
|
||||
return new JsonRpcError
|
||||
{
|
||||
Id = id,
|
||||
|
|
|
|||
|
|
@ -159,15 +159,15 @@ public static class RequestMethods
|
|||
/// <remarks>
|
||||
/// <para>
|
||||
/// This RPC is introduced in the 2026-07-28 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.
|
||||
/// to learn what a server supports without performing the <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. Clients on the 2026-07-28 revision
|
||||
/// typically call this once during connection establishment.
|
||||
/// Servers SHOULD implement this method. Initialize-handshake clients MAY ignore it. Clients on the
|
||||
/// 2026-07-28 revision typically call this once during connection establishment.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public const string ServerDiscover = "server/discover";
|
||||
|
|
@ -179,7 +179,7 @@ public static class RequestMethods
|
|||
/// <remarks>
|
||||
/// <para>
|
||||
/// This RPC is introduced in the 2026-07-28 protocol revision (SEP-2575) and replaces the unsolicited
|
||||
/// HTTP GET endpoint and the legacy <see cref="ResourcesSubscribe"/> / <see cref="ResourcesUnsubscribe"/>
|
||||
/// HTTP GET endpoint and the initialize-handshake <see cref="ResourcesSubscribe"/> / <see cref="ResourcesUnsubscribe"/>
|
||||
/// request methods.
|
||||
/// </para>
|
||||
/// <para>
|
||||
|
|
|
|||
|
|
@ -27,11 +27,22 @@ internal sealed partial class McpServerImpl : McpServer
|
|||
private readonly NotificationHandlers _notificationHandlers;
|
||||
private readonly RequestHandlers _requestHandlers;
|
||||
private readonly McpSessionHandler _sessionHandler;
|
||||
private readonly string[] _supportedProtocolVersions;
|
||||
private readonly string[] _initializeHandshakeProtocolVersions;
|
||||
private readonly string[] _perRequestMetadataProtocolVersions;
|
||||
private readonly SemaphoreSlim _disposeLock = new(1, 1);
|
||||
private readonly ConcurrentDictionary<string, CancellationTokenSource> _taskCancellationSources = new();
|
||||
private readonly ConcurrentDictionary<string, MrtrContinuation> _mrtrContinuations = new();
|
||||
private readonly ConcurrentDictionary<RequestId, MrtrContext> _mrtrContextsByRequestId = new();
|
||||
|
||||
private static readonly string[] s_perRequestMetadataKeys =
|
||||
[
|
||||
MetaKeys.ProtocolVersion,
|
||||
MetaKeys.ClientInfo,
|
||||
MetaKeys.ClientCapabilities,
|
||||
MetaKeys.LogLevel,
|
||||
];
|
||||
|
||||
// Track MRTR handler tasks using the same inFlightCount + TCS pattern as
|
||||
// McpSessionHandler.ProcessMessagesCoreAsync. Starts at 1 for DisposeAsync itself.
|
||||
private int _mrtrInFlightCount = 1;
|
||||
|
|
@ -72,6 +83,9 @@ internal sealed partial class McpServerImpl : McpServer
|
|||
_sessionTransport = transport;
|
||||
ServerOptions = options;
|
||||
Services = serviceProvider;
|
||||
_supportedProtocolVersions = GetConfiguredSupportedProtocolVersions(options.ProtocolVersion);
|
||||
_initializeHandshakeProtocolVersions = [.. _supportedProtocolVersions.Where(McpProtocolVersions.SupportsInitializeHandshake)];
|
||||
_perRequestMetadataProtocolVersions = [.. _supportedProtocolVersions.Where(McpProtocolVersions.RequiresPerRequestMetadata)];
|
||||
_serverOnlyEndpointName = $"Server ({options.ServerInfo?.Name ?? DefaultImplementation.Name} {options.ServerInfo?.Version ?? DefaultImplementation.Version})";
|
||||
_endpointName = _serverOnlyEndpointName;
|
||||
_servicesScopePerRequest = options.ScopeRequests;
|
||||
|
|
@ -161,33 +175,93 @@ internal sealed partial class McpServerImpl : McpServer
|
|||
/// MUST be populated per-request. Per-request client capabilities and client info are consumed request-scoped
|
||||
/// by <see cref="DestinationBoundMcpServer"/> and are not read from server-wide state by request handlers. The
|
||||
/// shared <see cref="_clientInfo"/> write below is best-effort and used only to derive the session endpoint
|
||||
/// name for logging/telemetry. For legacy clients the per-request values are absent and the built-in filter is
|
||||
/// a no-op (the values were captured during the initialize handler).
|
||||
/// name for logging/telemetry. For initialize-handshake clients the per-request values are absent and the built-in
|
||||
/// filter is a no-op (the values were captured during the initialize handler).
|
||||
/// </remarks>
|
||||
private JsonRpcMessageFilter PrependMetaReadingFilter(JsonRpcMessageFilter inner)
|
||||
{
|
||||
JsonRpcMessageFilter metaReadingFilter = next => async (message, cancellationToken) =>
|
||||
{
|
||||
if (message is JsonRpcRequest { Method: not RequestMethods.Initialize } request && request.Context is { } context)
|
||||
if (message is JsonRpcRequest { Method: RequestMethods.Initialize } initializeRequest)
|
||||
{
|
||||
ValidateInitializeRequestBoundary(initializeRequest);
|
||||
}
|
||||
else if (message is JsonRpcRequest request)
|
||||
{
|
||||
var context = request.Context;
|
||||
bool endpointNameNeedsRefresh = false;
|
||||
bool hasProtocolVersionMeta = HasMetaKey(request, MetaKeys.ProtocolVersion);
|
||||
bool hasReservedPerRequestMeta = TryGetPerRequestMetadataKey(request, out var reservedPerRequestMetaKey);
|
||||
|
||||
if (context.ProtocolVersion is { } protocolVersion)
|
||||
if (context?.ProtocolVersion is { } protocolVersion)
|
||||
{
|
||||
bool protocolVersionAlreadyEstablished = _negotiatedProtocolVersion is not null;
|
||||
if (protocolVersionAlreadyEstablished)
|
||||
{
|
||||
SetNegotiatedProtocolVersion(protocolVersion);
|
||||
}
|
||||
|
||||
// Per SEP-2575, the server MUST reject any request whose per-request
|
||||
// _meta/io.modelcontextprotocol/protocolVersion is not one of its supported versions
|
||||
// with an UnsupportedProtocolVersionError (-32022) carrying the supported list.
|
||||
if (!McpSessionHandler.SupportedProtocolVersions.Contains(protocolVersion))
|
||||
if (!_supportedProtocolVersions.Contains(protocolVersion))
|
||||
{
|
||||
throw new UnsupportedProtocolVersionException(
|
||||
requested: protocolVersion,
|
||||
supported: McpSessionHandler.SupportedProtocolVersions);
|
||||
supported: _supportedProtocolVersions);
|
||||
}
|
||||
|
||||
SetNegotiatedProtocolVersion(protocolVersion);
|
||||
if (McpProtocolVersions.RequiresPerRequestMetadata(protocolVersion))
|
||||
{
|
||||
ValidateRequiredPerRequestMetadata(
|
||||
protocolVersion,
|
||||
hasProtocolVersionMeta,
|
||||
context.ClientInfo is not null,
|
||||
context.ClientCapabilities is not null);
|
||||
}
|
||||
else if (McpProtocolVersions.SupportsInitializeHandshake(protocolVersion))
|
||||
{
|
||||
if (_negotiatedProtocolVersion is null && hasProtocolVersionMeta)
|
||||
{
|
||||
throw new UnsupportedProtocolVersionException(
|
||||
requested: protocolVersion,
|
||||
supported: _perRequestMetadataProtocolVersions,
|
||||
message: $"Protocol version '{protocolVersion}' requires the initialize handshake and cannot be selected through per-request metadata.");
|
||||
}
|
||||
|
||||
if (hasReservedPerRequestMeta)
|
||||
{
|
||||
ThrowReservedPerRequestMetadata(requestedProtocolVersion: protocolVersion, reservedPerRequestMetaKey);
|
||||
}
|
||||
}
|
||||
|
||||
if (!protocolVersionAlreadyEstablished)
|
||||
{
|
||||
SetNegotiatedProtocolVersion(protocolVersion);
|
||||
}
|
||||
}
|
||||
else if (_negotiatedProtocolVersion is null)
|
||||
{
|
||||
if (request.Method == RequestMethods.ServerDiscover)
|
||||
{
|
||||
throw new McpProtocolException(
|
||||
$"The '{RequestMethods.ServerDiscover}' request requires per-request metadata declaring a supported protocol version.",
|
||||
McpErrorCode.InvalidParams);
|
||||
}
|
||||
|
||||
if (hasReservedPerRequestMeta)
|
||||
{
|
||||
ThrowReservedPerRequestMetadata(requestedProtocolVersion: null, reservedPerRequestMetaKey);
|
||||
}
|
||||
}
|
||||
else if (McpProtocolVersions.SupportsInitializeHandshake(_negotiatedProtocolVersion) && hasReservedPerRequestMeta)
|
||||
{
|
||||
ThrowReservedPerRequestMetadata(_negotiatedProtocolVersion, reservedPerRequestMetaKey);
|
||||
}
|
||||
|
||||
if (context.ClientInfo is { } clientInfo &&
|
||||
ValidateRequestMethodBoundary(request);
|
||||
|
||||
if (context?.ClientInfo is { } clientInfo &&
|
||||
(_clientInfo is null || !string.Equals(_clientInfo.Name, clientInfo.Name, StringComparison.Ordinal) ||
|
||||
!string.Equals(_clientInfo.Version, clientInfo.Version, StringComparison.Ordinal)))
|
||||
{
|
||||
|
|
@ -207,6 +281,10 @@ internal sealed partial class McpServerImpl : McpServer
|
|||
_sessionHandler.EndpointName = _endpointName;
|
||||
}
|
||||
}
|
||||
else if (message is JsonRpcNotification notification)
|
||||
{
|
||||
ValidateNotificationBoundary(notification);
|
||||
}
|
||||
|
||||
await next(message, cancellationToken).ConfigureAwait(false);
|
||||
};
|
||||
|
|
@ -214,6 +292,142 @@ internal sealed partial class McpServerImpl : McpServer
|
|||
return next => metaReadingFilter(inner(next));
|
||||
}
|
||||
|
||||
private static void ValidateRequiredPerRequestMetadata(
|
||||
string protocolVersion,
|
||||
bool hasProtocolVersionMeta,
|
||||
bool hasClientInfoMeta,
|
||||
bool hasClientCapabilitiesMeta)
|
||||
{
|
||||
if (!hasProtocolVersionMeta)
|
||||
{
|
||||
ThrowMissingPerRequestMetadata(protocolVersion, MetaKeys.ProtocolVersion);
|
||||
}
|
||||
|
||||
if (!hasClientInfoMeta)
|
||||
{
|
||||
ThrowMissingPerRequestMetadata(protocolVersion, MetaKeys.ClientInfo);
|
||||
}
|
||||
|
||||
if (!hasClientCapabilitiesMeta)
|
||||
{
|
||||
ThrowMissingPerRequestMetadata(protocolVersion, MetaKeys.ClientCapabilities);
|
||||
}
|
||||
}
|
||||
|
||||
private static void ThrowMissingPerRequestMetadata(string protocolVersion, string key) =>
|
||||
throw new McpProtocolException(
|
||||
$"Requests using protocol version '{protocolVersion}' must include '_meta/{key}'.",
|
||||
McpErrorCode.InvalidParams);
|
||||
|
||||
private static void ThrowReservedPerRequestMetadata(string? requestedProtocolVersion, string key) =>
|
||||
throw new McpProtocolException(
|
||||
requestedProtocolVersion is null
|
||||
? $"The reserved per-request metadata key '_meta/{key}' requires a protocol version that uses per-request metadata."
|
||||
: $"The reserved per-request metadata key '_meta/{key}' is not valid with protocol version '{requestedProtocolVersion}'.",
|
||||
McpErrorCode.InvalidRequest);
|
||||
|
||||
private static bool TryGetPerRequestMetadataKey(JsonRpcRequest request, out string key)
|
||||
{
|
||||
foreach (var candidate in s_perRequestMetadataKeys)
|
||||
{
|
||||
if (HasMetaKey(request, candidate))
|
||||
{
|
||||
key = candidate;
|
||||
return true;
|
||||
}
|
||||
}
|
||||
|
||||
key = "";
|
||||
return false;
|
||||
}
|
||||
|
||||
private static bool HasMetaKey(JsonRpcRequest request, string key) =>
|
||||
request.Params is JsonObject paramsObj &&
|
||||
paramsObj["_meta"] is JsonObject metaObj &&
|
||||
metaObj.ContainsKey(key);
|
||||
|
||||
private void ValidateInitializeRequestBoundary(JsonRpcRequest request)
|
||||
{
|
||||
if (request.Context?.ProtocolVersion is { } protocolVersion &&
|
||||
!McpProtocolVersions.SupportsInitializeHandshake(protocolVersion))
|
||||
{
|
||||
throw new UnsupportedProtocolVersionException(
|
||||
requested: protocolVersion,
|
||||
supported: _initializeHandshakeProtocolVersions,
|
||||
message: $"Protocol version '{protocolVersion}' is not available through the initialize handshake.");
|
||||
}
|
||||
|
||||
if (TryGetPerRequestMetadataKey(request, out var key))
|
||||
{
|
||||
ThrowReservedPerRequestMetadata(TryGetStringParam(request, "protocolVersion"), key);
|
||||
}
|
||||
}
|
||||
|
||||
private static string? TryGetStringParam(JsonRpcRequest request, string propertyName)
|
||||
{
|
||||
if (request.Params is JsonObject paramsObj &&
|
||||
paramsObj[propertyName] is JsonValue value &&
|
||||
value.TryGetValue(out string? result))
|
||||
{
|
||||
return result;
|
||||
}
|
||||
|
||||
return null;
|
||||
}
|
||||
|
||||
private static string[] GetConfiguredSupportedProtocolVersions(string? protocolVersion)
|
||||
{
|
||||
if (protocolVersion is null)
|
||||
{
|
||||
return McpProtocolVersions.SupportedProtocolVersions;
|
||||
}
|
||||
|
||||
if (!McpProtocolVersions.IsSupportedProtocolVersion(protocolVersion))
|
||||
{
|
||||
throw new McpException(
|
||||
$"Unsupported server protocol version '{protocolVersion}'. Supported protocol versions: " +
|
||||
string.Join(", ", McpProtocolVersions.SupportedProtocolVersions) + ".");
|
||||
}
|
||||
|
||||
return [protocolVersion];
|
||||
}
|
||||
|
||||
private void ValidateNotificationBoundary(JsonRpcNotification notification)
|
||||
{
|
||||
if (notification.Method == NotificationMethods.InitializedNotification &&
|
||||
McpProtocolVersions.RequiresPerRequestMetadata(notification.Context?.ProtocolVersion ?? _negotiatedProtocolVersion))
|
||||
{
|
||||
throw new McpProtocolException(
|
||||
$"The notification '{NotificationMethods.InitializedNotification}' is only valid after the initialize handshake.",
|
||||
McpErrorCode.InvalidRequest);
|
||||
}
|
||||
}
|
||||
|
||||
private void ValidateRequestMethodBoundary(JsonRpcRequest request)
|
||||
{
|
||||
bool usesPerRequestMetadata = IsJuly2026OrLaterProtocolRequest(request);
|
||||
|
||||
if (!usesPerRequestMetadata &&
|
||||
request.Method is RequestMethods.SubscriptionsListen
|
||||
or RequestMethods.TasksGet
|
||||
or RequestMethods.TasksUpdate
|
||||
or RequestMethods.TasksCancel
|
||||
or RequestMethods.ServerDiscover)
|
||||
{
|
||||
throw new McpProtocolException(
|
||||
$"The method '{request.Method}' requires a newer protocol revision that supports per-request metadata; " +
|
||||
$"the negotiated protocol version is '{NegotiatedProtocolVersion ?? "(none)"}'.",
|
||||
McpErrorCode.MethodNotFound);
|
||||
}
|
||||
|
||||
if (usesPerRequestMetadata && request.Method == RequestMethods.LoggingSetLevel)
|
||||
{
|
||||
throw new McpProtocolException(
|
||||
$"The method '{RequestMethods.LoggingSetLevel}' is not available on protocol version '{request.Context?.ProtocolVersion ?? NegotiatedProtocolVersion}'. Use per-request _meta/{MetaKeys.LogLevel} instead.",
|
||||
McpErrorCode.MethodNotFound);
|
||||
}
|
||||
}
|
||||
|
||||
/// <inheritdoc/>
|
||||
public override string? SessionId => _sessionTransport.SessionId;
|
||||
|
||||
|
|
@ -356,26 +570,54 @@ internal sealed partial class McpServerImpl : McpServer
|
|||
UpdateEndpointNameWithClientInfo();
|
||||
_sessionHandler.EndpointName = _endpointName;
|
||||
|
||||
// Negotiate a protocol version. If the server options provide one, use that.
|
||||
// Otherwise, try to use whatever the client requested as long as it's supported.
|
||||
// If it's not supported, fall back to the latest supported version.
|
||||
// Negotiate an initialize-handshake protocol version. initialize is not available in the 2026-07-28
|
||||
// and later protocol revisions, so those versions must use server/discover with
|
||||
// per-request _meta instead.
|
||||
string? protocolVersion = options.ProtocolVersion;
|
||||
protocolVersion ??= request?.ProtocolVersion is string clientProtocolVersion &&
|
||||
McpSessionHandler.SupportedProtocolVersions.Contains(clientProtocolVersion) ?
|
||||
clientProtocolVersion :
|
||||
McpHttpHeaders.November2025ProtocolVersion;
|
||||
if (protocolVersion is { } configuredProtocolVersion &&
|
||||
McpProtocolVersions.IsJuly2026OrLaterProtocolVersion(configuredProtocolVersion))
|
||||
{
|
||||
throw new UnsupportedProtocolVersionException(
|
||||
configuredProtocolVersion,
|
||||
_initializeHandshakeProtocolVersions,
|
||||
$"Protocol version '{configuredProtocolVersion}' is not available through the initialize handshake.");
|
||||
}
|
||||
|
||||
// The legacy initialize handshake is authoritative: it may supersede a protocol version
|
||||
// a prior server/discover probe established on the same connection (the dual-era
|
||||
if (protocolVersion is null)
|
||||
{
|
||||
if (request?.ProtocolVersion is string clientProtocolVersion)
|
||||
{
|
||||
if (McpProtocolVersions.IsJuly2026OrLaterProtocolVersion(clientProtocolVersion))
|
||||
{
|
||||
throw new UnsupportedProtocolVersionException(
|
||||
clientProtocolVersion,
|
||||
_initializeHandshakeProtocolVersions,
|
||||
$"Protocol version '{clientProtocolVersion}' is not available through the initialize handshake.");
|
||||
}
|
||||
|
||||
protocolVersion = McpProtocolVersions.SupportsInitializeHandshake(clientProtocolVersion) ?
|
||||
clientProtocolVersion :
|
||||
McpProtocolVersions.November2025ProtocolVersion;
|
||||
}
|
||||
else
|
||||
{
|
||||
protocolVersion = McpProtocolVersions.November2025ProtocolVersion;
|
||||
}
|
||||
}
|
||||
|
||||
string negotiatedProtocolVersion = protocolVersion ?? McpProtocolVersions.November2025ProtocolVersion;
|
||||
|
||||
// The initialize handshake is authoritative: it may supersede a protocol version
|
||||
// a prior server/discover probe established on the same connection (the dual-path
|
||||
// fallback path a permissive client takes against an unknown server). Unlike the
|
||||
// per-request 2026-07-28 version - which SetNegotiatedProtocolVersion locks once negotiated -
|
||||
// initialize force-sets the version.
|
||||
_negotiatedProtocolVersion = protocolVersion;
|
||||
_sessionHandler.NegotiatedProtocolVersion = protocolVersion;
|
||||
_negotiatedProtocolVersion = negotiatedProtocolVersion;
|
||||
_sessionHandler.NegotiatedProtocolVersion = negotiatedProtocolVersion;
|
||||
|
||||
return new InitializeResult
|
||||
{
|
||||
ProtocolVersion = protocolVersion,
|
||||
ProtocolVersion = negotiatedProtocolVersion,
|
||||
Instructions = options.ServerInstructions,
|
||||
ServerInfo = options.ServerInfo ?? DefaultImplementation,
|
||||
Capabilities = ServerCapabilities ?? new(),
|
||||
|
|
@ -389,9 +631,9 @@ internal sealed partial class McpServerImpl : McpServer
|
|||
/// Registers the <c>server/discover</c> request handler introduced by the 2026-07-28 protocol revision (SEP-2575).
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// The handler is registered unconditionally so legacy clients can probe it too. It returns the server's
|
||||
/// supported protocol versions (<see cref="McpSessionHandler.SupportedProtocolVersions"/>), server
|
||||
/// capabilities, server info, and optional instructions.
|
||||
/// The handler is registered unconditionally so requests can be routed to the protocol boundary filters. Successful
|
||||
/// <c>server/discover</c> responses advertise only protocol versions available through per-request metadata; versions
|
||||
/// that require the <c>initialize</c> handshake are negotiated through <c>initialize</c> instead.
|
||||
/// </remarks>
|
||||
private void ConfigureDiscover(McpServerOptions options)
|
||||
{
|
||||
|
|
@ -400,7 +642,7 @@ internal sealed partial class McpServerImpl : McpServer
|
|||
{
|
||||
return new ValueTask<DiscoverResult>(new DiscoverResult
|
||||
{
|
||||
SupportedVersions = [.. McpSessionHandler.SupportedProtocolVersions],
|
||||
SupportedVersions = [.. _perRequestMetadataProtocolVersions],
|
||||
Capabilities = ServerCapabilities ?? new(),
|
||||
ServerInfo = options.ServerInfo ?? DefaultImplementation,
|
||||
Instructions = options.ServerInstructions,
|
||||
|
|
@ -435,6 +677,14 @@ internal sealed partial class McpServerImpl : McpServer
|
|||
_requestHandlers.Set(RequestMethods.SubscriptionsListen,
|
||||
async (request, jsonRpcRequest, cancellationToken) =>
|
||||
{
|
||||
if (!IsJuly2026OrLaterProtocolRequest(jsonRpcRequest))
|
||||
{
|
||||
throw new McpProtocolException(
|
||||
$"The method '{RequestMethods.SubscriptionsListen}' requires a newer protocol revision that supports per-request subscriptions; " +
|
||||
$"the negotiated protocol version is '{NegotiatedProtocolVersion ?? "(none)"}'.",
|
||||
McpErrorCode.MethodNotFound);
|
||||
}
|
||||
|
||||
var requested = request?.Notifications ?? new SubscriptionsListenNotifications();
|
||||
|
||||
// A stateless session (Streamable HTTP with no session) cannot deliver out-of-band
|
||||
|
|
@ -442,7 +692,7 @@ internal sealed partial class McpServerImpl : McpServer
|
|||
// changes back to the client (tracked by #1662). Rather than hold the POST open forever only
|
||||
// to deliver nothing - pinning the connection and its request scope - acknowledge the listen
|
||||
// request granting no notifications and complete immediately. This runs after protocol
|
||||
// negotiation, so it is not a legacy-server signal and never triggers a client fallback to the
|
||||
// negotiation, so it is not an initialize-handshake-server signal and never triggers a client fallback to the
|
||||
// initialize handshake.
|
||||
if (!HasStatefulTransport())
|
||||
{
|
||||
|
|
@ -522,7 +772,7 @@ internal sealed partial class McpServerImpl : McpServer
|
|||
/// </remarks>
|
||||
private async Task SendListChangedNotificationAsync(string notificationMethod)
|
||||
{
|
||||
// Legacy clients never open a subscriptions/listen stream, so they keep the session-wide broadcast.
|
||||
// Initialize-handshake clients never open a subscriptions/listen stream, so they keep the session-wide broadcast.
|
||||
// subscriptions/listen is a SEP-2575 feature, so clients on the 2026-07-28 or later revision instead get
|
||||
// a fan-out limited to the notification types they explicitly subscribed to.
|
||||
if (!IsJuly2026OrLaterProtocol())
|
||||
|
|
@ -805,8 +1055,8 @@ internal sealed partial class McpServerImpl : McpServer
|
|||
cancelTaskHandler ??= (static async (request, _) => throw new McpProtocolException($"Unknown task: '{request.Params?.TaskId}'", McpErrorCode.InvalidParams));
|
||||
|
||||
// The tasks/* methods do not exist before the 2026-07-28 revision (SEP-2663). Reject them with
|
||||
// MethodNotFound when the request was negotiated under a legacy protocol version. The handlers
|
||||
// stay registered so a dual-era server still serves them for 2026-07-28 requests.
|
||||
// MethodNotFound when the request was negotiated under an initialize-handshake protocol version. The handlers
|
||||
// stay registered so a dual-path server still serves them for 2026-07-28 requests.
|
||||
getTaskHandler = GateTaskMethodToJuly2026OrLaterProtocol(getTaskHandler, RequestMethods.TasksGet);
|
||||
updateTaskHandler = GateTaskMethodToJuly2026OrLaterProtocol(updateTaskHandler, RequestMethods.TasksUpdate);
|
||||
cancelTaskHandler = GateTaskMethodToJuly2026OrLaterProtocol(cancelTaskHandler, RequestMethods.TasksCancel);
|
||||
|
|
@ -883,7 +1133,7 @@ internal sealed partial class McpServerImpl : McpServer
|
|||
listResourceTemplatesHandler ??= (static async (_, __) => new ListResourceTemplatesResult());
|
||||
readResourceHandler ??= (static async (request, _) =>
|
||||
{
|
||||
var errorCode = McpHttpHeaders.UseInvalidParamsForMissingResource(request.Server.NegotiatedProtocolVersion)
|
||||
var errorCode = McpProtocolVersions.UseInvalidParamsForMissingResource(request.Server.NegotiatedProtocolVersion)
|
||||
? McpErrorCode.InvalidParams
|
||||
: McpErrorCode.ResourceNotFound;
|
||||
throw new McpProtocolException($"Unknown resource URI: '{request.Params?.Uri}'", errorCode);
|
||||
|
|
@ -1560,6 +1810,13 @@ internal sealed partial class McpServerImpl : McpServer
|
|||
RequestMethods.LoggingSetLevel,
|
||||
(request, jsonRpcRequest, cancellationToken) =>
|
||||
{
|
||||
if (IsJuly2026OrLaterProtocolRequest(jsonRpcRequest))
|
||||
{
|
||||
throw new McpProtocolException(
|
||||
$"The method '{RequestMethods.LoggingSetLevel}' is not available on protocol version '{jsonRpcRequest.Context?.ProtocolVersion ?? NegotiatedProtocolVersion}'. Use per-request _meta/{MetaKeys.LogLevel} instead.",
|
||||
McpErrorCode.MethodNotFound);
|
||||
}
|
||||
|
||||
// Store the provided level.
|
||||
if (request is not null)
|
||||
{
|
||||
|
|
@ -1794,7 +2051,7 @@ internal sealed partial class McpServerImpl : McpServer
|
|||
|
||||
/// <inheritdoc cref="IsJuly2026OrLaterProtocolRequest(JsonRpcRequest?)"/>
|
||||
internal bool IsJuly2026OrLaterProtocolRequest(JsonRpcMessageContext? requestContext) =>
|
||||
McpHttpHeaders.IsJuly2026OrLaterProtocolVersion(
|
||||
McpProtocolVersions.IsJuly2026OrLaterProtocolVersion(
|
||||
requestContext?.ProtocolVersion ?? NegotiatedProtocolVersion);
|
||||
|
||||
/// <inheritdoc />
|
||||
|
|
|
|||
|
|
@ -14,7 +14,7 @@ public sealed class McpServerOptions
|
|||
/// Gets or sets information about this server implementation, including its name and version.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// This information is sent to the client during initialization to identify the server.
|
||||
/// This information is sent to the client during initialization or discovery to identify the server.
|
||||
/// It's displayed in client logs and can be used for debugging and compatibility checks.
|
||||
/// </remarks>
|
||||
public Implementation? ServerInfo { get; set; }
|
||||
|
|
@ -33,11 +33,23 @@ public sealed class McpServerOptions
|
|||
/// Gets or sets the protocol version supported by this server, using a date-based versioning scheme.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// The protocol version defines which features and message formats this server supports.
|
||||
/// This uses a date-based versioning scheme in the format "YYYY-MM-DD".
|
||||
/// If <see langword="null"/>, the server will advertise to the client the version requested
|
||||
/// by the client if that version is known to be supported, and otherwise will advertise the latest
|
||||
/// version supported by the server.
|
||||
/// <para>
|
||||
/// The protocol version defines which features and message formats this server supports. Supported
|
||||
/// values are <c>2024-11-05</c>, <c>2025-03-26</c>, <c>2025-06-18</c>, <c>2025-11-25</c>, and
|
||||
/// <c>2026-07-28</c>.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// If <see langword="null"/>, the server supports all of the versions listed above. For clients using
|
||||
/// the <c>initialize</c> handshake, the server returns the requested initialize-capable version when it
|
||||
/// is supported and otherwise returns <c>2025-11-25</c>. For clients using <c>server/discover</c> and
|
||||
/// per-request metadata, the server advertises the supported per-request metadata versions; currently
|
||||
/// this is <c>2026-07-28</c>.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// Set this property to a specific supported value to pin the server to that version. Setting it to
|
||||
/// <c>2026-07-28</c> makes the server reject <c>initialize</c> handshakes; setting it to an earlier
|
||||
/// value makes the server reject <c>2026-07-28</c> per-request metadata.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public string? ProtocolVersion { get; set; }
|
||||
|
||||
|
|
@ -74,12 +86,13 @@ public sealed class McpServerOptions
|
|||
public bool ScopeRequests { get; set; } = true;
|
||||
|
||||
/// <summary>
|
||||
/// Gets or sets preexisting knowledge about the client including its name and version to help support
|
||||
/// stateless Streamable HTTP servers that encode this knowledge in the mcp-session-id header.
|
||||
/// Gets or sets preexisting knowledge about the client including its name and version.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// When not specified, this information is sourced from the client's initialize request.
|
||||
/// When not specified, this information is sourced from the client's <c>initialize</c> request or,
|
||||
/// for protocol versions that use per-request metadata, from the current request's <c>_meta</c> field.
|
||||
/// This is typically set during session migration in conjunction with <see cref="KnownClientCapabilities"/>.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public Implementation? KnownClientInfo { get; set; }
|
||||
|
|
@ -90,7 +103,8 @@ public sealed class McpServerOptions
|
|||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// When not specified, this information is sourced from the client's initialize request.
|
||||
/// When not specified, this information is sourced from the client's <c>initialize</c> request or,
|
||||
/// for protocol versions that use per-request metadata, from the current request's <c>_meta</c> field.
|
||||
/// This is typically set during session migration in conjunction with <see cref="KnownClientInfo"/>.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
|
|
|
|||
Loading…
Reference in a new issue