mcp: Implement server-side support for discover method (SEP-2575)

docs/mcpgodebug.md

@@ -39,6 +39,12 @@ Options listed below were added and will be removed in the 1.9.0 version of the
   restoring the previous behavior. The default behavior was changed so that
   stateless servers ignore session IDs entirely and reject `DELETE` with 405.
 
+- `nomethodnotfoundcodeinerror` added. If set to `1`, the jsonrpc2 layer will not
+  include the MethodNotFound Error (`-32601`) in the error response when the 
+  requested method in STDIO transport is not found. The default behavior was
+  changed to include the MethodNotFound Error in the error response when the
+  requested method in STDIO transport is not found.
+
 ### 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

@@ -38,6 +38,12 @@ Options listed below were added and will be removed in the 1.9.0 version of the
   restoring the previous behavior. The default behavior was changed so that
   stateless servers ignore session IDs entirely and reject `DELETE` with 405.
 
+- `nomethodnotfoundcodeinerror` added. If set to `1`, the jsonrpc2 layer will not
+  include the MethodNotFound Error (`-32601`) in the error response when the 
+  requested method in STDIO transport is not found. The default behavior was
+  changed to include the MethodNotFound Error in the error response when the
+  requested method in STDIO transport is not found.
+
 ### 1.6.0
 
 Options listed below were added and will be removed in the 1.8.0 version of the SDK.

internal/jsonrpc2/conn.go

@@ -14,8 +14,25 @@ import (
 	"time"
 
 	"github.com/modelcontextprotocol/go-sdk/internal/json"
+	"github.com/modelcontextprotocol/go-sdk/internal/mcpgodebug"
 )
 
+// nomethodnotfoundcodeinerror is a compatibility parameter that restores the
+// pre-fix behavior of [processResult], where wrapped [ErrNotHandled] or
+// [ErrMethodNotFound] errors returned by request handlers were not
+// recognized as "method not found" signals. The original switch statement
+// compared sentinel errors with ==, which never matched errors returned via
+// fmt.Errorf("%w: ...", ErrNotHandled, ...) — including the ones produced
+// by checkRequest. As a result the wire error response carried code 0
+// instead of code -32601. The fix uses errors.Is to recognize wrapped
+// sentinels and append the method name to the message.
+//
+// To restore the previous behavior, set MCPGODEBUG=nomethodnotfoundcodeinerror=1.
+// This option will be removed in a future SDK version.
+// See the documentation for the mcpgodebug package for instructions on how
+// to use it.
+var nomethodnotfoundcodeinerror = mcpgodebug.Value("nomethodnotfoundcodeinerror")
+
 // Connection manages the jsonrpc2 protocol, connecting responses back to their
 // calls. Connection is bidirectional; it does not have a designated server or
 // client end.
