Bug: `new McpServer()` throws "Schema method literal must be a string" during initialization (method literal stored under `_def.values[0]`)

[kirill578]

Describe the bug
new McpServer() throws during construction with:

Error: Schema method literal must be a string

This happens before any user code registers tools/resources/prompts (during SDK initialization when it installs default request handlers like ping). It appears the SDK’s Server.setRequestHandler() only reads method literals from _def.value / .value, but in some Zod runtimes the literal is stored under _def.values[0].

Related theme / potentially overlapping work:

• Migrate to Zod 4 #1251 (Migrate to Zod 4)
• Decouple from Zod, allow any validator (bring your own) #1252 (Decouple from Zod, allow any validator)
• Type-first as opposed to Zod schema-first approach #1253 (Type-first as opposed to Zod schema-first approach)
• Bug: server.tool() silently ignores ZodObject schemas and strips all arguments #1291 (Bug: server.tool() silently ignores ZodObject schemas and strips all arguments) — schema handling bug, though this issue occurs even before tool registration
• [TypeScript] Zod's .toJSONSchema() output type incompatible with elicitInput's requestedSchema parameter #1362 ([TypeScript] Zod's .toJSONSchema() output type incompatible...) — not the same failure mode, but same Zod/schema compatibility surface area

To Reproduce
Steps to reproduce the behavior:

1. Install deps (any package manager):
   • @modelcontextprotocol/sdk@1.25.2
   • zod@3.25.1
2. Run:

// repro.js
const { McpServer } = require("@modelcontextprotocol/sdk/server/mcp.js");
new McpServer({ name: "repro", version: "1.0.0" });
console.log("constructed");

3. node repro.js

Expected behavior
new McpServer() constructs successfully (default handlers like ping should register without error).

Logs
Example stack:

Error: Schema method literal must be a string
    at Server.setRequestHandler (.../node_modules/@modelcontextprotocol/sdk/dist/cjs/server/index.js:117:19)
    at new Protocol (.../node_modules/@modelcontextprotocol/sdk/dist/cjs/shared/protocol.js:37:14)
    at new Server (.../node_modules/@modelcontextprotocol/sdk/dist/cjs/server/index.js:41:9)
    at new McpServer (.../node_modules/@modelcontextprotocol/sdk/dist/cjs/server/mcp.js:28:23)

Additional observed detail:

• For the SDK’s internal request schemas (e.g. PingRequestSchema), method’s schema _def contains { type, values } and the literal is at _def.values[0], while _def.value and .value are undefined.
• dist/cjs/server/index.js currently does:
  • methodValue = legacyDef?.value ?? v3Schema.value;
  • then throws if typeof methodValue !== 'string'

Additional context
Workaround (ugly): monkey-patch Server.prototype.setRequestHandler before new McpServer() to fallback to _def.values[0] when _def.value/.value are missing, then retry registration. This suggests the SDK should either:

• use the existing compat helper (it already has logic to read values[0] in some places), or
• extend Server.setRequestHandler method-literal extraction to check _def.values[0] as a fallback.

[kirill578]

if you need to workaround feel free to use this:

function applyMcpSdkMethodLiteralWorkaround() {
    try {
        const mcpEntryPath = require.resolve('@modelcontextprotocol/sdk/server/mcp.js');
        const distCjsDir = path.resolve(path.dirname(mcpEntryPath), '..'); // .../dist/cjs

        // eslint-disable-next-line @typescript-eslint/no-var-requires
        const { Server } = require(path.join(distCjsDir, 'server', 'index.js')) as { Server: any };
        // eslint-disable-next-line @typescript-eslint/no-var-requires
        const { getObjectShape } = require(path.join(distCjsDir, 'server', 'zod-compat.js')) as {
            getObjectShape: (schema: unknown) => any;
        };

        if (Server.prototype.__methodLiteralPatched) {
            return;
        }

        const originalSetRequestHandler = Server.prototype.setRequestHandler;

        Server.prototype.setRequestHandler = function patchedSetRequestHandler(requestSchema: unknown, handler: any) {
            try {
                return originalSetRequestHandler.call(this, requestSchema, handler);
            } catch (err) {
                if (!(err instanceof Error) || err.message !== 'Schema method literal must be a string') {
                    throw err;
                }

                // Best-effort: expose `_def.values[0]` as `_def.value` and `.value` so the SDK can read it.
                try {
                    const shape = getObjectShape(requestSchema);
                    const methodSchema: any = shape?.method;
                    const def: any = methodSchema?._def;
                    const maybeValue = Array.isArray(def?.values) ? def.values[0] : undefined;

                    if (typeof maybeValue === 'string') {
                        if (def && def.value === undefined) {
                            def.value = maybeValue;
                        }
                        if (methodSchema && methodSchema.value === undefined) {
                            methodSchema.value = maybeValue;
                        }
                    }
                } catch {
                    // ignore
                }

                // Retry after patching the schema shape.
                return originalSetRequestHandler.call(this, requestSchema, handler);
            }
        };

        Server.prototype.__methodLiteralPatched = true;
    } catch {
        // Best-effort patch; if it fails, we fall back to normal behavior (and likely crash as before).
    }
}

applyMcpSdkMethodLiteralWorkaround();

// Create an MCP server
const server = new McpServer({