feat(compat): accept raw Zod shape in registerTool/registerPrompt schemas

v1 allowed passing a raw shape like `{ field: z.string() }` directly as
inputSchema/outputSchema/argsSchema. v2 expects a Standard Schema (e.g.
`z.object({...})`). This restores the v1 shorthand as a deprecated overload:

- core: add isZodRawShape() guard + normalizeRawShapeSchema() that auto-wraps
  raw shapes in z.object() and emits a one-time deprecation warning via
  deprecate('raw-shape', ...).
- server: convert registerTool/registerPrompt to overload sets with a
  @deprecated ZodRawShape-accepting signature so v1 callers typecheck
  unchanged. Implementation pipes schemas through normalizeRawShapeSchema.
- server: add ZodRawShape / LegacyToolCallback / LegacyPromptCallback
  deprecated type aliases for the legacy callback inference.

The shim warns once per process and will be removed in v3.

Author: felixweinberger

.changeset/register-rawshape-compat.md

@@ -0,0 +1,6 @@
+---
+'@modelcontextprotocol/core': patch
+'@modelcontextprotocol/server': patch
+---
+
+v1-compat: `registerTool`/`registerPrompt` accept a raw Zod shape (`{ field: z.string() }`) for `inputSchema`/`outputSchema`/`argsSchema` again. The shape is auto-wrapped in `z.object()` and a one-time deprecation warning is emitted. Wrap in `z.object({...})` to silence the warning; the shim will be removed in v3.

packages/core/src/index.ts

@@ -49,4 +49,4 @@ export * from './validators/fromJsonSchema.js';
 
 // Core types only - implementations are exported via separate entry points
 export type { JsonSchemaType, JsonSchemaValidator, jsonSchemaValidator, JsonSchemaValidatorResult } from './validators/types.js';
-export { deprecate } from './util/deprecate.js';
+export { deprecate, _resetDeprecationWarnings } from './util/deprecate.js';

packages/core/src/util/standardSchema.ts

@@ -6,6 +6,9 @@
 
 /* eslint-disable @typescript-eslint/no-namespace */
 
+import * as z from 'zod/v4';
+import { deprecate } from './deprecate.js';
+
 // Standard Schema interfaces — vendored from https://standardschema.dev (spec v1, Jan 2025)
 
 export interface StandardTypedV1<Input = unknown, Output = Input> {
@@ -136,6 +139,42 @@ export function isStandardSchemaWithJSON(schema: unknown): schema is StandardSch
     return isStandardJSONSchema(schema) && isStandardSchema(schema);
 }
 
