mcp: a response that has already arrived is discarded when the caller's context is cancelled during decoding, and notifications/cancelled is sent for the completed request

Start with the three failing tests named in the logs: TestAwaitPrefersDeliveredResponse in internal/jsonrpc2/conn_test.go, TestAwaitPrefersDeliveredError, and TestCallKeepsDeliveredResponseOnCancel in mcp/transport_test.go. The race sits in the cancellation check in call (mcp/transport.go, about line 306) and the two-way select in AsyncCall.Await (internal/jsonrpc2/conn.go, about line 434). Done means those tests pass and a completed request no longer produces notifications/cancelled.

Describe the bug

ClientSession methods such as ListTools and CallTool can return context.Canceled for a request whose response the client has already received and decoded. The result is lost. The client then sends notifications/cancelled for a request that is not in progress any more.

Two things combine to produce this:

1. call in mcp/transport.go tests ctx.Err() != nil before it tests err == nil (mcp/transport.go:306 on main 3c08147). When Await returns nil because the response arrived and decoded, but the context was cancelled while json.Unmarshal was running, call takes the cancellation branch anyway. It retires the call, returns ctx.Err() and sends notifications/cancelled in a goroutine.
2. AsyncCall.Await in internal/jsonrpc2/conn.go:434 selects between ctx.Done() and ac.ready with no preference. When both are ready, Go picks one at random, so a response that is already in hand is reported as a cancellation about half the time.

The window is the time it takes to decode the result. A large tools/list result makes it several milliseconds wide, but any call is affected when a deadline expires right as its response lands.

To Reproduce

1. Connect a client to an in-memory server that exposes a few thousand tools so the result takes a while to decode.
2. Wrap the client transport so that the caller's context is cancelled on the first Read after the tools/list response has been returned from Read. At that point jsonrpc2 has already retired the call with its result, because the read loop dispatches a message before it reads the next one.
3. Call ListTools with that context.

package main

import (
	"context"
	"fmt"
	"log"
	"sync"
	"time"

	"github.com/modelcontextprotocol/go-sdk/jsonrpc"
	"github.com/modelcontextprotocol/go-sdk/mcp"
)

// cancelAfterResponse cancels ctx on the first Read after the response to
// tools/list has been delivered, and records what the client writes.
type cancelAfterResponse struct {
	mcp.Transport
	cancel context.CancelFunc
	mu     sync.Mutex
	ids    map[int64]string
	wrote  []string
}

func (t *cancelAfterResponse) Connect(ctx context.Context) (mcp.Connection, error) {
	c, err := t.Transport.Connect(ctx)
	if err != nil {
		return nil, err
	}
	t.ids = map[int64]string{}
	return &conn{Connection: c, t: t}, nil
}

type conn struct {
	mcp.Connection
	t         *cancelAfterResponse
	delivered bool
}

func (c *conn) Read(ctx context.Context) (jsonrpc.Message, error) {
	if c.delivered {
		c.delivered = false
		c.t.cancel()
	}
	m, err := c.Connection.Read(ctx)
	if r, ok := m.(*jsonrpc.Response); ok {
		c.t.mu.Lock()
		c.delivered = c.t.ids[r.ID.Raw().(int64)] == "tools/list"
		c.t.mu.Unlock()
	}
	return m, err
}

func (c *conn) Write(ctx context.Context, m jsonrpc.Message) error {
	if r, ok := m.(*jsonrpc.Request); ok {
		c.t.mu.Lock()
		if id, ok := r.ID.Raw().(int64); ok {
			c.t.ids[id] = r.Method
		}
		c.t.wrote = append(c.t.wrote, r.Method)
		c.t.mu.Unlock()
	}
	return c.Connection.Write(ctx, m)
}

func main() {
	ctx := context.Background()
	server := mcp.NewServer(&mcp.Implementation{Name: "s", Version: "0"}, &mcp.ServerOptions{PageSize: 3000})
	for i := range 3000 {
		server.AddTool(&mcp.Tool{Name: fmt.Sprintf("tool-%04d", i), InputSchema: map[string]any{"type": "object"}},
			func(context.Context, *mcp.CallToolRequest) (*mcp.CallToolResult, error) {
				return &mcp.CallToolResult{Content: []mcp.Content{&mcp.TextContent{Text: "ok"}}}, nil
			})
	}
	ct, st := mcp.NewInMemoryTransports()
	if _, err := server.Connect(ctx, st, nil); err != nil {
		log.Fatal(err)
	}
	callCtx, cancel := context.WithCancel(ctx)
	defer cancel()
	tr := &cancelAfterResponse{Transport: ct, cancel: cancel}
	cs, err := mcp.NewClient(&mcp.Implementation{Name: "c", Version: "0"}, nil).Connect(ctx, tr, nil)
	if err != nil {
		log.Fatal(err)
	}
	defer cs.Close()

	res, err := cs.ListTools(callCtx, nil)
	fmt.Println("error:", err)
	if res != nil {
		fmt.Println("tools:", len(res.Tools))
	}
	// The cancelled notification is written from a goroutine; give it a moment.
	time.Sleep(100 * time.Millisecond)
	fmt.Println("written:", tr.wrote)
}

Output on v1.8.0 and on main (3c08147), every run:

error: context canceled
written: [server/discover tools/list notifications/cancelled]

With a timing-based variant (cancel 50 µs to 1 ms after Read returned a 10 000-tool response, 20 runs per delay) the result was lost 20/20 times and notifications/cancelled was written 20/20 times on both versions. With the cancel fired after decoding had finished, 0/20 were lost. That pins the window to the decode duration.

Expected behavior

ListTools returns the decoded result. The response was received before the cancellation was observed, so the request is complete. No notifications/cancelled is written for it.

Expected output:

error: <nil>
tools: 3000
written: [server/discover tools/list]

Logs

Regression tests from the fix, run against main before the fix:

--- FAIL: TestAwaitPrefersDeliveredResponse (0.00s)
    conn_test.go:56: iteration 1: Await() = context canceled, want nil for a delivered response
--- FAIL: TestAwaitPrefersDeliveredError (0.00s)
    conn_test.go:74: iteration 0: Await() = context canceled, want bad params
--- FAIL: TestCallKeepsDeliveredResponseOnCancel (0.04s)
    transport_test.go:476: ListTools() = context canceled, want the delivered result

Additional context

Specification, 2025-11-25, Cancellation, Behavior Requirements: "Cancellation notifications MUST only reference requests that: Were previously issued in the same direction; Are believed to still be in-progress."
https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/cancellation

The same requirement in 2026-07-28: https://modelcontextprotocol.io/specification/2026-07-28/basic/patterns/cancellation

Root cause:

• mcp/transport.go:306 (call): case ctx.Err() != nil is evaluated before err == nil.
• internal/jsonrpc2/conn.go:434 (AsyncCall.Await): the two-way select does not prefer a response that is already ready.

This is the client-side counterpart of #1259 (a cancelled request is still answered on the server). It is distinct from #1150, which made the cancellation notification non-blocking. The eager retirement from #1150 is kept by the fix.

SDK versions: v1.8.0 (3f3b699) and main at 3c0814798be7e813740406029e8efef07828f34f (2026-10-09).
Go version: go1.27.1 darwin/arm64.

I have a fix with regression tests ready and will open a pull request.