feat(client): ergonomics batch — UnauthorizedError under auto, logLevel, list page-1, typed era-validation error (#102,#126-128,#168,#169)

Author: felixweinberger

.changeset/client-ergonomics-batch.md

@@ -0,0 +1,12 @@
+---
+"@modelcontextprotocol/core-internal": minor
+"@modelcontextprotocol/client": minor
+---
+
+Client ergonomics batch:
+
+- `connect()` under `versionNegotiation: 'auto'` / `{ pin }` now rejects with `UnauthorizedError` directly when the auth provider rejects the connect-time probe (previously wrapped in `SdkError(VersionNegotiationFailed).data.cause`). `UnauthorizedError` now sets `error.name`.
+- New `ClientOptions.logLevel`: auto-attaches the `io.modelcontextprotocol/logLevel` `_meta` envelope key on 2026-07-28 connections, and sends a single best-effort `logging/setLevel` after a 2025-era handshake when the server advertises `logging`.
+- New `ListRequestOptions.allPages`: pass `{ allPages: false }` to `listTools()` / `listPrompts()` / `listResources()` / `listResourceTemplates()` to fetch only the first page (with its raw `nextCursor`) instead of auto-aggregating.
+- New `SdkErrorCode.ResultProtocolMismatch`: a 2026-07-28 peer result that omits or malforms the REQUIRED `resultType` discriminator now rejects with this code (was `InvalidResult`), so tooling can classify a non-conformant peer separately from a malformed payload.
+- **Breaking (alpha-only):** `SdkErrorCode.EraNegotiationFailed` is renamed to `SdkErrorCode.VersionNegotiationFailed` (string value `'VERSION_NEGOTIATION_FAILED'`).

docs/client.md

@@ -137,7 +137,7 @@ await worker.connect(new StreamableHTTPClientTransport(url), { prior: JSON.parse
 ```
 
 {@linkcode @modelcontextprotocol/client!client/client.Client#getDiscoverResult | client.getDiscoverResult()} returns the value that the `'auto'`/pinned probe path, an explicit {@linkcode @modelcontextprotocol/client!client/client.Client#discover | client.discover()} call, or a
-prior `connect({ prior })` recorded; it round-trips through `JSON.stringify`/`JSON.parse`. `connect({ prior })` is **2026-07-28+ only** — it rejects with `SdkError(EraNegotiationFailed)` when the supplied result and the client share no modern revision. Only reuse a persisted
+prior `connect({ prior })` recorded; it round-trips through `JSON.stringify`/`JSON.parse`. `connect({ prior })` is **2026-07-28+ only** — it rejects with `SdkError(VersionNegotiationFailed)` when the supplied result and the client share no modern revision. Only reuse a persisted
 `DiscoverResult` across clients that present the **same authorization context** as the one that obtained it. See the [`gateway/` example](../examples/gateway/README.md) for the full probe-once / connect-many pattern with a server-side proof.
 
 ### Disconnecting
@@ -298,7 +298,7 @@ try {
     return client;
 } catch (error) {
     // With version negotiation, the connect-time 401 may surface wrapped as
-    // SdkError(EraNegotiationFailed) whose .data.cause is the UnauthorizedError.
+    // SdkError(VersionNegotiationFailed) whose .data.cause is the UnauthorizedError.
     const root = error instanceof UnauthorizedError ? error : (error as { data?: { cause?: unknown } }).data?.cause;
     if (!(root instanceof UnauthorizedError)) throw error;
     // The transport called redirectToAuthorization(); fall through to the browser callback.

docs/migration/support-2026-07-28.md

@@ -47,15 +47,15 @@ client.getProtocolEra(); // 'modern' | 'legacy'
 - **`mode: 'auto'`** — probe with `server/discover`; fall back to the 2025 handshake on
   the same connection against a 2025-only server (one extra round trip).
 - **`mode: { pin: '2026-07-28' }`** — modern only; no fallback, `connect()` rejects with
-  `SdkError(EraNegotiationFailed)` against a 2025-only server.
+  `SdkError(VersionNegotiationFailed)` against a 2025-only server.
 
 #### Probe policy
 
 Failure semantics under `'auto'` are deliberately conservative but never silent about
 infrastructure problems. Anything the probe does not positively recognize as modern
 falls back to the legacy era — provided the supported-versions list still contains a
 2025-era revision; with a modern-only list `connect()` rejects with
-`SdkError(EraNegotiationFailed)` instead. A network outage rejects with a typed connect
+`SdkError(VersionNegotiationFailed)` instead. A network outage rejects with a typed connect
 error. Probe timeouts are **transport-aware**: on **stdio** a server that does not
 answer within `timeoutMs` is treated as legacy and the client falls back to `initialize`
 on the same stream (some legacy servers never respond to unknown pre-`initialize`

docs/migration/upgrade-to-v2.md

@@ -493,11 +493,12 @@ if (error instanceof SdkHttpError) {
 | `ConnectionClosed` | Connection was closed |
 | `SendFailed` | Failed to send message |
 | `InvalidResult` | Response result failed local schema validation |
+| `ResultProtocolMismatch` | The peer returned a result whose shape does not match the negotiated protocol version's schema (e.g. a 2026-07-28 peer omitted the REQUIRED `resultType` discriminator) |
 | `UnsupportedResultType` | A 2026-era response carried an unrecognized `resultType` |
 | `InputRequiredRoundsExceeded` | Multi-round-trip auto-fulfilment hit `maxRounds` |
 | `ListPaginationExceeded` | No-arg `list*()` aggregate walk hit `listMaxPages` |
 | `MethodNotSupportedByProtocolVersion` | Outbound spec method does not exist on the negotiated protocol version |
-| `EraNegotiationFailed` | `connect()` could not negotiate a protocol era (probe failed / no overlap) |
+| `VersionNegotiationFailed` | `connect()` could not negotiate a protocol version (probe failed / no overlap). Auth-required connects throw `UnauthorizedError` directly in every negotiation mode — `VersionNegotiationFailed` is reserved for genuine negotiation failures |
 | `ClientHttpNotImplemented` | HTTP POST request failed |
 | `ClientHttpAuthentication` | Server returned 401 after re-authentication |
 | `ClientHttpForbidden` | Server returned 403 `insufficient_scope` after step-up retry cap |

examples/gateway/README.md

@@ -47,4 +47,4 @@ The server exposes a `request_count` tool returning how many MCP requests reache
 Only reuse a persisted `DiscoverResult` across workers that present the **same authorization context** as the bootstrap client (key the blob on a credential hash). Adopting a wider `prior` does not grant access — the server authorizes every request — but it can mislead
 client-side capability gating.
 
-`connect({ prior })` is **modern-only**: no mutual 2026-07-28+ revision → `SdkError(EraNegotiationFailed)`. Use `versionNegotiation: { mode: 'auto' }` for legacy-era fallback.
+`connect({ prior })` is **modern-only**: no mutual 2026-07-28+ revision → `SdkError(VersionNegotiationFailed)`. Use `versionNegotiation: { mode: 'auto' }` for legacy-era fallback.

examples/guides/clientGuide.examples.ts

@@ -294,7 +294,7 @@ async function auth_finishAuth(url: URL, provider: OAuthClientProvider & { lastS
         return client;
     } catch (error) {
         // With version negotiation, the connect-time 401 may surface wrapped as
-        // SdkError(EraNegotiationFailed) whose .data.cause is the UnauthorizedError.
+        // SdkError(VersionNegotiationFailed) whose .data.cause is the UnauthorizedError.
         const root = error instanceof UnauthorizedError ? error : (error as { data?: { cause?: unknown } }).data?.cause;
         if (!(root instanceof UnauthorizedError)) throw error;
         // The transport called redirectToAuthorization(); fall through to the browser callback.

examples/oauth/client.ts

@@ -115,7 +115,7 @@ try {
 } catch (error) {
     // Under `--legacy` the transport surfaces `UnauthorizedError` directly;
     // under `mode: 'auto'` the version-negotiation probe is what got 401'd
-    // and wraps it in an EraNegotiationFailed `SdkError` whose `data.cause`
+    // and wraps it in an VersionNegotiationFailed `SdkError` whose `data.cause`
     // is the original `UnauthorizedError`. Either way the auth driver has
     // already run by the time we land here — DCR done, auth URL captured.
     const root = error instanceof UnauthorizedError ? error : (error as { data?: { cause?: unknown } }).data?.cause;

packages/client/src/client/auth.ts

@@ -488,6 +488,7 @@ export type AuthResult = 'AUTHORIZED' | 'REDIRECT';
 export class UnauthorizedError extends Error {
     constructor(message?: string) {
         super(message ?? 'Unauthorized');
+        this.name = 'UnauthorizedError';
     }
 }
 

packages/client/src/client/client.ts

@@ -205,6 +205,24 @@ export type ClientOptions = ProtocolOptions & {
      */
     versionNegotiation?: VersionNegotiationOptions;
 
+    /**
+     * Per-request log opt-in. On 2026-07-28 connections the level is attached
+     * to every outgoing request as the `io.modelcontextprotocol/logLevel`
+     * `_meta` envelope key (without it, servers MUST NOT emit
+     * `notifications/message` for the request). On 2025-era connections the
+     * client sends a single best-effort `logging/setLevel` after the handshake
+     * when the server advertises the `logging` capability. A per-call
+     * `params._meta[LOG_LEVEL_META_KEY]` still overrides this default.
+     *
+     * The envelope key rides every outgoing message (notifications included);
+     * it is inert on messages that are not request-scoped logs.
+     *
+     * Note: MCP-level logging is in the SEP-2577 deprecation window; this
+     * option fronts that vocabulary deliberately because it is currently the
+     * only way to receive request-tied server logs on 2026-07-28 connections.
+     */
+    logLevel?: LoggingLevel;
+
     /**
      * Multi-round-trip auto-fulfilment (protocol revision 2026-07-28).
      *
@@ -329,7 +347,7 @@ export type ConnectOptions = RequestOptions & {
      * A previously-obtained {@linkcode DiscoverResult} (see
      * {@linkcode Client.getDiscoverResult}). When supplied, `connect()` adopts
      * it directly — zero round trips. 2026-07-28+ only: throws
-     * `SdkError(EraNegotiationFailed)` when there is no modern overlap. Only
+     * `SdkError(VersionNegotiationFailed)` when there is no modern overlap. Only
      * reuse across clients presenting the same authorization context.
      */
     prior?: DiscoverResult;
@@ -351,6 +369,21 @@ export type CacheableRequestOptions = RequestOptions & {
     cacheMode?: CacheMode;
 };
 
+/**
+ * {@linkcode CacheableRequestOptions} extended with a per-call opt-out of the
+ * list verbs' auto-aggregating walk.
+ */
+export type ListRequestOptions = CacheableRequestOptions & {
+    /**
+     * Set to `false` to fetch only the first page (with its raw `nextCursor`)
+     * instead of walking and aggregating every page. Equivalent to passing an
+     * explicit `{ cursor }` for page 1, which the typed verbs cannot otherwise
+     * express because page 1 has no cursor. The single-page path does not
+     * consult or write the response cache. Default: `true` (auto-aggregate).
+     */
+    allPages?: boolean;
+};
+
 /**
  * Options for {@linkcode Client.callTool}. Extends {@linkcode RequestOptions}
  * with an escape hatch for callers that already hold the tool definition
@@ -503,6 +536,7 @@ export class Client extends Protocol<ClientContext> {
     private readonly _listChangedConfig?: ListChangedHandlers;
     private _enforceStrictCapabilities: boolean;
     private _versionNegotiation?: VersionNegotiationOptions;
+    private readonly _logLevel?: LoggingLevel;
     private _supportedProtocolVersionsOption?: string[];
     private _inputRequiredDriverConfig: ResolvedInputRequiredDriverConfig;
     /**
@@ -585,6 +619,7 @@ export class Client extends Protocol<ClientContext> {
         this._jsonSchemaValidator = options?.jsonSchemaValidator ?? new DefaultJsonSchemaValidator();
         this._enforceStrictCapabilities = options?.enforceStrictCapabilities ?? false;
         this._versionNegotiation = options?.versionNegotiation;
+        this._logLevel = options?.logLevel;
         this._supportedProtocolVersionsOption = options?.supportedProtocolVersions;
         // Multi-round-trip auto-fulfilment driver (2026-07-28): on by default,
         // configurable via ClientOptions.inputRequired.
@@ -653,7 +688,8 @@ export class Client extends Protocol<ClientContext> {
         return this._wireCodec().outboundEnvelope({
             protocolVersion: version,
             clientInfo: this._clientInfo,
-            clientCapabilities: this._capabilities
+            clientCapabilities: this._capabilities,
+            logLevel: this._logLevel
         });
     }
 
@@ -978,7 +1014,7 @@ export class Client extends Protocol<ClientContext> {
             const offeredVersion = legacyVersions[0];
             if (offeredVersion === undefined) {
                 throw new SdkError(
-                    SdkErrorCode.EraNegotiationFailed,
+                    SdkErrorCode.VersionNegotiationFailed,
                     'Cannot run the initialize handshake: supportedProtocolVersions contains no pre-2026-07-28 protocol version'
                 );
             }
@@ -1029,6 +1065,18 @@ export class Client extends Protocol<ClientContext> {
             if (this._listChangedConfig) {
                 this._setupListChangedHandlers(this._listChangedConfig);
             }
+
+            // Legacy half of ClientOptions.logLevel: a single best-effort
+            // logging/setLevel after the handshake when the server advertises
+            // logging. A failure here must not fail connect(). The connect-time
+            // signal/onprogress are deliberately NOT propagated — this request
+            // outlives connect() and a post-resolve abort would surface as a
+            // spurious onerror.
+            if (this._logLevel !== undefined && this._serverCapabilities?.logging) {
+                void this.setLoggingLevel(this._logLevel).catch(error_ =>
+                    this.onerror?.(error_ instanceof Error ? error_ : new Error(String(error_)))
+                );
+            }
         } catch (error) {
             // Disconnect if initialization fails.
             void this.close();
@@ -1187,7 +1235,7 @@ export class Client extends Protocol<ClientContext> {
 
     /**
      * Connect from a previously-obtained {@linkcode DiscoverResult}. Always
-     * zero-round-trip; throws `EraNegotiationFailed` when there is no
+     * zero-round-trip; throws `VersionNegotiationFailed` when there is no
      * 2026-07-28+ overlap (no legacy fallback). See {@linkcode ConnectOptions}.
      */
     private async _connectFromPrior(transport: Transport, prior: DiscoverResult): Promise<void> {
@@ -1199,7 +1247,7 @@ export class Client extends Protocol<ClientContext> {
         const version = clientModern.find(v => prior.supportedVersions.includes(v));
         if (version === undefined) {
             throw new SdkError(
-                SdkErrorCode.EraNegotiationFailed,
+                SdkErrorCode.VersionNegotiationFailed,
                 "connect({ prior }) requires a 2026-07-28+ mutual protocol version; the supplied DiscoverResult and this client's " +
                     "supportedProtocolVersions have no modern overlap. Use versionNegotiation: { mode: 'auto' } for legacy-era fallback."
             );
@@ -1286,6 +1334,16 @@ export class Client extends Protocol<ClientContext> {
      * The {@linkcode DiscoverResult} from the last `'auto'`/pinned probe,
      * {@linkcode discover} call, or `connect({ prior })`. Persistable via
      * `JSON.stringify`; feed to {@linkcode ConnectOptions} `prior`.
+     *
+     * Note on receiver-side leniency: per the 2026-07-28 spec
+     * (caching §TTL — "If `ttlMs` is absent, clients SHOULD assume a default
+     * of `0`"; "If `ttlMs` is negative, clients SHOULD ignore it and treat it
+     * as `0`"), the SDK's discover decoder defaults absent or malformed
+     * `ttlMs` / `cacheScope` to `0` / `'private'` rather than rejecting. This
+     * is deliberately less strict than the `resultType` posture (which has no
+     * such receiver-side SHOULD and rejects when missing). The sender
+     * obligation — `ttlMs >= 0` and `cacheScope` MUST be present — is still
+     * REQUIRED on the wire and is enforced by the SDK server's encode step.
      */
     getDiscoverResult(): DiscoverResult | undefined {
         return this._discoverResult;
@@ -1497,13 +1555,13 @@ export class Client extends Protocol<ClientContext> {
      * );
      * ```
      */
-    async listPrompts(params?: ListPromptsRequest['params'], options?: CacheableRequestOptions): Promise<ListPromptsResult> {
+    async listPrompts(params?: ListPromptsRequest['params'], options?: ListRequestOptions): Promise<ListPromptsResult> {
         if (!this._serverCapabilities?.prompts && !this._enforceStrictCapabilities) {
             // Respect capability negotiation: server does not support prompts
             console.debug('Client.listPrompts() called but server does not advertise prompts capability - returning empty list');
             return { prompts: [] };
         }
-        if (params?.cursor !== undefined) {
+        if (params?.cursor !== undefined || options?.allPages === false) {
             return this.request({ method: 'prompts/list', params }, options);
         }
         const hit = await this._serveFromCache<ListPromptsResult>('prompts/list', undefined, options);
@@ -1537,13 +1595,13 @@ export class Client extends Protocol<ClientContext> {
      * );
      * ```
      */
-    async listResources(params?: ListResourcesRequest['params'], options?: CacheableRequestOptions): Promise<ListResourcesResult> {
+    async listResources(params?: ListResourcesRequest['params'], options?: ListRequestOptions): Promise<ListResourcesResult> {
         if (!this._serverCapabilities?.resources && !this._enforceStrictCapabilities) {
             // Respect capability negotiation: server does not support resources
             console.debug('Client.listResources() called but server does not advertise resources capability - returning empty list');
             return { resources: [] };
         }
-        if (params?.cursor !== undefined) {
+        if (params?.cursor !== undefined || options?.allPages === false) {
             return this.request({ method: 'resources/list', params }, options);
         }
         const hit = await this._serveFromCache<ListResourcesResult>('resources/list', undefined, options);
@@ -1567,7 +1625,7 @@ export class Client extends Protocol<ClientContext> {
      */
     async listResourceTemplates(
         params?: ListResourceTemplatesRequest['params'],
-        options?: CacheableRequestOptions
+        options?: ListRequestOptions
     ): Promise<ListResourceTemplatesResult> {
         if (!this._serverCapabilities?.resources && !this._enforceStrictCapabilities) {
             // Respect capability negotiation: server does not support resources
@@ -1576,7 +1634,7 @@ export class Client extends Protocol<ClientContext> {
             );
             return { resourceTemplates: [] };
         }
-        if (params?.cursor !== undefined) {
+        if (params?.cursor !== undefined || options?.allPages === false) {
             return this.request({ method: 'resources/templates/list', params }, options);
         }
         const hit = await this._serveFromCache<ListResourceTemplatesResult>('resources/templates/list', undefined, options);
@@ -2392,13 +2450,13 @@ export class Client extends Protocol<ClientContext> {
      * );
      * ```
      */
-    async listTools(params?: ListToolsRequest['params'], options?: CacheableRequestOptions): Promise<ListToolsResult> {
+    async listTools(params?: ListToolsRequest['params'], options?: ListRequestOptions): Promise<ListToolsResult> {
         if (!this._serverCapabilities?.tools && !this._enforceStrictCapabilities) {
             // Respect capability negotiation: server does not support tools
             console.debug('Client.listTools() called but server does not advertise tools capability - returning empty list');
             return { tools: [] };
         }
-        if (params?.cursor !== undefined) {
+        if (params?.cursor !== undefined || options?.allPages === false) {
             // Per-page: single request, never written to the response cache.
             // SEP-2243: the spec's MUST has no carve-out for paginated reads,
             // so the per-page result is filtered (on a non-stdio modern