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

src/Common/McpHttpHeaders.cs

@@ -75,4 +75,12 @@ internal static class McpHttpHeaders
     /// </summary>
     public static bool SupportsStandardHeaders(string? protocolVersion)
         => !string.IsNullOrEmpty(protocolVersion) && s_versionsWithStandardHeaders.Contains(protocolVersion!);
+
+    /// <summary>
+    /// Returns <see langword="true"/> if the negotiated protocol version reports unresolvable
+    /// resource URIs with the standard JSON-RPC <see cref="McpErrorCode.InvalidParams"/> (-32602)
+    /// rather than the legacy <see cref="McpErrorCode.ResourceNotFound"/> (-32002).
+    /// </summary>
+    internal static bool UseInvalidParamsForMissingResource(string? protocolVersion)
+        => string.Equals(protocolVersion, MinVersionForStandardHeaders, StringComparison.Ordinal);
 }

src/ModelContextProtocol.Core/McpErrorCode.cs

@@ -29,8 +29,17 @@ 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. Newer protocol versions report this
+    /// condition with the standard JSON-RPC <see cref="InvalidParams"/> (-32602) instead. The SDK
+    /// selects between the two automatically based on the negotiated protocol version, so older
+    /// clients still see <see cref="ResourceNotFound"/> (-32002) and newer ones see
+    /// <see cref="InvalidParams"/>.
+    /// </para>
+    /// <para>
+    /// New user code throwing <see cref="McpProtocolException"/> directly for unknown-resource conditions
+    /// should prefer <see cref="InvalidParams"/>; the SDK will pass the value through unchanged.
+    /// </para>
     /// </remarks>
     ResourceNotFound = -32002,
 
@@ -85,6 +94,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 class McpProtocolException : McpException
     /// <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/Server/McpServerImpl.cs

@@ -421,7 +421,13 @@ internal sealed partial class McpServerImpl : McpServer
 
         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));
+        readResourceHandler ??= (static async (request, _) =>
+        {
+            var errorCode = McpHttpHeaders.UseInvalidParamsForMissingResource(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;