Deprecate McpErrorCode.ResourceNotFound (-32002) and use McpErrorCode.InvalidParams (-32602) per SEP-2164

src/ModelContextProtocol.Core/McpErrorCode.cs

@@ -9,8 +9,22 @@ public enum McpErrorCode
     /// Indicates that the requested resource could not be found.
     /// </summary>
     /// <remarks>
-    /// This error should be used when a resource URI does not match any available resource on the server.
-    /// It allows clients to distinguish between missing resources and other types of errors.
+    /// <para>
+    /// Legacy error code for unresolvable resource URIs. Per SEP-2164 (MCP spec 2026-06-30) this is
+    /// superseded by <see cref="InvalidParams"/> (-32602), the standard JSON-RPC code that the
+    /// 2026-06-30 spec mandates for the same condition.
+    /// </para>
+    /// <para>
+    /// The SDK selects between the two automatically based on the negotiated protocol version:
+    /// </para>
+    /// <list type="bullet">
+    ///   <item><description>Negotiated version &lt; <c>"2026-06-30"</c>: SDK returns <see cref="ResourceNotFound"/> (-32002).</description></item>
+    ///   <item><description>Negotiated version &gt;= <c>"2026-06-30"</c> (including the in-flight draft string <c>"DRAFT-2026-06-v1"</c>): SDK returns <see cref="InvalidParams"/> (-32602).</description></item>
+    /// </list>
+    /// <para>
+    /// New user code throwing <see cref="McpProtocolException"/> directly for unknown-resource conditions
+    /// should prefer <see cref="InvalidParams"/>; the SDK will still pass the value through unchanged.
+    /// </para>
     /// </remarks>
     ResourceNotFound = -32002,
 
@@ -65,6 +79,7 @@ public enum McpErrorCode
     /// <list type="bullet">
     /// <item><description><b>Tools</b>: Unknown tool name or invalid protocol-level tool arguments.</description></item>
     /// <item><description><b>Prompts</b>: Unknown prompt name or missing required protocol-level arguments.</description></item>
+    /// <item><description><b>Resources</b>: Unknown or unresolvable resource URI.</description></item>
     /// <item><description><b>Pagination</b>: Invalid or expired cursor values.</description></item>
     /// <item><description><b>Logging</b>: Invalid log level.</description></item>
     /// <item><description><b>Tasks</b>: Invalid or nonexistent task ID or invalid cursor.</description></item>

src/ModelContextProtocol.Core/McpProtocolException.cs

@@ -76,7 +76,7 @@ public McpProtocolException(string message, Exception? innerException, McpErrorC
     /// <item><description>-32700: Parse error - Invalid JSON received</description></item>
     /// <item><description>-32600: Invalid request - The JSON is not a valid Request object</description></item>
     /// <item><description>-32601: Method not found - The method does not exist or is not available</description></item>
-    /// <item><description>-32602: Invalid params - Malformed request or unknown primitive name (tool/prompt/resource)</description></item>
+    /// <item><description>-32602: Invalid params - Malformed request, unknown primitive name (tool/prompt/resource), or unresolvable resource URI</description></item>
     /// <item><description>-32603: Internal error - Internal JSON-RPC error</description></item>
     /// </list>
     /// </remarks>

src/ModelContextProtocol.Core/McpSessionHandler.cs

@@ -64,6 +64,30 @@ internal static bool SupportsPrimingEvent(string? protocolVersion)
         return string.Compare(protocolVersion, MinResumabilityProtocolVersion, StringComparison.Ordinal) >= 0;
     }
 
+    /// <summary>
+    /// Checks whether the negotiated protocol version takes the SEP-2164 error code for
+    /// unresolvable resource URIs (<see cref="McpErrorCode.InvalidParams"/>, -32602) rather
+    /// than the legacy <see cref="McpErrorCode.ResourceNotFound"/> (-32002).
+    /// </summary>
+    /// <remarks>
+    /// SEP-2164 (MCP spec 2026-06-30) replaces the legacy code with the standard JSON-RPC
+    /// <see cref="McpErrorCode.InvalidParams"/>. Returns <see langword="true"/> for protocol
+    /// versions that sort lexically &gt;= <c>"2026-06-30"</c>; this also covers the in-flight
+    /// draft string <c>"DRAFT-2026-06-v1"</c> because <c>'D'</c> sorts greater than <c>'2'</c>
+    /// in ASCII.
+    /// </remarks>
+    internal static bool UseSep2164ResourceErrors(string? protocolVersion)
+    {
+        const string MinSep2164ProtocolVersion = "2026-06-30";
+
+        if (protocolVersion is null)
+        {
+            return false;
+        }
+
+        return string.Compare(protocolVersion, MinSep2164ProtocolVersion, StringComparison.Ordinal) >= 0;
+    }
+
     private readonly bool _isServer;
     private readonly string _transportKind;
     private readonly ITransport _transport;

