tools/list returns empty inputSchema for ZodEffects-wrapped schemas (Zod .superRefine / .refine / .transform / .pipe)

[produtoramaxvision]

Summary

When a tool's inputSchema is a Zod schema that has been transformed via .superRefine(), .refine(), .transform(), or .pipe() (Zod v3) — producing a ZodEffects (or ZodPipeline) wrapper around an underlying ZodObject — the tools/list JSON-RPC response emits an empty inputSchema: {} for that tool. Runtime validation of incoming tools/call arguments still works correctly (the SDK's safeParse handles ZodEffects), but client-side introspection (Cursor, IDE plugins, schema-driven UIs) loses all field metadata.

Tools whose inputSchema is a plain ZodObject are unaffected and emit a correct JSON Schema.

Reproduction

Minimal repro (Node 20+, TypeScript or JS):

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { z } from 'zod';

// Plain ZodObject — emits proper JSON Schema in tools/list
const PlainSchema = z.object({
  prompt: z.string().min(1),
  count: z.number().int().positive().default(1),
});

// ZodEffects (superRefine over the same shape) — emits {} in tools/list
const EffectsSchema = PlainSchema.superRefine((v, ctx) => {
  if (v.count > 100) {
    ctx.addIssue({ code: 'custom', path: ['count'], message: 'cap exceeded' });
  }
});

const server = new McpServer({ name: 'demo', version: '0.0.1' });

server.registerTool('plain_tool', {
  title: 'Plain',
  description: 'Plain ZodObject',
  inputSchema: PlainSchema, // ✅ tools/list inputSchema has properties
}, async () => ({ content: [{ type: 'text', text: 'ok' }] }));

server.registerTool('effects_tool', {
  title: 'Effects',
  description: 'ZodEffects (superRefine)',
  inputSchema: EffectsSchema, // ❌ tools/list inputSchema is `{}`
}, async () => ({ content: [{ type: 'text', text: 'ok' }] }));

After connecting any MCP client and calling tools/list, the response shows:

{
  "tools": [
    {
      "name": "plain_tool",
      "inputSchema": {
        "type": "object",
        "properties": {
          "prompt": { "type": "string", "minLength": 1 },
          "count": { "type": "integer", "exclusiveMinimum": 0, "default": 1 }
        },
        "required": ["prompt"]
      }
    },
    {
      "name": "effects_tool",
      "inputSchema": {}      // ← empty
    }
  ]
}

Same problem reproduces with .refine(), .transform(), and .pipe() (any wrapper that produces ZodEffects or ZodPipeline).

Expected behavior

tools/list should emit the JSON Schema of the underlying object shape regardless of whether the schema has been wrapped in ZodEffects / ZodPipeline. Cross-field validation logic (the superRefine/refine body) does not need to be serialized — its absence from the JSON Schema is expected — but the field-level metadata (properties, types, defaults, required) should still be exposed.

Actual behavior

tools/list returns inputSchema: {} for ZodEffects-wrapped schemas, leaving clients without field metadata.

Root cause

In src/server/zod-compat.ts → normalizeObjectSchema(schema):

// (Zod v3 branch)
const v3Schema = schema;
if (v3Schema.shape !== undefined) {
  return schema;
}
return undefined; // ← falls through here for ZodEffects

ZodEffects (Zod v3) does not expose .shape directly — it lives on schema._def.schema.shape. The same applies to ZodPipeline (._def.in / ._def.out), ZodOptional / ZodNullable / ZodReadonly / ZodBranded / ZodDefault (._def.innerType).

When normalizeObjectSchema returns undefined, the caller in src/server/mcp.ts falls back to emitting inputSchema: {} (see lines 79, 175 in dist/cjs/server/mcp.js).

Suggested fix

Add an unwrap step at the top of normalizeObjectSchema that peels off ZodEffects, ZodPipeline, ZodOptional, ZodNullable, ZodReadonly, ZodBranded, and ZodDefault until either a ZodObject is reached or no further unwrapping is possible. Pseudo-code:

