[TypeScript] Zod's .toJSONSchema() output type incompatible with elicitInput's requestedSchema parameter

[dorukozerr]

Hi, this might be a silly question but I couldn't figure this out on my own. Before creating this issue I looked into documentation and especially type definitions a lot.

• I'm trying to use Zod schemas for requestedSchema in elicitInput() in MCP server tool registration.

  • Example Code

    // tool registration handler function block
    const elicitationStep1 = await mcpServer.server.elicitInput({
      mode: 'form',
      message: 'Elicitation Form - Step 1',
      requestedSchema: z
        .object({
          step1Field: z
            .enum(['s1v1', 's1v2'])
            .describe('Elicitation Form - Step 1, description')
        })
        .toJSONSchema()
    });
    
    const elicitationStep2 = await mcpServer.server.elicitInput({
      mode: 'form',
      message: 'Elicitation Form - Step 2',
      requestedSchema: {
        type: 'object',
        properties: {
          step2Field: {
            type: 'string',
            description: 'Elicitation Form - Step 2, description',
            enum: ['s2v1', 's2v2']
          }
        }
      }
    });
    // tool registration handler function block

• Things I verified

  1. Even though the zod schema usage gives TypeScript error when I run this code the MCP Client request handler gets the identical payloads. Logs I took from MCP Client request handler, data is request handler parameter.

     • Logs

       [
         {
           timestamp: '2026-01-06T14:54:29.883Z',
           operation: 'stdio_mcp_client_log',
           data: {
             method: 'elicitation/create',
             params: {
               mode: 'form',
               message: 'Elicitation Form - Step 1',
               requestedSchema: {
                 type: 'object',
                 properties: {
                   step1Field: {
                     type: 'string',
                     description: 'Elicitation Form - Step 1, description',
                     enum: ['s1v1', 's1v2']
                   }
                 },
                 required: ['step1Field']
               }
             }
           }
         },
         {
           timestamp: '2026-01-06T14:54:29.886Z',
           operation: 'stdio_mcp_client_log',
           data: {
             method: 'elicitation/create',
             params: {
               mode: 'form',
               message: 'Elicitation Form - Step 2',
               requestedSchema: {
                 type: 'object',
                 properties: {
                   step2Field: {
                     type: 'string',
                     description: 'Elicitation Form - Step 2, description',
                     enum: ['s2v1', 's2v2']
                   }
                 }
               }
             }
           }
         }
       ];

  2. If MCP Client request handler returns something that does not match enum options for elicitation requests, MCP Server error block returns the value with correct information, I mean like which step failed and why.

  3. If correct values returned from MCP Client request handler, tool success response returns and elicitation form input data entered is available without any problem.

  4. Before running this flow and get the logs I log the result of zodSchema.toJSONSchema() and compared it. It has 2 extra field only and I'm not sure does that matter because MCP client server communication successfully completes with correct data or returns error with correct rejection reason

     • `.toJSONSchema()` Output

       {
         "$schema": "https://json-schema.org/draft/2020-12/schema",
         "type": "object",
         "properties": {
           "step1Field": {
             "type": "string",
             "enum": [
               "val1",
               "val2"
             ],
             "description": "Example Description"
           }
         },
         "required": [
           "step1Field"
         ],
         "additionalProperties": false
       }

NOTE: If I cast the type of .toJSONSchema() TypeScript error disappears but I really would not prefer that. Also I'm aware of there is no example for this usage anywhere (not that I'm aware of) but I wondered if it's possible to use zod schemas here. I really searched through the examples and looked into type definitions before creating this post but since flow completes with this usage too I just wanted to find out proper way to do it this way.

[felixweinberger]

the requestedSchema type is too narrow — it rejects valid JSON Schema fields like $schema and additionalProperties that Zod v4's .toJSONSchema() (and other generators) produce. works fine at runtime, so this is a type-def bug.\n\nrelated to #662 (which tracks adding Zod helpers more broadly) but this is a standalone fix — the type should accept standard JSON Schema output regardless of generator.\n\nmarking as good first issue since the fix is well-scoped: widen the type in spec.types.ts to allow additional JSON Schema fields.

[dorukozerr]

I attempted a fix for this in PR #1431.

The approach was to cast the requestedSchema type to accept additional properties (like $schema, additionalProperties) that Zod's .toJSONSchema() includes.

However, I found that Zod's TypeScript return type for .toJSONSchema() has properties and type as optional, while the MCP spec requires them. Loosening the SDK types to match Zod's TypeScript types breaks the spec compatibility tests in test/spec.types.test.ts.

I tested the runtime behavior with a real stdio MCP server/client - elicitation works correctly since the Zod validation schema is unchanged. The issue is purely TypeScript type compatibility.

Would appreciate guidance on the preferred approach:

1. Keep strict types (users cast their Zod output)
2. Loosen types and update spec tests
3. Provide a helper function for Zod conversion

Also noting: CONTRIBUTING.md mentions running pnpm test:all but CI also runs pnpm check:all (includes typecheck) - might be worth adding that to the docs.