src/ModelContextProtocol.Core/Server/McpServerImpl.cs

@@ -421,7 +421,19 @@ subscribeHandler is null && unsubscribeHandler is null && resources is null &&
 
         listResourcesHandler ??= (static async (_, __) => new ListResourcesResult());
         listResourceTemplatesHandler ??= (static async (_, __) => new ListResourceTemplatesResult());
-        readResourceHandler ??= (static async (request, _) => throw new McpProtocolException($"Unknown resource URI: '{request.Params?.Uri}'", McpErrorCode.ResourceNotFound));
+        // Per SEP-2164, unresolvable resource URIs are reported as InvalidParams (-32602) on
+        // the 2026-06-30 spec and later. The legacy ResourceNotFound (-32002) is preserved for
+        // earlier protocol versions so pre-SEP-2164 clients pattern-matching on -32002 still
+        // recognise the condition. Selection is based on the version both ends agreed on during
+        // initialization; mismatched versions never reach this handler (the client fails to
+        // connect on a mismatch).
+        readResourceHandler ??= (static async (request, _) =>
+        {
+            var errorCode = McpSessionHandler.UseSep2164ResourceErrors(request.Server.NegotiatedProtocolVersion)
+                ? McpErrorCode.InvalidParams
+                : McpErrorCode.ResourceNotFound;
+            throw new McpProtocolException($"Unknown resource URI: '{request.Params?.Uri}'", errorCode);
+        });
         subscribeHandler ??= (static async (_, __) => new EmptyResult());
         unsubscribeHandler ??= (static async (_, __) => new EmptyResult());
         var listChanged = resourcesCapability?.ListChanged;

tests/ModelContextProtocol.TestServer/Program.cs

@@ -503,7 +503,7 @@ private static void ConfigureResources(McpServerOptions options)
             }
 
             ResourceContents contents = resourceContents.FirstOrDefault(r => r.Uri == request.Params.Uri)
-                ?? throw new McpProtocolException($"Resource not found: '{request.Params.Uri}'", McpErrorCode.ResourceNotFound);
+                ?? throw new McpProtocolException($"Resource not found: '{request.Params.Uri}'", McpErrorCode.InvalidParams);
 
             return new ReadResourceResult
             {

tests/ModelContextProtocol.TestSseServer/Program.cs

@@ -307,7 +307,7 @@ static CreateMessageRequestParams CreateRequestSamplingParams(string context, st
                 }
 
                 ResourceContents? contents = resourceContents.FirstOrDefault(r => r.Uri == request.Params.Uri) ??
-                    throw new McpProtocolException($"Resource not found: '{request.Params.Uri}'", McpErrorCode.ResourceNotFound);
+                    throw new McpProtocolException($"Resource not found: '{request.Params.Uri}'", McpErrorCode.InvalidParams);
 
                 return new ReadResourceResult
                 {

tests/ModelContextProtocol.Tests/Configuration/McpServerBuilderExtensionsResourcesTests.cs

@@ -109,7 +109,7 @@ protected override void ConfigureServices(ServiceCollection services, IMcpServer
                     };
             }
 
-            throw new McpProtocolException($"Resource not found: {request.Params.Uri}", McpErrorCode.ResourceNotFound);
+            throw new McpProtocolException($"Resource not found: {request.Params.Uri}", McpErrorCode.InvalidParams);
         })
         .WithResources<SimpleResources>();
     }
@@ -317,7 +317,7 @@ public async Task Throws_Exception_On_Unknown_Resource()
             cancellationToken: TestContext.Current.CancellationToken));
 
         Assert.Contains("Resource not found", e.Message);
-        Assert.Equal(McpErrorCode.ResourceNotFound, e.ErrorCode);
+        Assert.Equal(McpErrorCode.InvalidParams, e.ErrorCode);
     }
 
     [Fact]

tests/ModelContextProtocol.Tests/Configuration/McpServerResourceRoutingTests.cs

@@ -1,4 +1,5 @@
 using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Options;
 using ModelContextProtocol.Client;
 using ModelContextProtocol.Protocol;
 using ModelContextProtocol.Server;
@@ -22,6 +23,27 @@ private async Task<McpClient> CreateClientWithResourcesAsync(params McpServerRes
         return await CreateMcpClientForServer();
     }
 
