fix(core): restore the v1 content default for tools/call results on the legacy era (#2456)

Author: felixweinberger

.changeset/calltoolresult-content-default.md

@@ -0,0 +1,14 @@
+---
+'@modelcontextprotocol/core-internal': patch
+'@modelcontextprotocol/client': patch
+'@modelcontextprotocol/core': patch
+'@modelcontextprotocol/server': patch
+---
+
+Restore the v1 parse tolerance for `CallToolResult.content`: an inbound legacy-era `tools/call` result without `content` defaults to `[]` instead of failing validation. Deployed servers — accepted by SDK v1 for years — return `structuredContent`-only (or otherwise content-less) results, and the strict parse turned every such call into an `INVALID_RESULT` error before application code could run.
+
+The silent-empty-success hazard the strictness guarded is preserved where it matters: the 2025 era's wire-seam schema refuses to default `content` for a body carrying another result family's vocabulary (`task`, `inputRequests`, `requestState` — the era is frozen, so the list is complete), and the 2026-era wire schemas stay strict — modern-revision servers have no legacy excuse. Task interop through an explicit result schema is untouched (including bodies that also stamp a foreign `resultType`), and the server-side authoring normalization refuses the same foreign-family vocabulary.
+
+Server-side authoring is era-independent: a handler result without `content` (dynamic/JS callers — the TypeScript surface requires it) is normalized to `content: []` before era validation on every leg, reaching the wire spec-valid.
+
+Conscious call: the nested sampling `ToolResultContentSchema` stays spec-strict — v1 had defaulted its `content` too, but it is params-side (tool results a caller authors into a sampling message), deliberately not restored.

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

@@ -340,9 +340,11 @@ If you were on a v2 alpha and consumed wire schemas directly:
 
 The `resultType` / `EmptyResultSchema` / `specTypeSchemas` rules above have **no v1.x
 impact** — these members did not exist before 2026-07-28. The neutral-model wire
-tightening that **does** affect v1 code (`content` required, custom-handler `_meta`
-passthrough, `specTypeSchemas` narrowing) is in
-[upgrade-to-v2.md › Wire tightening](./upgrade-to-v2.md#wire-tightening-every-era).
+tightening that **does** affect v1 code (custom-handler `_meta` passthrough,
+`specTypeSchemas` narrowing) is in
+[upgrade-to-v2.md › Wire tightening](./upgrade-to-v2.md#wire-tightening-every-era);
+`CallToolResult.content` keeps its v1 default on the legacy era (2026-07-28
+connections require it explicitly).
 
 > **If you were on a v2 alpha:** the 2026-07-28 draft error codes were renumbered:
 > `HeaderMismatch` `-32001`→`-32020`, `MissingRequiredClientCapability` `-32003`→`-32021`,

docs/migration/upgrade-to-v2.md

@@ -1673,10 +1673,16 @@ requests, the per-request `_meta.logLevel` envelope key is the filter — see
 
 #### Wire tightening (every era)
 
-- **`CallToolResult.content` is required at the wire boundary.** The `content.default([])`
-  affordance was removed. Tool handlers MUST include `content` (the TypeScript surface
-  always required it; `content: []` is fine). A handler result without it is rejected
-  with `-32602`.
+- **`CallToolResult.content` keeps the v1 parse tolerance on the legacy era.** An
+  inbound result without `content` defaults to `[]` (deployed servers omit it
+  alongside `structuredContent`); 2026-07-28 connections stay strict. Authoring is
+  unchanged and era-independent: the TypeScript surface requires `content` on handler
+  results, and a content-less handler result is normalized to `content: []` before it
+  reaches the wire. One sharpening remains: a content-less body carrying another
+  result family's vocabulary (a task handle or an `input_required` round) is still
+  rejected loudly — tolerance never turns a different result kind into a silent empty
+  success. A body whose only foreign key was `resultType` strips to an empty object
+  and defaults, exactly as v1 parsed a payload-free body.
 - **`ElicitResult.content` values are typed and validated as
   `string | number | boolean | string[]`.** v1's TypeScript surface accepted
   `Record<string, unknown>` content values; an elicitation handler returning arbitrary

packages/core-internal/eslint.config.mjs

@@ -7,7 +7,9 @@ export default [
     {
         // Wire-layer isolation, outbound direction: nothing outside src/wire/ may
         // reach into a wire revision module. The wire layer's only public surface
-        // is src/wire/codec.ts (the WireCodec interface) and src/wire/bootstrap.ts.
+        // is src/wire/codec.ts (the WireCodec interface), src/wire/bootstrap.ts,
+        // and the leaf result-family module src/wire/resultFamilies.ts (the shared
+        // tools/call-result ruling, re-exported on the barrel).
         // test/wire/layeringInvariants.test.ts re-derives the same invariant with
         // zero exceptions. Type-only imports are exempted at the lint layer (a
         // type-only crossing is erased at runtime), but the test allows none.

packages/core-internal/src/index.ts

@@ -28,11 +28,15 @@ export * from './util/inMemory';
 // 2026-only seam runs in. NOTHING per-revision (registries, codec objects,
 // per-revision schemas) is ever exported on this barrel — sibling packages
 // reach the wire layer ONLY through `codecForVersion`'s function-only
-// `WireCodec` surface.
+// `WireCodec` surface. Sole exemption: the shared result-family ruling
+// (`wire/resultFamilies.ts`), era-independent by design — the server's
+// authoring normalization and the e2e wire sniffer apply the same ruling
+// (and name the same vocabulary) as the 2025 wire seam.
 export * from './util/schema';
 export * from './util/standardSchema';
 export * from './util/zodCompat';
 export { codecForVersion, MODERN_WIRE_REVISION } from './wire/codec';
+export { normalizeContentlessToolResult, TOOL_RESULT_FOREIGN_FAMILY_KEYS } from './wire/resultFamilies';
 
 // Validator provider classes stay subpath-only. Re-exporting them here, even as
 // `type`, can make generated client/server root declarations advertise

packages/core-internal/src/types/guards.ts

@@ -84,7 +84,9 @@ export const isJSONRPCResponse = (value: unknown): value is JSONRPCResponse => J
  * @returns True if the value is a valid {@linkcode CallToolResult}, false otherwise.
  */
 export const isCallToolResult = (value: unknown): value is CallToolResult => {
-    if (typeof value !== 'object' || value === null || !('content' in value)) return false;
+    // content === undefined covers an explicit undefined key too: the schema's
+    // .default([]) would parse it, but the narrowed type requires the array.
+    if (typeof value !== 'object' || value === null || (value as { content?: unknown }).content === undefined) return false;
     return CallToolResultSchema.safeParse(value).success;
 };
 

packages/core-internal/src/types/schemas.ts

@@ -1381,8 +1381,11 @@ export const CallToolResultSchema = ResultSchema.extend({
      *
      * If the `Tool` does not define an outputSchema, this field MUST be present in the result.
      * Required on the wire per the specification (it may be an empty array).
+     *
+     * Parse-tolerant: absent `content` defaults to `[]` (v1 parity — deployed
+     * servers omit it alongside `structuredContent`).
      */
-    content: z.array(ContentBlockSchema),
+    content: z.array(ContentBlockSchema).default([]),
 
     /**
      * Structured tool output.

packages/core-internal/src/wire/resultFamilies.ts

@@ -0,0 +1,24 @@
+/**
+ * Result-family keys that must never default into a `{content: []}` tools/call
+ * success. Shared by the 2025 wire-seam schema and server normalization.
+ * Leaf module (like `textFallback.ts`): imported by registry/server paths, so
+ * it must NOT import from `./codec.js` — that would close a runtime cycle.
+ */
+export const TOOL_RESULT_FOREIGN_FAMILY_KEYS = ['task', 'inputRequests', 'requestState'] as const;
+
+/**
+ * Single owner of the v1-parity ruling: a plain-object tool result without `content` (and
+ * without foreign-family keys) gains `content: []`. Shared by the 2025 wire seam and server-side handler normalization.
+ */
+export function normalizeContentlessToolResult(value: unknown): unknown {
+    if (
+        value === null ||
+        typeof value !== 'object' ||
+        Array.isArray(value) ||
+        (value as { content?: unknown }).content !== undefined ||
+        TOOL_RESULT_FOREIGN_FAMILY_KEYS.some(key => key in value)
+    ) {
+        return value;
+    }
+    return { ...value, content: [] };
+}

packages/core-internal/src/wire/rev2025-11-25/codec.ts

@@ -105,8 +105,9 @@ export const rev2025Codec: WireCodec = {
 
     decodeResult(_method: string, raw: unknown): DecodedResult {
         // Strip-on-lift (Q1-SD3 ii): a foreign `resultType` on the 2025 leg is
-        // dropped before validation, whatever its value. There is no
-        // discrimination on this era — `resultType` carries no meaning here.
+        // dropped before validation, whatever its value. Validation judges the
+        // husk — the registry wire-seam schema on the plain path, the caller's
+        // schema on the explicit path (task interop).
         if (isPlainObject(raw) && 'resultType' in raw) {
             const stripped = { ...raw };
             delete stripped['resultType'];

packages/core-internal/src/wire/rev2025-11-25/registry.ts

@@ -21,9 +21,10 @@
  * shells, `resultType`, the `_meta` envelope) has NO entry and NO code path
  * here — the inverse-leak guarantee is physical absence, not discipline.
  */
-import type * as z from 'zod/v4';
+import * as z from 'zod/v4';
 
 import type { NotificationMethod, NotificationTypeMap, RequestMethod, RequestTypeMap, ResultTypeMap } from '../../types/types';
+import { normalizeContentlessToolResult, TOOL_RESULT_FOREIGN_FAMILY_KEYS } from '../resultFamilies';
 import type { ClientNotificationSchema, ClientRequestSchema, ServerNotificationSchema, ServerRequestSchema } from './schemas';
 import {
     CallToolRequestSchema,
@@ -106,6 +107,31 @@ type Rev2025TypedRequestMethod = Extract<RequestMethod, Rev2025RequestMethod>;
 // no key may fall outside it (no `tasks/*` entries — the task methods are
 // 2025-11-25 wire vocabulary with no SDK runtime; callers needing task
 // interop pass an explicit schema).
+/**
+ * Wire seam: owns both halves of the v1-parity ruling — the guard (a content-less body
+ * carrying another result family's keys fails loudly; the era is frozen so the key list is
+ * complete) and the tolerance (`content` defaults to `[]`). The era file stays twin-conformant.
+ */
+export const CallToolResultWireSchema = z
+    .unknown()
+    .superRefine((value, ctx) => {
+        // content === undefined covers both an absent key and an explicit
+        // undefined from server-side authoring objects.
+        if (typeof value !== 'object' || value === null || Array.isArray(value) || (value as Record<string, unknown>).content !== undefined)
+            return;
+        for (const key of TOOL_RESULT_FOREIGN_FAMILY_KEYS) {
+            if (key in value) {
+                ctx.addIssue({
+                    code: 'custom',
+                    message: `content is required when the body carries '${key}' — another result family cannot default into an empty tools/call success`
+                });
+                return;
+            }
+        }
+    })
+    .transform(normalizeContentlessToolResult)
+    .pipe(CallToolResultSchema);
+
 const resultSchemas: { readonly [M in Rev2025TypedRequestMethod]: z.ZodType<ResultTypeMap[M]> } = {
     ping: EmptyResultSchema,
     initialize: InitializeResultSchema,
@@ -118,7 +144,7 @@ const resultSchemas: { readonly [M in Rev2025TypedRequestMethod]: z.ZodType<Resu
     'resources/read': ReadResourceResultSchema,
     'resources/subscribe': EmptyResultSchema,
     'resources/unsubscribe': EmptyResultSchema,
-    'tools/call': CallToolResultSchema,
+    'tools/call': CallToolResultWireSchema,
     'tools/list': ListToolsResultSchema,
     'sampling/createMessage': CreateMessageResultWithToolsSchema,
     'elicitation/create': ElicitResultSchema,