Tool output validation fails when outputSchema is a Zod schema other than ZodObject

[joshjg]

Describe the bug

Tool output validation fails with the following error when the tool's outputSchema is an optional, nullable, nullish, or union schema (or, most likely anything besides a plain object schema).

Cannot read properties of undefined (reading '_zod')

When validating output the SDK attempts to use normalizeObjectSchema, which returns undefined for anything besides object schemas.

To Reproduce
Steps to reproduce the behavior:

1. Define an outputSchema with something other than a plain object or z.object schema.
2. Implement the tool so that it returns structuredContent that conforms to this schema.
3. Invoke the tool.

// Works:
outputSchema: z.object({ data: z.string() })

// Fails:
outputSchema: z.object({ data: z.string() }).optional()
outputSchema: z.object({ data: z.string() }).nullable()
outputSchema: z.object({ data: z.string() }).nullish()
outputSchema: z.union([z.object({ data: z.string() }), z.object({ value: z.string() })])

Expected behavior
The SDK should be able to validate output based on Zod schemas which represent a JSON object, even if it is optional or a union of possible object schemas. Based on the spec, null is not a valid value for structuredContent, so nullable and nullish schemas should not be allowed, either through more restrictive typing of outputSchema or runtime validation with a clear error message.

Logs

    at isZ4Schema ($PROJECT/node_modules/@modelcontextprotocol/sdk/dist/cjs/server/zod-compat.js:46:21)
    at safeParseAsync ($PROJECT/node_modules/@modelcontextprotocol/sdk/dist/cjs/server/zod-compat.js:80:9)
    at McpServer.validateToolOutput ($PROJECT/node_modules/@modelcontextprotocol/sdk/dist/cjs/server/mcp.js:205:70)
    at $PROJECT/node_modules/@modelcontextprotocol/sdk/dist/cjs/server/mcp.js:135:28
    at process.processTicksAndRejections (node:internal/process/task_queues:105:5)
    at async wrappedHandler ($PROJECT/node_modules/@modelcontextprotocol/sdk/dist/cjs/server/index.js:131:32)

Additional context

"@modelcontextprotocol/sdk": "1.24.3",
"zod": "4.1.13"

I was expecting this to work based on #816 but it has possibly regressed with #1040

[KKonstantinov]

Hi, thanks for this, could you please help by providing the generated JSON schema by this?

Currently, the validation of outputSchema is:

outputSchema: z
        .object({
            type: z.literal('object'),
            properties: z.record(z.string(), AssertObjectSchema).optional(),
            required: z.array(z.string()).optional()
        })
        .catchall(z.unknown())
        .optional(),

Which matches

https://github.com/modelcontextprotocol/modelcontextprotocol/blob/11a026d882003053b86ce47ac88f296c2bc5ee80/schema/2025-11-25/schema.ts#L1277

But we'd need to check what schema is generated from .nullable, .nullish etc.

[sstklen]

Hey! I ran into a similar pattern in our bug knowledge base and thought this might help.

What's happening: Module resolution mismatch between ESM and CJS builds in @modelcontextprotocol/sdk package, likely due to incorrect package.json exports or build configuration

What worked for us:

The package is trying to load CJS module but the path points to ESM, or vice versa. This is a common issue with dual-format packages.

// Try this import instead:
import { Server } from '@modelcontextprotocol/sdk/server';
// Or for CJS:
// const { Server } = require('@modelcontextprotocol/sdk/server');

Hope this helps! Let me know if it doesn't match your case — happy to dig deeper. 🦞

Disclosure: This analysis is from Confucius Debug, an AI-powered community KB for agent bugs. Please verify before applying.

---

_{🦞 Confucius Debug — community knowledge base for AI agent bugs. Free to search via MCP.}

[Vadaski]

I tested this against the current v2 branch and the issue no longer repros — validateToolOutput now calls parseSchemaAsync (which uses z.safeParseAsync) directly, so .optional(), .nullable(), .nullish(), and .union() output schemas all work correctly.

If this is still a problem on the v1 release track, happy to look at a backport. Otherwise this may be worth closing as fixed in v2.