+    /// <summary>
+    /// Starts the server with the specified resources, pins both the server's and the
+    /// client's protocol version to <paramref name="protocolVersion"/>, and returns a
+    /// connected client.
+    /// </summary>
+    /// <remarks>
+    /// Both ends must be pinned because <see cref="McpClient"/> strictly compares the
+    /// server's negotiated version against the client's requested version and refuses to
+    /// connect on mismatch. Used to drive the SEP-2164 error-code gate from tests without
+    /// bumping the SDK's <c>SupportedProtocolVersions</c> array.
+    /// </remarks>
+    private async Task<McpClient> CreateClientWithResourcesAndServerVersionAsync(
+        string protocolVersion,
+        params McpServerResource[] resources)
+    {
+        McpServerBuilder.WithResources(resources);
+        McpServerBuilder.Services.Configure<McpServerOptions>(o => o.ProtocolVersion = protocolVersion);
+        StartServer();
+        return await CreateMcpClientForServer(new McpClientOptions { ProtocolVersion = protocolVersion });
+    }
+
     /// <summary>
     /// Asserts that the given URI matches the template and produces the expected text result.
     /// </summary>
@@ -40,20 +62,54 @@ private async Task AssertMatchAsync(
     }
 
     /// <summary>
-    /// Asserts that the given URI does NOT match the template.
+    /// Asserts that the given URI does NOT match the template. Server is pinned to the
+    /// 2026-06-30 protocol version so the SEP-2164 gate produces <see cref="McpErrorCode.InvalidParams"/>
+    /// rather than the legacy <c>ResourceNotFound</c>.
     /// </summary>
     private async Task AssertNoMatchAsync(
         string uriTemplate,
         Delegate method,
         string uri)
     {
         var resource = McpServerResource.Create(options: new() { UriTemplate = uriTemplate }, method: method);
-        var client = await CreateClientWithResourcesAsync(resource);
+        var client = await CreateClientWithResourcesAndServerVersionAsync("2026-06-30", resource);
 
         var ex = await Assert.ThrowsAsync<McpProtocolException>(async () =>
             await client.ReadResourceAsync(uri, null, TestContext.Current.CancellationToken));
 
-        Assert.Equal(McpErrorCode.ResourceNotFound, ex.ErrorCode);
+        Assert.Equal(McpErrorCode.InvalidParams, ex.ErrorCode);
+    }
+
+    // SEP-2164 standardizes the error code for "unknown resource URI" from the legacy
+    // -32002 (McpErrorCode.ResourceNotFound) to the standard JSON-RPC -32602
+    // (McpErrorCode.InvalidParams). Per Mike Kistler's review on PR #1558, this is
+    // version-gated to keep pre-2026-06-30 clients working: when the negotiated protocol
+    // version is < "2026-06-30", the SDK still returns the legacy code.
+    //
+    // The three inline cases below exercise:
+    //   - "2025-11-25"      — the latest pre-SEP-2164 protocol version.
+    //   - "DRAFT-2026-06-v1" — the in-flight draft string used during spec review.
+    //   - "2026-06-30"      — the anticipated final spec version.
+    //
+    // The draft string is included because lexically `'D' > '2'`, so the SDK's
+    // string-comparison-based gate (matching the precedent set by `SupportsPrimingEvent`)
+    // routes both the draft and the final version through the new code path.
+    [Theory]
+    [InlineData("2025-11-25", McpErrorCode.ResourceNotFound)]
+    [InlineData("DRAFT-2026-06-v1", McpErrorCode.InvalidParams)]
+    [InlineData("2026-06-30", McpErrorCode.InvalidParams)]
+    public async Task ResourceNotFound_ErrorCode_IsVersionGated(string serverProtocolVersion, McpErrorCode expectedCode)
+    {
+        var resource = McpServerResource.Create(
+            options: new() { UriTemplate = "test://known/{id}" },
+            method: (string id) => $"ok: {id}");
+
+        var client = await CreateClientWithResourcesAndServerVersionAsync(serverProtocolVersion, resource);
+
+        var ex = await Assert.ThrowsAsync<McpProtocolException>(async () =>
+            await client.ReadResourceAsync("test://unknown", null, TestContext.Current.CancellationToken));
+
+        Assert.Equal(expectedCode, ex.ErrorCode);
     }
 
     /// <summary>
