fix(server): return -32602 for nonexistent resources (SEP-2164)

Per SEP-2164, the draft spec upgrades resource-not-found handling from
SHOULD return -32002 (2025-11-25) to MUST return -32602 (Invalid params).
The requested URI is included in the error's data.uri so clients can
still distinguish not-found from other invalid-params errors.

ProtocolErrorCode.ResourceNotFound (-32002) is deprecated but remains
exported, since clients SHOULD still accept it from older servers.

Closes #2194

Author: mattzcarey

.changeset/sep-2164-resource-not-found-invalid-params.md

@@ -0,0 +1,6 @@
+---
+'@modelcontextprotocol/server': patch
+'@modelcontextprotocol/core': patch
+---
+
+Resource not found now returns `-32602` (Invalid params) per SEP-2164; `-32002` (`ProtocolErrorCode.ResourceNotFound`) is deprecated. The error includes the requested URI in `data.uri` so clients can still distinguish not-found from other invalid-params errors. Clients SHOULD continue to accept legacy `-32002` from older servers.

packages/core/src/types/enums.ts

@@ -11,6 +11,13 @@ export enum ProtocolErrorCode {
     InternalError = -32_603,
 
     // MCP-specific error codes
+    /**
+     * Legacy error code for reads of nonexistent resources.
+     *
+     * @deprecated Per SEP-2164, servers MUST return {@link ProtocolErrorCode.InvalidParams}
+     * (`-32602`, with the requested URI in `data.uri`) for nonexistent resources. This code
+     * remains exported because clients SHOULD still accept `-32002` from older servers.
+     */
     ResourceNotFound = -32_002,
     /**
      * Processing the request requires a capability the client did not declare

packages/server/src/server/mcp.ts

@@ -406,7 +406,9 @@ export class McpServer {
                 }
             }
 
-            throw new ProtocolError(ProtocolErrorCode.ResourceNotFound, `Resource ${uri} not found`);
+            // SEP-2164: nonexistent resources MUST return -32602 (Invalid params); the
+            // requested URI is included in `data` so clients can distinguish not-found.
+            throw new ProtocolError(ProtocolErrorCode.InvalidParams, `Resource ${uri} not found`, { uri: uri.toString() });
         });
 
         this._resourceHandlersInitialized = true;

test/e2e/requirements.ts

@@ -531,7 +531,8 @@ export const REQUIREMENTS: Record<string, Requirement> = {
     },
     'resources:read:unknown-uri': {
         source: 'https://modelcontextprotocol.io/specification/2025-11-25/server/resources#error-handling',
-        behavior: 'resources/read for an unknown URI returns JSON-RPC error -32002 (resource not found).'
+        behavior: 'resources/read for an unknown URI returns JSON-RPC error -32602 (Invalid params) with the URI in error data.',
+        note: 'SEP-2164: the draft spec upgrades this to MUST -32602 (2025-11-25 said SHOULD -32002); clients SHOULD still accept legacy -32002 from older servers.'
     },
     'resources:subscribe:capability-required': {
         source: 'https://modelcontextprotocol.io/specification/2025-11-25/server/resources#capabilities',

test/e2e/scenarios/resources.test.ts

@@ -203,8 +203,10 @@ verifies('resources:read:unknown-uri', async ({ transport }: TestArgs) => {
     await using _ = await wire(transport, makeServer, client);
 
     await expect(client.readResource({ uri: 'file:///no-such-resource' })).rejects.toMatchObject({
-        code: -32_002,
-        message: expect.stringMatching(/not found|unknown/i)
+        // SEP-2164: nonexistent resources return -32602 (Invalid params) with the URI in `data`
+        code: -32_602,
+        message: expect.stringMatching(/not found|unknown/i),
+        data: { uri: 'file:///no-such-resource' }
     });
 });
 

test/integration/test/server/mcp.test.ts

@@ -2728,8 +2728,10 @@ describe('Zod v4', () => {
                     }
                 })
             ).rejects.toMatchObject({
-                code: ProtocolErrorCode.ResourceNotFound,
-                message: expect.stringContaining('not found')
+                // SEP-2164: nonexistent resources return -32602 (Invalid params) with the URI in `data`
+                code: ProtocolErrorCode.InvalidParams,
+                message: expect.stringContaining('not found'),
+                data: { uri: 'test://nonexistent' }
             });
         });