[mcp-claude]

bug is present on v1.x (bf1e022), fixed on main (v2 rewrite uses validateStandardSchema directly). any non-ZodObject outputSchema — .optional(), .nullable(), .nullish(), z.union() — causes tool calls to silently fail with isError: true.

root cause: normalizeObjectSchema returns undefined for non-ZodObject schemas; that undefined is passed to safeParseAsync, which crashes accessing undefined._zod.

workaround: wrap the output schema in z.object(...) explicitly, or avoid optional/nullable/union wrappers on the top-level outputSchema.

repro script (run from repo root on v1.x)

// repro.ts
import { McpServer } from './src/server/mcp.js';
import { InMemoryTransport } from './src/inMemory.js';
import { Client } from './src/client/index.js';
import { z } from 'zod';

async function testSchema(label: string, outputSchema: z.ZodTypeAny, content: unknown) {
    const server = new McpServer({ name: 'test', version: '1.0.0' });
    server.registerTool('test-tool', { outputSchema }, async () => ({
        content: [],
        structuredContent: content,
    }));
    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
    await server.connect(serverTransport);
    const client = new Client({ name: 'test-client', version: '1.0.0' });
    await client.connect(clientTransport);
    try {
        const result = await client.callTool({ name: 'test-tool', arguments: {} });
        if (result.isError) {
            const errorText = (result.content as Array<{ type: string; text?: string }>)
                .filter(c => c.type === 'text').map(c => c.text).join('');
            console.log(`[FAIL] ${label}: ${errorText}`);
        } else {
            console.log(`[PASS] ${label}`);
        }
    } finally {
        await client.close();
        await server.close();
    }
}

async function main() {
    await testSchema('z.object (baseline)', z.object({ data: z.string() }), { data: 'hello' });
    await testSchema('z.object.optional()', z.object({ data: z.string() }).optional(), { data: 'hello' });
    await testSchema('z.object.nullable()', z.object({ data: z.string() }).nullable(), { data: 'hello' });
    await testSchema('z.object.nullish()', z.object({ data: z.string() }).nullish(), { data: 'hello' });
    await testSchema('z.union([...])', z.union([z.object({ data: z.string() }), z.object({ value: z.string() })]), { data: 'hello' });
}
main().catch(console.error);

$ npx tsx repro.ts
[PASS] z.object (baseline)
[FAIL] z.object.optional(): Cannot read properties of undefined (reading '_zod')
[FAIL] z.object.nullable(): Cannot read properties of undefined (reading '_zod')
[FAIL] z.object.nullish(): Cannot read properties of undefined (reading '_zod')
[FAIL] z.union([...]): Cannot read properties of undefined (reading '_zod')

code path

src/server/mcp.ts:309 — validateToolOutput:

const outputObj = normalizeObjectSchema(tool.outputSchema) as AnyObjectSchema;  // returns undefined
const parseResult = await safeParseAsync(outputObj, result.structuredContent);  // crashes

src/server/zod-compat.ts:57 — isZ4Schema (called inside safeParseAsync):

export function isZ4Schema(s: AnySchema): s is z4.$ZodType {
    const schema = s as unknown as ZodV4Internal;
    return !!schema._zod;  // TypeError: Cannot read properties of undefined
}

suggested fix

// src/server/mcp.ts
         // if the tool has an output schema, validate structured content
-        const outputObj = normalizeObjectSchema(tool.outputSchema) as AnyObjectSchema;
-        const parseResult = await safeParseAsync(outputObj, result.structuredContent);
+        const parseResult = await safeParseAsync(tool.outputSchema as AnyObjectSchema, result.structuredContent);

test to verify: registers a tool with each of .optional(), .nullable(), .nullish(), and z.union() as outputSchema, calls it, and asserts result.isError is not true for any variant (both Zod v3 and v4).

[lawrence3699]

I reproduced this on v1.x (bf1e022) with the same outputSchema failure modes (.optional(), .nullable(), .nullish(), and top-level z.union(...)). I am working on a focused v1.x fix plus regression coverage for those cases.