@@ -63,8 +119,10 @@ private async Task AssertNoMatchAsync(
     [Fact]
     public async Task MultipleTemplatedResources_MatchesCorrectResource()
     {
-        // Register templates from most specific to least specific
-        var client = await CreateClientWithResourcesAsync(
+        // Server pinned to the SEP-2164-aware protocol version so the no-match assertion at
+        // the bottom of this test sees InvalidParams rather than the legacy ResourceNotFound.
+        var client = await CreateClientWithResourcesAndServerVersionAsync(
+            "2026-06-30",
             McpServerResource.Create(options: new() { UriTemplate = "test://resource/non-templated" }, method: () => "static"),
             McpServerResource.Create(options: new() { UriTemplate = "test://resource/{id}" }, method: (string id) => $"template: {id}"),
             McpServerResource.Create(options: new() { UriTemplate = "test://params{?a1,a2,a3}" }, method: (string a1, string a2, string a3) => $"params: {a1}, {a2}, {a3}"),
@@ -92,7 +150,7 @@ public async Task MultipleTemplatedResources_MatchesCorrectResource()
 
         // Literal template braces in URI should not match (template literal is not a valid URI)
         var mcpEx = await Assert.ThrowsAsync<McpProtocolException>(async () => await client.ReadResourceAsync("test://params{?a1,a2,a3}", null, TestContext.Current.CancellationToken));
-        Assert.Equal(McpErrorCode.ResourceNotFound, mcpEx.ErrorCode);
+        Assert.Equal(McpErrorCode.InvalidParams, mcpEx.ErrorCode);
         Assert.Equal("Request failed (remote): Unknown resource URI: 'test://params{?a1,a2,a3}'", mcpEx.Message);
     }
 

tests/ModelContextProtocol.Tests/McpProtocolExceptionDataTests.cs

@@ -33,7 +33,7 @@ protected override void ConfigureServices(ServiceCollection services, IMcpServer
             switch (toolName)
             {
                 case "throw_with_serializable_data":
-                    throw new McpProtocolException("Resource not found", McpErrorCode.ResourceNotFound)
+                    throw new McpProtocolException("Resource not found", McpErrorCode.InvalidParams)
                     {
                         Data =
                         {
@@ -43,7 +43,7 @@ protected override void ConfigureServices(ServiceCollection services, IMcpServer
                     };
 
                 case "throw_with_nonserializable_data":
-                    throw new McpProtocolException("Resource not found", McpErrorCode.ResourceNotFound)
+                    throw new McpProtocolException("Resource not found", McpErrorCode.InvalidParams)
                     {
                         Data =
                         {
@@ -55,7 +55,7 @@ protected override void ConfigureServices(ServiceCollection services, IMcpServer
                     };
 
                 case "throw_with_only_nonserializable_data":
-                    throw new McpProtocolException("Resource not found", McpErrorCode.ResourceNotFound)
+                    throw new McpProtocolException("Resource not found", McpErrorCode.InvalidParams)
                     {
                         Data =
                         {
@@ -79,7 +79,7 @@ public async Task Exception_With_Serializable_Data_Propagates_To_Client()
             await client.CallToolAsync("throw_with_serializable_data", cancellationToken: TestContext.Current.CancellationToken));
 
         Assert.Equal("Request failed (remote): Resource not found", exception.Message);
-        Assert.Equal(McpErrorCode.ResourceNotFound, exception.ErrorCode);
+        Assert.Equal(McpErrorCode.InvalidParams, exception.ErrorCode);
 
         // Verify the data was propagated to the exception
         // The Data collection should contain the expected keys
@@ -113,7 +113,7 @@ public async Task Exception_With_NonSerializable_Data_Still_Propagates_Error_To_
             await client.CallToolAsync("throw_with_nonserializable_data", cancellationToken: TestContext.Current.CancellationToken));
 
         Assert.Equal("Request failed (remote): Resource not found", exception.Message);
-        Assert.Equal(McpErrorCode.ResourceNotFound, exception.ErrorCode);
+        Assert.Equal(McpErrorCode.InvalidParams, exception.ErrorCode);
 
         // Verify that only the serializable data was propagated (non-serializable was filtered out)
         var hasUri = false;
@@ -142,7 +142,7 @@ public async Task Exception_With_Only_NonSerializable_Data_Still_Propagates_Erro
             await client.CallToolAsync("throw_with_only_nonserializable_data", cancellationToken: TestContext.Current.CancellationToken));
 
         Assert.Equal("Request failed (remote): Resource not found", exception.Message);
-        Assert.Equal(McpErrorCode.ResourceNotFound, exception.ErrorCode);
+        Assert.Equal(McpErrorCode.InvalidParams, exception.ErrorCode);
 
         // When all data is non-serializable, the Data collection should be empty
         // (the server's ConvertExceptionData returns null when no serializable data exists)

tests/ModelContextProtocol.Tests/Server/McpServerTests.cs

@@ -1033,7 +1033,7 @@ await transport.SendMessageAsync(
     public async Task Can_Handle_Call_Tool_Requests_With_McpProtocolException_And_Data()
     {
         const string ErrorMessage = "Resource not found";
-        const McpErrorCode ErrorCode = McpErrorCode.ResourceNotFound;
+        const McpErrorCode ErrorCode = McpErrorCode.InvalidParams;
         const string ResourceUri = "file:///path/to/resource";
 
         await using var transport = new TestServerTransport();