function unwrapToObject(schema: unknown): unknown {
  if (!schema || typeof schema !== 'object') return schema;
  const def = (schema as { _def?: { typeName?: string; schema?: unknown; in?: unknown; innerType?: unknown } })._def;
  if (!def) return schema;

  // Zod v3 ZodEffects: ._def.schema is the wrapped schema
  if (def.typeName === 'ZodEffects' && def.schema) {
    return unwrapToObject(def.schema);
  }
  // ZodPipeline: ._def.in is the input-side schema
  if (def.typeName === 'ZodPipeline' && def.in) {
    return unwrapToObject(def.in);
  }
  // ZodOptional / ZodNullable / ZodReadonly / ZodBranded / ZodDefault: ._def.innerType
  if (def.innerType) {
    return unwrapToObject(def.innerType);
  }
  return schema;
}

export function normalizeObjectSchema(schema: AnySchemaCompat | undefined) {
  if (!schema) return undefined;
  const unwrapped = unwrapToObject(schema);
  // ... existing raw-shape detection and v3/v4 object checks operate on `unwrapped` ...
}

The equivalent for Zod v4 Mini would inspect _zod.def.type === 'pipe' | 'transform' | 'refine' | 'optional' | 'nullable' | ... and chain through _zod.def.in / _zod.def.innerType.

This preserves the documented behavior (object schemas pass through), fixes the silent fallback to {}, and does not require any caller changes.

Environment

• @modelcontextprotocol/sdk 1.29.0
• zod 3.25.76
• Node.js 25.5.0
• Windows 11 (and reproduced on Ubuntu 22.04 in CI matrix)
• Affected paths in installed SDK: dist/cjs/server/zod-compat.js (lines ~110-156), dist/cjs/server/mcp.js (lines 79, 92, 175, 203, 432)

Workaround currently in use (production plugin)

We split each affected schema in two:

• _FooBase = z.object({...}) (ZodObject — registered as MCP inputSchema for proper introspection)
• FooInput = _FooBase.superRefine(...) (ZodEffects — kept as a separate validationSchema and re-parsed inside the request handler before delegating to the service layer)

This restores client-side hints and keeps cross-field validation server-side, at the cost of one extra .parse() per request and a custom validationSchema?: ZodTypeAny field on our tool registry. Happy to upstream a similar primitive if useful, but the cleanest fix is on the SDK side as described above.

Impact

Approximately 50% of complex tools (those with any cross-field rule via .superRefine / .refine) are affected. For our use case (multimedia generation plugin with 22 tools), 10 tools lost client-side metadata until we applied the workaround.

Happy to open a PR with the unwrap helper + tests if you'd like — let me know if you'd prefer a v3-only fix, a unified v3+v4 fix, or different unwrap semantics.

Thank you for the SDK!

[kayalopez]

One downstream regression check I would add for this class of bug is a metadata-completeness pass over the actual tools/list response, separate from runtime tools/call validation.

Concrete checks that catch the failure mode in this issue:

• inputSchema: {} should be treated as a review failure for any tool that is expected to take arguments.
• Missing inputSchema should be distinguished from an explicit no-argument object schema.
• Object schemas with properties but no required array should be reviewed so required path/body parameters are not silently treated as optional.
• Parameters without descriptions should be called out because clients and LLM argument builders lose useful intent/context.

I added those checks to a metadata-only CLI/browser importer here in case it is useful as an interim CI guard while the SDK fix lands:

• https://github.com/kayalopez/ai-agent-launch-tools/releases/tag/v0.1.10
• https://ai-launch-risk-check-public.vercel.app/mcp-permission-matrix-importer.html

It only reads non-sensitive tools/list JSON and does not invoke tools. For this SDK issue specifically, the important assertion is that a ZodEffects/ZodPipeline-wrapped object schema must still produce a non-empty object schema with the underlying properties in tools/list.

[cogeor]

Also ran into this issue, happy to take this if you haven't started @produtoramaxvision . Should have a PR up in a few days.

Smaller fix than unwrapping wrappers by type, I think: mirror the fallback the codebase already uses for validation. In src/server/mcp.ts:

// validateToolInput, lines 272–274 — already does this
const inputObj = normalizeObjectSchema(tool.inputSchema);
const schemaToParse = inputObj ?? (tool.inputSchema as AnySchema);

// tools/list emission, lines 148–155 — doesn't
const obj = normalizeObjectSchema(tool.inputSchema);
return obj ? toJsonSchemaCompat(obj, {...}) : EMPTY_OBJECT_JSON_SCHEMA;

zod-to-json-schema (v3) and z4mini.toJSONSchema (v4) both walk ZodEffects/ZodPipe/etc. natively and drop the refinement body, so letting the original schema reach them recovers the shape. ~6-line change: same fallback at the two emission sites (input + output), plus widening toJsonSchemaCompat's first parameter from AnyObjectSchema to AnySchema. No wrapper list to maintain across zod versions.

