mcp: align resource not found error code with sep-2164 (#931)

Change the error code returned by ResourceNotFoundError from -32002 to
-32602 (jsonrpc.CodeInvalidParams), aligning with
[SEP-2164](modelcontextprotocol/modelcontextprotocol#2164).

* Not gated with a protocol version check, because the previous error
code was never formally specified and the behaviour varied across SDKs.
* In case clients which rely on the old error code exist, the previous
behaviour can be restored with `MCPGODEBUG=customresnotfounderrcode=1`.
* `CodeResourceNotFound` deprecated since its only purpose going forward
is backward compatibility. The new code should use
`jsonrpc.CodeInvalidParams` directly.
* `CodeResourceNotFound` changed to `var` so it can stay in sync with
`ResourceNotFoundError` and existing code doing `code ==
mcp.CodeResourceNotFound` keeps working in both the default and compat
modes.

Author: yarolegovich

docs/mcpgodebug.md

@@ -18,6 +18,15 @@
 
 ## `MCPGODEBUG` history
 
+### 1.7.0
+
+Options listed below were added and will be removed in the 1.9.0 version of the SDK.
+
+- `customresnotfounderrcode` added. If set to `1`, `ResourceNotFoundError` will
+  use the custom error code `-32002` instead of the standard `-32602` (Invalid
+  Params), restoring the previous behavior. The default behavior was changed to
+  align with SEP-2164 and the JSON-RPC specification.
+
 ### 1.6.0
 
 Options listed below were added and will be removed in the 1.8.0 version of the SDK.

internal/docs/mcpgodebug.src.md

@@ -17,6 +17,15 @@
 
 ## `MCPGODEBUG` history
 
+### 1.7.0
+
+Options listed below were added and will be removed in the 1.9.0 version of the SDK.
+
+- `customresnotfounderrcode` added. If set to `1`, `ResourceNotFoundError` will
+  use the custom error code `-32002` instead of the standard `-32602` (Invalid
+  Params), restoring the previous behavior. The default behavior was changed to
+  align with SEP-2164 and the JSON-RPC specification.
+
 ### 1.6.0
 
 Options listed below were added and will be removed in the 1.8.0 version of the SDK.

mcp/error_test.go

@@ -111,6 +111,22 @@ func TestServerErrors(t *testing.T) {
 	}
 }
 
+// TestResourceNotFoundErrorCode verifies ResourceNotFoundError code and
+// CodeResourceNotFound are -32602 (InvalidParams) per SEP-2164.
+func TestResourceNotFoundErrorCode(t *testing.T) {
+	err := ResourceNotFoundError("file:///test.txt")
+	var rpcErr *jsonrpc.Error
+	if !errors.As(err, &rpcErr) {
+		t.Fatalf("got error type %T, want *jsonrpc.Error", err)
+	}
+	if rpcErr.Code != jsonrpc.CodeInvalidParams {
+		t.Errorf("got error code %d, want %d (InvalidParams)", rpcErr.Code, jsonrpc.CodeInvalidParams)
+	}
+	if CodeResourceNotFound != jsonrpc.CodeInvalidParams {
+		t.Errorf("CodeResourceNotFound = %d, want %d", CodeResourceNotFound, jsonrpc.CodeInvalidParams)
+	}
+}
+
 // TestInputValidationToolError validates that input validation errors (missing
 // required params, wrong types) are returned as tool results with IsError=true,
 // not as JSON-RPC errors. This allows LLMs to see the error and self-correct.

mcp/resource.go

@@ -15,6 +15,7 @@ import (
 	"path/filepath"
 	"strings"
 
+	"github.com/modelcontextprotocol/go-sdk/internal/mcpgodebug"
 	"github.com/modelcontextprotocol/go-sdk/internal/util"
 	"github.com/modelcontextprotocol/go-sdk/jsonrpc"
 	"github.com/yosida95/uritemplate/v3"
@@ -37,8 +38,25 @@ type serverResourceTemplate struct {
 // If it cannot find the resource, it should return the result of calling [ResourceNotFoundError].
 type ResourceHandler func(context.Context, *ReadResourceRequest) (*ReadResourceResult, error)
 
+// customresnotfounderrcode is a compatibility parameter that restores the
+// pre-1.7.0 behavior of [ResourceNotFoundError] and [CodeResourceNotFound],
+// where the error code was a custom -32002. See the documentation for the mcpgodebug
+// package for instructions on how to enable it.
+// The option will be removed in the future version of the SDK.
+var customresnotfounderrcode = mcpgodebug.Value("customresnotfounderrcode")
+
+func init() {
+	if customresnotfounderrcode == "1" {
+		CodeResourceNotFound = -32002
+	}
+}
+
 // ResourceNotFoundError returns an error indicating that a resource being read could
 // not be found.
+//
+// By default, the error code is -32602 (Invalid Params), as specified in the
+// MCP specification (SEP-2164). To restore the pre-1.7.0 release behavior where the
+// error code was -32002, set MCPGODEBUG=customresnotfounderrcode=1.
 func ResourceNotFoundError(uri string) error {
 	return &jsonrpc.Error{
 		Code:    CodeResourceNotFound,

mcp/shared.go

@@ -347,14 +347,22 @@ const (
 	// CodeHeaderMismatch indicates that HTTP headers do not match the corresponding values
 	// in the request body, or that required headers are missing or malformed.
 	CodeHeaderMismatch = -32001
-	// CodeResourceNotFound indicates that a requested resource could not be found.
-	CodeResourceNotFound = -32002
 	// CodeURLElicitationRequired indicates that the server requires URL elicitation
 	// before processing the request. The client should execute the elicitation handler
 	// with the elicitations provided in the error data.
 	CodeURLElicitationRequired = -32042
 )
 
+// CodeResourceNotFound indicates that a requested resource could not be found.
+//
+// By default, the value is -32602 (Invalid Params), as specified in the
+// MCP specification (SEP-2164). To restore the pre-1.7.0 release behavior where the
+// error code was -32002, set MCPGODEBUG=customresnotfounderrcode=1.
+//
+// Deprecated: Use [jsonrpc.CodeInvalidParams] directly. This variable will be
+// removed in a future version.
+var CodeResourceNotFound int64 = jsonrpc.CodeInvalidParams
+
 // URLElicitationRequiredError returns an error indicating that URL elicitation is required
 // before the request can be processed. The elicitations parameter should contain the
 // elicitation requests that must be completed.