@@ -648,9 +665,7 @@ func (c *Connection) handleAsync() {
 
 // processResult processes the result of a request and, if appropriate, sends a response.
 func (c *Connection) processResult(from any, req *incomingRequest, result any, err error) error {
-	switch err {
-	case ErrNotHandled, ErrMethodNotFound:
-		// Add detail describing the unhandled method.
+	if nomethodnotfoundcodeinerror != "1" && (errors.Is(err, ErrNotHandled) || errors.Is(err, ErrMethodNotFound)) {
 		err = fmt.Errorf("%w: %q", ErrMethodNotFound, req.Method)
 	}
 

internal/jsonrpc2/wire.go

@@ -33,7 +33,7 @@ var (
 	// ErrServerClosing is returned for calls that arrive while the server is closing.
 	ErrServerClosing = NewError(-32006, "server is closing")
 	// ErrClientClosing is a dummy error returned for calls initiated while the client is closing.
-	ErrClientClosing = NewError(-32003, "client is closing")
+	ErrClientClosing = NewError(-32007, "client is closing")
 
 	// The following errors have special semantics for MCP transports
 

mcp/client_test.go

@@ -8,6 +8,7 @@ import (
 	"context"
 	"fmt"
 	"log/slog"
+	"slices"
 	"sync/atomic"
 	"testing"
 
@@ -677,6 +678,17 @@ func TestClientConnectDiscover(t *testing.T) {
 			wantInitialize: true,
 			wantVersion:    latestProtocolVersion,
 		},
+		{
+			name: "unsupported protocol version falls back to initialize",
+			discoverHandler: func() (Result, error) {
+				return nil, &jsonrpc.Error{
+					Code:    CodeUnsupportedProtocolVersion,
+					Message: "unsupported protocol version",
+				}
+			},
+			wantInitialize: true,
+			wantVersion:    latestProtocolVersion,
+		},
 		{
 			name: "no overlapping supported version falls back to initialize",
 			discoverHandler: func() (Result, error) {
@@ -772,6 +784,10 @@ func TestClientConnectDiscover(t *testing.T) {
 // request sent by Client.Connect carries the SEP-2575 per-request _meta triple:
 // protocolVersion, clientInfo, and clientCapabilities.
 func TestClientConnectDiscover_RequestContents(t *testing.T) {
+	orig := supportedProtocolVersions
+	supportedProtocolVersions = append([]string{protocolVersion20260630}, slices.Clone(orig)...)
+	t.Cleanup(func() { supportedProtocolVersions = orig })
+
 	ctx := context.Background()
 
 	type captured struct {
@@ -841,3 +857,242 @@ func TestClientConnectDiscover_RequestContents(t *testing.T) {
 		t.Errorf("clientCapabilities.sampling missing (CreateMessageHandler was set); got %v", caps)
 	}
 }
+
+// TestInMemory_E2E_DiscoverSuccess is a full end-to-end smoke test for
+// SEP-2575 over a non-HTTP transport.
+func TestInMemory_E2E_DiscoverSuccess(t *testing.T) {
+	ctx := context.Background()
+
+	orig := supportedProtocolVersions
+	supportedProtocolVersions = append([]string{protocolVersion20260630}, slices.Clone(orig)...)
+	t.Cleanup(func() { supportedProtocolVersions = orig })
+
+	server := NewServer(&Implementation{Name: "stdio-like-server", Version: "v1"}, nil)
+	ct, st := NewInMemoryTransports()
+	ss, err := server.Connect(ctx, st, nil)
+	if err != nil {
+		t.Fatalf("server.Connect: %v", err)
+	}
+	defer ss.Close()
+
+	client := NewClient(&Implementation{Name: "stdio-like-client", Version: "v1"}, nil)
+	cs, err := client.Connect(ctx, ct, &ClientSessionOptions{protocolVersion: protocolVersion20260630})
+	if err != nil {
+		t.Fatalf("client.Connect: %v", err)
+	}
+	defer cs.Close()
+
+	ir := cs.InitializeResult()
+	if ir == nil {
+		t.Fatal("InitializeResult is nil; discover should have populated it")
+	}
+	if ir.ProtocolVersion != protocolVersion20260630 {
+		t.Errorf("InitializeResult.ProtocolVersion = %q, want %q (negotiated via discover, no initialize)",
+			ir.ProtocolVersion, protocolVersion20260630)
+	}
+	if ir.ServerInfo == nil || ir.ServerInfo.Name != "stdio-like-server" {
+		t.Errorf("InitializeResult.ServerInfo = %+v, want name=stdio-like-server", ir.ServerInfo)
+	}
+
+	// Prove the session is usable.
+	if _, err := cs.ListTools(ctx, nil); err != nil {
+		t.Errorf("ListTools after discover: %v", err)
+	}
+}
+
+// TestInMemory_E2E_DiscoverFallback_NoOverlap verifies the fallback path
+// over an InMemory (STDIO-equivalent) transport: the client probes with
+// _meta.protocolVersion = 2026-06-30, but the server's supported list does
+// NOT include that version (the default for an SDK server that hasn't
+// shimmed supportedProtocolVersions).
+func TestInMemory_E2E_DiscoverFallback_NoOverlap(t *testing.T) {
+	ctx := context.Background()
+	orig := supportedProtocolVersions
+	supportedProtocolVersions = append([]string{protocolVersion20260630}, slices.Clone(orig)...)
+	t.Cleanup(func() { supportedProtocolVersions = orig })
+
+	server := NewServer(&Implementation{Name: "vpre-like-server", Version: "v1"}, nil)
+	// Intercept discover and reply as if we were a server that only
+	// supports legacy versions.
+	server.AddReceivingMiddleware(func(next MethodHandler) MethodHandler {
+		return func(ctx context.Context, method string, req Request) (Result, error) {
+			if method == methodDiscover {
+				return &DiscoverResult{
+					SupportedVersions: []string{protocolVersion20251125},
+					Capabilities:      &ServerCapabilities{},
+					ServerInfo:        &Implementation{Name: "vpre-like-server", Version: "v1"},
+				}, nil
+			}
+			return next(ctx, method, req)
+		}
+	})
+
+	ct, st := NewInMemoryTransports()
+	ss, err := server.Connect(ctx, st, nil)
+	if err != nil {
+		t.Fatalf("server.Connect: %v", err)
+	}
+	defer ss.Close()
+
+	client := NewClient(&Implementation{Name: "new-client", Version: "v1"}, nil)
+	cs, err := client.Connect(ctx, ct, &ClientSessionOptions{protocolVersion: protocolVersion20260630})
+	if err != nil {
+		t.Fatalf("client.Connect: %v", err)
+	}
+	defer cs.Close()
+
+	ir := cs.InitializeResult()
+	if ir == nil {
+		t.Fatal("InitializeResult is nil after fallback initialize")
+	}
+	if ir.ProtocolVersion != latestProtocolVersion {
+		t.Errorf("InitializeResult.ProtocolVersion = %q, want %q (legacy fallback after no-overlap discover)",
+			ir.ProtocolVersion, latestProtocolVersion)
+	}
+
+	// Prove the session is usable after fallback.
+	if _, err := cs.ListTools(ctx, nil); err != nil {
+		t.Errorf("ListTools after fallback initialize: %v", err)
+	}
+}
+
+// TestInMemory_E2E_DiscoverFallback_MethodNotFound verifies the fallback
+// path over InMemory when the server doesn't know about server/discover at
+// all (simulating a true pre-SEP-2575 server).
+func TestInMemory_E2E_DiscoverFallback_MethodNotFound(t *testing.T) {
+	ctx := context.Background()
+
+	orig := supportedProtocolVersions
+	supportedProtocolVersions = append([]string{protocolVersion20260630}, slices.Clone(orig)...)
+	t.Cleanup(func() { supportedProtocolVersions = orig })
+
+	server := NewServer(&Implementation{Name: "vpre-server", Version: "v1"}, nil)
+	server.AddReceivingMiddleware(func(next MethodHandler) MethodHandler {
+		return func(ctx context.Context, method string, req Request) (Result, error) {
+			if method == methodDiscover {
+				return nil, jsonrpc2.ErrMethodNotFound
+			}
+			return next(ctx, method, req)
+		}
+	})
+
+	ct, st := NewInMemoryTransports()
+	ss, err := server.Connect(ctx, st, nil)
+	if err != nil {
+		t.Fatalf("server.Connect: %v", err)
+	}
+	defer ss.Close()
+
+	client := NewClient(&Implementation{Name: "new-client", Version: "v1"}, nil)
+	cs, err := client.Connect(ctx, ct, &ClientSessionOptions{protocolVersion: protocolVersion20260630})
+	if err != nil {
+		t.Fatalf("client.Connect: %v", err)
+	}
+	defer cs.Close()
+
+	ir := cs.InitializeResult()
+	if ir == nil {
+		t.Fatal("InitializeResult is nil after fallback initialize")
+	}
+	if ir.ProtocolVersion != latestProtocolVersion {
+		t.Errorf("InitializeResult.ProtocolVersion = %q, want %q (legacy fallback after MethodNotFound)",
+			ir.ProtocolVersion, latestProtocolVersion)
+	}
+
+	if _, err := cs.ListTools(ctx, nil); err != nil {
+		t.Errorf("ListTools after fallback initialize: %v", err)
+	}
+}
+
+// TestInMemory_E2E_DiscoverFallback_UnsupportedProtocolVersion verifies the
+// fallback path when the server explicitly rejects the discover probe with
+// CodeUnsupportedProtocolVersion (the structured SEP-2575 signal). This
+// exercises Path A of the fallback logic in client.go.
+func TestInMemory_E2E_DiscoverFallback_UnsupportedProtocolVersion(t *testing.T) {
+	ctx := context.Background()
+
+	orig := supportedProtocolVersions
+	supportedProtocolVersions = append([]string{protocolVersion20260630}, slices.Clone(orig)...)
+	t.Cleanup(func() { supportedProtocolVersions = orig })
+
+	server := NewServer(&Implementation{Name: "strict-server", Version: "v1"}, nil)
+	server.AddReceivingMiddleware(func(next MethodHandler) MethodHandler {
+		return func(ctx context.Context, method string, req Request) (Result, error) {
+			if method == methodDiscover {
+				return nil, &jsonrpc.Error{
+					Code:    CodeUnsupportedProtocolVersion,
+					Message: "unsupported protocol version",
+				}
+			}
+			return next(ctx, method, req)
+		}
+	})
+
+	ct, st := NewInMemoryTransports()
+	ss, err := server.Connect(ctx, st, nil)
+	if err != nil {
+		t.Fatalf("server.Connect: %v", err)
+	}
+	defer ss.Close()
+
+	client := NewClient(&Implementation{Name: "new-client", Version: "v1"}, nil)
+	cs, err := client.Connect(ctx, ct, &ClientSessionOptions{protocolVersion: protocolVersion20260630})
+	if err != nil {
+		t.Fatalf("client.Connect: %v", err)
+	}
+	defer cs.Close()
+
+	ir := cs.InitializeResult()
+	if ir == nil {
+		t.Fatal("InitializeResult is nil after fallback initialize")
+	}
+	if ir.ProtocolVersion != latestProtocolVersion {
+		t.Errorf("InitializeResult.ProtocolVersion = %q, want %q (legacy fallback after UnsupportedProtocolVersion)",
+			ir.ProtocolVersion, latestProtocolVersion)
+	}
+}
+
+// TestInMemory_E2E_DiscoverPropagatesOtherErrors verifies that an unrelated
+// error from the discover handler aborts Connect and does NOT silently
+// fall back.
+func TestInMemory_E2E_DiscoverPropagatesOtherErrors(t *testing.T) {
+	ctx := context.Background()
+
+	orig := supportedProtocolVersions
+	supportedProtocolVersions = append([]string{protocolVersion20260630}, slices.Clone(orig)...)
+	t.Cleanup(func() { supportedProtocolVersions = orig })
+
+	var sawInitialize atomic.Bool
+	server := NewServer(&Implementation{Name: "broken-server", Version: "v1"}, nil)
+	server.AddReceivingMiddleware(func(next MethodHandler) MethodHandler {
+		return func(ctx context.Context, method string, req Request) (Result, error) {
+			switch method {
+			case methodDiscover:
+				return nil, &jsonrpc.Error{
+					Code:    jsonrpc.CodeInternalError,
+					Message: "boom",
+				}
+			case methodInitialize:
+				sawInitialize.Store(true)
+			}
+			return next(ctx, method, req)
+		}
+	})
+
+	ct, st := NewInMemoryTransports()
+	ss, err := server.Connect(ctx, st, nil)
+	if err != nil {
+		t.Fatalf("server.Connect: %v", err)
+	}
+	defer ss.Close()
+
+	client := NewClient(&Implementation{Name: "new-client", Version: "v1"}, nil)
+	cs, err := client.Connect(ctx, ct, &ClientSessionOptions{protocolVersion: protocolVersion20260630})
+	if err == nil {
+		_ = cs.Close()
+		t.Fatal("Connect succeeded; want propagated discover error")
+	}
+	if sawInitialize.Load() {
+		t.Error("server received initialize; Connect should have aborted on the discover error")
+	}
+}

mcp/mrtr_test.go

@@ -526,27 +526,6 @@ func TestMultiRoundTrip_ReadResource_ManualRetry(t *testing.T) {
 func mustConnect(t *testing.T, s *Server, clientOpts *ClientOptions) *ClientSession {
 	t.Helper()
 
-	// The mrtr tests require negotiating the 2026-06-30 protocol version.
-	// Server.discover is currently a stub that returns ErrMethodNotFound, which
-	// would cause Client.Connect to fall back to the legacy initialize handshake
-	// and downgrade the negotiated version. Install a receiving middleware that
-	// answers server/discover with a DiscoverResult advertising 2026-06-30 so
-	// the client can negotiate the new protocol via the discover path.
-	//
-	// TODO: Remove this once the server has a proper discover implementation.
-	s.AddReceivingMiddleware(func(next MethodHandler) MethodHandler {
-		return func(ctx context.Context, method string, req Request) (Result, error) {
-			if method == methodDiscover {
-				return &DiscoverResult{
-					SupportedVersions: []string{protocolVersion20260630},
-					Capabilities:      &ServerCapabilities{},
-					ServerInfo:        testImpl,
-				}, nil
-			}
-			return next(ctx, method, req)
-		}
-	})
-
 	st, ct := NewInMemoryTransports()
 	ss, err := s.Connect(t.Context(), st, nil)
 	if err != nil {

mcp/protocol.go

@@ -2103,3 +2103,14 @@ const (
 	// MetaKeyClientCapabilities carries the client's [ClientCapabilities].
 	MetaKeyClientCapabilities = "io.modelcontextprotocol/clientCapabilities"
 )
+
+// UnsupportedProtocolVersionData is the SEP-2575 payload carried in the
+// `data` field of a JSON-RPC error response with code
+// [CodeUnsupportedProtocolVersion]. The server uses it to advertise which
+// versions it supports so the client can pick a mutually supported one.
+type UnsupportedProtocolVersionData struct {
+	// Supported is the list of protocol versions the server supports.
+	Supported []string `json:"supported"`
+	// Requested is the protocol version the client asked for.
+	Requested string `json:"requested"`
+}