Tests: parametrize over .refine / .superRefine / .transform / .pipe for both v3 and v4, covering input and output emission, assert inputSchema.properties is populated. One regression case for EMPTY_OBJECT_JSON_SCHEMA when no schema is provided.

Targeting v1.x per CONTRIBUTING.

[scosemicolon]

This looks worth covering with a tools/list regression test for each Zod wrapper type, not just one repro case.

Suggested matrix:

• z.object({...}).refine(...)
• z.object({...}).superRefine(...)
• z.object({...}).transform(...)
• z.object({...}).pipe(...)

For each case, the test should assert that tools/list still emits an object schema with the original properties, and that runtime tools/call validation still applies the wrapper behavior. That catches the important split here: schema introspection should unwrap far enough for clients to see inputs, while validation should continue using the real wrapped schema.

[cogeor]

Done, opened #2159. Test layout follows your matrix (.refine / .superRefine / .transform / .pipe) under the existing zodTestMatrix so both Zod v3 and v4 are covered, asserting both that tools/list emits the underlying object's properties and that tools/call still rejects args violating the wrapper's rule. Thanks for the shape, having the "introspection unwraps, validation doesn't" split spelled out made the test surface obvious.

[mcp-claude]

reproduces on v1.x @ 69749aa, not on main @ 3834921 (the standardSchemaToJsonSchema refactor already delegates to zod's own converters, which walk wrappers). backport still needed for v1.x — PR #2159 targets v1.x and takes the mirror-the-fallback approach.

on v1.x, normalizeObjectSchema in src/server/zod-compat.ts checks .shape at the root only; ZodEffects keeps it on _def.schema.shape, ZodPipeline on _def.in.shape, so it returns undefined and the tools/list site at src/server/mcp.ts:148-156 falls through to EMPTY_OBJECT_JSON_SCHEMA. validateToolInput at src/server/mcp.ts:272-274 already has the fallback (inputObj ?? tool.inputSchema), so runtime validation still works — only introspection is broken. workaround: split into a plain z.object({...}) for inputSchema and keep the wrapped schema for server-side re-validation.

fix is minimal — mirror the existing validate fallback at the two emission sites (input at 148-156, output at 162-170) and widen toJsonSchemaCompat's first parameter to AnySchema. both branches of toJsonSchemaCompat already delegate to converters (zodToJsonSchema for v3, z4mini.toJSONSchema for v4) that walk wrapper types natively, so no wrapper-type list to maintain across zod versions. verified against both zod v3 and v4 in the test matrix; full suite (1608 tests) still green, typecheck clean.

repro on v1.x — npm install && npm run build && npx tsx repro.ts

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

const PlainSchema = z.object({
    prompt: z.string().min(1),
    count: z.number().int().positive().default(1)
});
const RefineSchema = PlainSchema.refine(v => v.count <= 100, { message: 'cap exceeded', path: ['count'] });
const SuperRefineSchema = PlainSchema.superRefine((v, ctx) => {
    if (v.count > 100) ctx.addIssue({ code: 'custom', path: ['count'], message: 'cap exceeded' });
});
const TransformSchema = PlainSchema.transform(v => ({ ...v, count: v.count * 2 }));
const PipeSchema = PlainSchema.pipe(z.object({ prompt: z.string(), count: z.number() }));

async function run() {
    const server = new McpServer({ name: 'demo', version: '0.0.1' });
    server.registerTool('plain_tool', { title: 'Plain', description: '', inputSchema: PlainSchema },
        async () => ({ content: [{ type: 'text', text: 'ok' }] }));
    server.registerTool('refine_tool', { title: 'Refine', description: '', inputSchema: RefineSchema as any },
        async () => ({ content: [{ type: 'text', text: 'ok' }] }));
    server.registerTool('super_refine_tool', { title: 'SR', description: '', inputSchema: SuperRefineSchema as any },
        async () => ({ content: [{ type: 'text', text: 'ok' }] }));
    server.registerTool('transform_tool', { title: 'T', description: '', inputSchema: TransformSchema as any },
        async () => ({ content: [{ type: 'text', text: 'ok' }] }));
    server.registerTool('pipe_tool', { title: 'P', description: '', inputSchema: PipeSchema as any },
        async () => ({ content: [{ type: 'text', text: 'ok' }] }));

    const [ct, st] = InMemoryTransport.createLinkedPair();
    const client = new Client({ name: 'test-client', version: '0.0.1' });
    await Promise.all([server.connect(st), client.connect(ct)]);
    const listed = await client.listTools();
    for (const t of listed.tools) console.log(`\n=== ${t.name} ===\n${JSON.stringify(t.inputSchema, null, 2)}`);
    await client.close(); await server.close();
}
run().catch(e => { console.error(e); process.exit(1); });

observed on v1.x (69749aa):

=== plain_tool ===
{ "type": "object", "properties": { "prompt": {...}, "count": {...} }, "required": ["prompt"], ... }
=== refine_tool ===
{ "type": "object", "properties": {} }
=== super_refine_tool ===
{ "type": "object", "properties": {} }
=== transform_tool ===
{ "type": "object", "properties": {} }
=== pipe_tool ===
{ "type": "object", "properties": {} }

same repro on main (3834921) emits full properties for every tool.

suggested fix

// src/server/mcp.ts — tools/list emission site
                             inputSchema: (() => {
                                 const obj = normalizeObjectSchema(tool.inputSchema);
-                                return obj
-                                    ? (toJsonSchemaCompat(obj, {
-                                          strictUnions: true,
-                                          pipeStrategy: 'input'
-                                      }) as Tool['inputSchema'])
-                                    : EMPTY_OBJECT_JSON_SCHEMA;
+                                const schemaForConversion = obj ?? (tool.inputSchema as AnySchema | undefined);
+                                if (!schemaForConversion) return EMPTY_OBJECT_JSON_SCHEMA;
+                                return toJsonSchemaCompat(schemaForConversion, {
+                                    strictUnions: true,
+                                    pipeStrategy: 'input'
+                                }) as Tool['inputSchema'];
                             })(),

                         if (tool.outputSchema) {
                             const obj = normalizeObjectSchema(tool.outputSchema);
-                            if (obj) {
-                                toolDefinition.outputSchema = toJsonSchemaCompat(obj, {
+                            const schemaForConversion = obj ?? (tool.outputSchema as AnySchema | undefined);
+                            if (schemaForConversion) {
+                                toolDefinition.outputSchema = toJsonSchemaCompat(schemaForConversion, {
                                     strictUnions: true,
                                     pipeStrategy: 'output'
                                 }) as Tool['outputSchema'];
                             }
                         }

// src/server/zod-json-schema-compat.ts — widen param
-export function toJsonSchemaCompat(schema: AnyObjectSchema, opts?: CommonOpts): JsonSchema {
+export function toJsonSchemaCompat(schema: AnySchema, opts?: CommonOpts): JsonSchema {

test to verify: registers four tools whose inputSchemas are a base z.object wrapped with .refine/.superRefine/.transform/.pipe, calls tools/list, and asserts each emitted inputSchema has type: "object" and properties keys ["count", "prompt"]. runs under both zod v3 and v4 via the existing zodTestMatrix. fails on 69749aa (properties {}); passes with the fix. full suite (1608 tests) remains green.

[cogeor]

Confirming alignment with the verification above, as author of #2159:

• The PR already implements exactly the suggested fix. I diffed the suggested patch against the PR branch: same fallback at both emission sites (input at src/server/mcp.ts:148, output at :163), same widening of toJsonSchemaCompat's first parameter from AnyObjectSchema to AnySchema. The only differences are cosmetic (early return + obj ?? tool.inputSchema instead of a schemaForConversion local).
• Test coverage matches the described matrix. The PR parametrizes .refine / .superRefine / .transform / .pipe under the existing zodTestMatrix (Zod v3 and v4), asserting both that tools/list emits the underlying object's properties and that tools/call still rejects arguments violating the wrapper's rule, plus a regression case for EMPTY_OBJECT_JSON_SCHEMA when no schema is provided.
• Agreed that main doesn't need the fix — the standardSchemaToJsonSchema refactor already delegates to Zod's own converters, which walk wrapper types. One gap worth noting: main has no regression test for wrapped schemas in tools/list (the fix there is a side effect of the refactor, not covered explicitly). I can follow up with a small test-only PR against main porting this matrix, so a future converter change can't silently regress it — happy to do that if maintainers agree.

So: #2159 is the v1.x backport called for above, and it's ready for review as-is.