+/**
+ * Detects a "raw shape" — a plain object whose values are Zod (or other
+ * Standard Schema) field schemas, e.g. `{ name: z.string() }`. v1 accepted
+ * this shorthand directly; v2 expects `z.object({...})`. This guard powers
+ * the deprecated auto-wrap shim in {@linkcode normalizeRawShapeSchema}.
+ *
+ * @internal
+ */
+export function isZodRawShape(obj: unknown): obj is Record<string, StandardSchemaV1> {
+    if (typeof obj !== 'object' || obj === null) return false;
+    if (isStandardSchema(obj)) return false;
+    const values = Object.values(obj);
+    return values.length > 0 && values.every(v => isStandardSchema(v) || (typeof v === 'object' && v !== null && '_def' in v));
+}
+
+/**
+ * v1-compat shim: if a tool/prompt was registered with the v1 raw-shape
+ * shorthand `{ field: z.string() }`, wrap it in `z.object()` so the rest of
+ * the pipeline sees a {@linkcode StandardSchemaWithJSON}. Passes through
+ * already-wrapped schemas unchanged. Warns once per process.
+ *
+ * @internal
+ */
+export function normalizeRawShapeSchema(schema: unknown): StandardSchemaWithJSON | undefined {
+    if (schema === undefined) return undefined;
+    if (isZodRawShape(schema)) {
+        deprecate(
+            'raw-shape',
+            'Passing a raw shape like `{ field: z.string() }` as inputSchema/argsSchema is deprecated. ' +
+                'Wrap it in z.object({...}) (or your schema library equivalent). Auto-wrapping for now; this shim will be removed in v3.'
+        );
+        return z.object(schema as z.core.$ZodLooseShape) as StandardSchemaWithJSON;
+    }
+    return schema as StandardSchemaWithJSON;
+}
+
 // JSON Schema conversion
 
 /**

packages/server/src/server/mcp.ts

@@ -30,6 +30,7 @@ import type {
 import {
     assertCompleteRequestPrompt,
     assertCompleteRequestResourceTemplate,
+    normalizeRawShapeSchema,
     promptArgumentsFromStandardSchema,
     ProtocolError,
     ProtocolErrorCode,
@@ -873,6 +874,31 @@ export class McpServer {
             _meta?: Record<string, unknown>;
         },
         cb: ToolCallback<InputArgs>
+    ): RegisteredTool;
+    /** @deprecated Pass a Standard Schema (e.g. wrap your raw shape in `z.object({...})`). Raw-shape inputs are auto-wrapped at runtime. Removed in v3. */
+    registerTool<InputArgs extends ZodRawShape, OutputArgs extends ZodRawShape | StandardSchemaWithJSON | undefined = undefined>(
+        name: string,
+        config: {
+            title?: string;
+            description?: string;
+            inputSchema?: InputArgs;
+            outputSchema?: OutputArgs;
+            annotations?: ToolAnnotations;
+            _meta?: Record<string, unknown>;
+        },
+        cb: LegacyToolCallback<InputArgs>
+    ): RegisteredTool;
+    registerTool(
+        name: string,
+        config: {
+            title?: string;
+            description?: string;
+            inputSchema?: StandardSchemaWithJSON | ZodRawShape;
+            outputSchema?: StandardSchemaWithJSON | ZodRawShape;
+            annotations?: ToolAnnotations;
+            _meta?: Record<string, unknown>;
+        },
+        cb: ToolCallback<StandardSchemaWithJSON | undefined> | LegacyToolCallback<ZodRawShape>
     ): RegisteredTool {
         if (this._registeredTools[name]) {
             throw new Error(`Tool ${name} is already registered`);
@@ -884,8 +910,8 @@ export class McpServer {
             name,
             title,
             description,
-            inputSchema,
-            outputSchema,
+            normalizeRawShapeSchema(inputSchema),
+            normalizeRawShapeSchema(outputSchema),
             annotations,
             { taskSupport: 'forbidden' },
             _meta,
@@ -928,6 +954,27 @@ export class McpServer {
             _meta?: Record<string, unknown>;
         },
         cb: PromptCallback<Args>
+    ): RegisteredPrompt;
+    /** @deprecated Pass a Standard Schema (e.g. wrap your raw shape in `z.object({...})`). Raw-shape inputs are auto-wrapped at runtime. Removed in v3. */
+    registerPrompt<Args extends ZodRawShape>(
+        name: string,
+        config: {
+            title?: string;
+            description?: string;
+            argsSchema?: Args;
+            _meta?: Record<string, unknown>;
+        },
+        cb: LegacyPromptCallback<Args>
+    ): RegisteredPrompt;
+    registerPrompt(
+        name: string,
+        config: {
+            title?: string;
+            description?: string;
+            argsSchema?: StandardSchemaWithJSON | ZodRawShape;
+            _meta?: Record<string, unknown>;
+        },
+        cb: PromptCallback<StandardSchemaWithJSON> | LegacyPromptCallback<ZodRawShape>
     ): RegisteredPrompt {
         if (this._registeredPrompts[name]) {
             throw new Error(`Prompt ${name} is already registered`);
@@ -939,7 +986,7 @@ export class McpServer {
             name,
             title,
             description,
-            argsSchema,
+            normalizeRawShapeSchema(argsSchema),
             cb as PromptCallback<StandardSchemaWithJSON | undefined>,
             _meta
         );
@@ -1062,6 +1109,25 @@ export class ResourceTemplate {
     }
 }
 
+/**
+ * v1 raw-shape: a plain record of field schemas, e.g. `{ name: z.string() }`.
+ * @deprecated Wrap in `z.object({...})` and pass to `registerTool`. Removed in v3.
+ */
+export type ZodRawShape = Record<string, StandardSchemaWithJSON>;
+
+/** @deprecated Removed in v3. */
+export type InferRawShape<S extends ZodRawShape> = { [K in keyof S]: StandardSchemaWithJSON.InferOutput<S[K]> };
+
+/** @deprecated Use {@linkcode ToolCallback} with `registerTool`. Removed in v3. */
+export type LegacyToolCallback<Args extends ZodRawShape | undefined> = Args extends ZodRawShape
+    ? (args: InferRawShape<Args>, ctx: ServerContext) => CallToolResult | Promise<CallToolResult>
+    : (ctx: ServerContext) => CallToolResult | Promise<CallToolResult>;
+
+/** @deprecated Use {@linkcode PromptCallback} with `registerPrompt`. Removed in v3. */
+export type LegacyPromptCallback<Args extends ZodRawShape | undefined> = Args extends ZodRawShape
+    ? (args: InferRawShape<Args>, ctx: ServerContext) => GetPromptResult | Promise<GetPromptResult>
+    : (ctx: ServerContext) => GetPromptResult | Promise<GetPromptResult>;
+
 export type BaseToolCallback<
     SendResultT extends Result,
     Ctx extends ServerContext,

packages/server/test/server/mcp.compat.test.ts

@@ -0,0 +1,61 @@
+import { _resetDeprecationWarnings, isStandardSchema } from '@modelcontextprotocol/core';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import * as z from 'zod/v4';
+import { McpServer } from '../../src/index.js';
+
+describe('v1 compat: registerTool/registerPrompt raw-shape auto-wrap', () => {
+    beforeEach(() => {
+        _resetDeprecationWarnings();
+    });
+
+    it('registerTool accepts a raw shape for inputSchema, auto-wraps, and warns once', () => {
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+        const server = new McpServer({ name: 't', version: '1.0.0' });
+
+        server.registerTool('a', { inputSchema: { x: z.number() } }, async ({ x }) => ({
+            content: [{ type: 'text' as const, text: String(x) }]
+        }));
+        server.registerTool('b', { inputSchema: { y: z.number() } }, async ({ y }) => ({
+            content: [{ type: 'text' as const, text: String(y) }]
+        }));
+
+        const tools = (server as unknown as { _registeredTools: Record<string, { inputSchema?: unknown }> })._registeredTools;
+        expect(Object.keys(tools)).toEqual(['a', 'b']);
+        // raw shape was wrapped into a Standard Schema (z.object)
+        expect(isStandardSchema(tools['a']?.inputSchema)).toBe(true);
+
+        const rawShapeWarns = warn.mock.calls.filter(c => String(c[0]).includes('raw shape'));
+        expect(rawShapeWarns.length).toBe(1);
+        warn.mockRestore();
+    });
+
+    it('registerTool with z.object() inputSchema does not warn', () => {
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+        const server = new McpServer({ name: 't', version: '1.0.0' });
+
+        server.registerTool('c', { inputSchema: z.object({ x: z.number() }) }, async ({ x }) => ({
+            content: [{ type: 'text' as const, text: String(x) }]
+        }));
+
+        const rawShapeWarns = warn.mock.calls.filter(c => String(c[0]).includes('raw shape'));
+        expect(rawShapeWarns.length).toBe(0);
+        warn.mockRestore();
+    });
+
+    it('registerPrompt accepts a raw shape for argsSchema and warns', () => {
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+        const server = new McpServer({ name: 't', version: '1.0.0' });
+
+        server.registerPrompt('p', { argsSchema: { topic: z.string() } }, async ({ topic }) => ({
+            messages: [{ role: 'user' as const, content: { type: 'text' as const, text: topic } }]
+        }));
+
+        const prompts = (server as unknown as { _registeredPrompts: Record<string, { argsSchema?: unknown }> })._registeredPrompts;
+        expect(Object.keys(prompts)).toContain('p');
+        expect(isStandardSchema(prompts['p']?.argsSchema)).toBe(true);
+
+        const rawShapeWarns = warn.mock.calls.filter(c => String(c[0]).includes('raw shape'));
+        expect(rawShapeWarns.length).toBe(1);
+        warn.mockRestore();
+    });
+});