fix: route prompt schema warnings through logger

Author: mattzcarey

docs/client.md

@@ -388,6 +388,24 @@ const client = new Client(
 );
 ```
 
+### SDK diagnostics logger
+
+SDK-internal diagnostics, such as capability-gating debug messages and schema conversion warnings, use the {@linkcode @modelcontextprotocol/client!index.ProtocolOptions.logger | logger} constructor option. It defaults to `console`. The logger is partial: each method is optional, and omitted levels are silently skipped.
+
+```ts source="../examples/client/src/clientGuide.examples.ts#sdkLogger_basic"
+const client = new Client(
+    { name: 'my-client', version: '1.0.0' },
+    {
+        logger: {
+            warn: (...args) => console.warn('[mcp-sdk]', ...args),
+            debug: () => {
+                // Drop debug diagnostics
+            }
+        }
+    }
+);
+```
+
 ### Manual notification handlers
 
 For full control — or for notification types not covered by `listChanged` (such as log messages) — register handlers directly with {@linkcode @modelcontextprotocol/client!client/client.Client#setNotificationHandler | setNotificationHandler()}:

docs/server.md

@@ -346,6 +346,8 @@ server.registerPrompt(
 > [!WARNING]
 > MCP logging is deprecated as of protocol version 2026-07-28 (SEP-2577). It remains fully functional during the deprecation window (at least twelve months); see the [deprecated features registry](https://modelcontextprotocol.io/specification/draft/deprecated). Migrate to stderr logging (STDIO servers) or OpenTelemetry.
 
+This section covers MCP protocol logging sent from your server to the client. SDK-internal diagnostics, such as tool-name validation warnings and schema conversion fallbacks, are separate and use the `logger` constructor option on `Server` and `McpServer`. The option defaults to `console`; each logger method is optional, so omitted levels are skipped.
+
 Logging lets your server send structured diagnostics — debug traces, progress updates, warnings — to the connected client as notifications (see [Logging](https://modelcontextprotocol.io/specification/latest/server/utilities/logging) in the MCP specification).
 
 Declare the `logging` capability, then call `ctx.mcpReq.log(level, data)` (from {@linkcode @modelcontextprotocol/server!index.ServerContext | ServerContext}) inside any handler:

examples/client/src/clientGuide.examples.ts

@@ -368,6 +368,24 @@ async function listChanged_basic() {
     return client;
 }
 
+/** Example: Route SDK diagnostics through an application logger. */
+function sdkLogger_basic() {
+    //#region sdkLogger_basic
+    const client = new Client(
+        { name: 'my-client', version: '1.0.0' },
+        {
+            logger: {
+                warn: (...args) => console.warn('[mcp-sdk]', ...args),
+                debug: () => {
+                    // Drop debug diagnostics
+                }
+            }
+        }
+    );
+    //#endregion sdkLogger_basic
+    return client;
+}
+
 // ---------------------------------------------------------------------------
 // Handling server-initiated requests
 // ---------------------------------------------------------------------------
@@ -615,6 +633,7 @@ void complete_basic;
 void notificationHandler_basic;
 void setLoggingLevel_basic;
 void listChanged_basic;
+void sdkLogger_basic;
 void capabilities_declaration;
 void sampling_handler;
 void elicitation_handler;

packages/core-internal/src/util/standardSchema.ts

@@ -243,9 +243,10 @@ export async function validateStandardSchema<T extends StandardSchemaV1>(
 // Prompt argument extraction
 
 export function promptArgumentsFromStandardSchema(
-    schema: StandardJSONSchemaV1
+    schema: StandardJSONSchemaV1,
+    logger: SdkLogger = console
 ): Array<{ name: string; description?: string; required: boolean }> {
-    const jsonSchema = standardSchemaToJsonSchema(schema, 'input');
+    const jsonSchema = standardSchemaToJsonSchema(schema, 'input', logger);
     const properties = (jsonSchema.properties as Record<string, { description?: string }>) || {};
     const required = (jsonSchema.required as string[]) || [];
 

packages/server/src/server/mcp.ts

@@ -465,7 +465,7 @@ export class McpServer {
                             name,
                             title: prompt.title,
                             description: prompt.description,
-                            arguments: prompt.argsSchema ? promptArgumentsFromStandardSchema(prompt.argsSchema) : undefined,
+                            arguments: prompt.argsSchema ? promptArgumentsFromStandardSchema(prompt.argsSchema, this._logger) : undefined,
                             icons: prompt.icons,
                             _meta: prompt._meta
                         };

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

@@ -91,6 +91,51 @@ describe('registerTool/registerPrompt accept raw Zod shape (auto-wrapped)', () =
         expect(isStandardSchema(prompts['p']?.argsSchema)).toBe(true);
     });
 
+    it('routes prompt argsSchema conversion warnings to the configured logger', async () => {
+        const warn = vi.fn();
+        const consoleWarn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+        const server = new McpServer({ name: 't', version: '1.0.0' }, { logger: { warn } });
+
+        const argsSchema = z.object({ topic: z.string() });
+        const { jsonSchema: _drop, ...stdNoJson } = argsSchema['~standard'] as unknown as Record<string, unknown>;
+        void _drop;
+        Object.defineProperty(argsSchema, '~standard', { value: { ...stdNoJson, vendor: 'zod' }, configurable: true });
+
+        server.registerPrompt('p', { argsSchema }, async ({ topic }) => ({
+            messages: [{ role: 'user' as const, content: { type: 'text' as const, text: topic } }]
+        }));
+
+        const [client, srv] = InMemoryTransport.createLinkedPair();
+        try {
+            await server.connect(srv);
+            await client.start();
+
+            const responses: JSONRPCMessage[] = [];
+            client.onmessage = m => responses.push(m);
+
+            await client.send({
+                jsonrpc: '2.0',
+                id: 1,
+                method: 'initialize',
+                params: {
+                    protocolVersion: LATEST_PROTOCOL_VERSION,
+                    capabilities: {},
+                    clientInfo: { name: 'c', version: '1.0.0' }
+                }
+            } as JSONRPCMessage);
+            await client.send({ jsonrpc: '2.0', method: 'notifications/initialized' } as JSONRPCMessage);
+            await client.send({ jsonrpc: '2.0', id: 2, method: 'prompts/list' } as JSONRPCMessage);
+
+            await vi.waitFor(() => expect(responses.some(r => 'id' in r && r.id === 2)).toBe(true));
+
+            expect(warn).toHaveBeenCalledWith(expect.stringContaining('zod 4.2.0'));
+            expect(consoleWarn).not.toHaveBeenCalled();
+        } finally {
+            consoleWarn.mockRestore();
+            await server.close();
+        }
+    });
+
     it('callback receives validated, typed args end-to-end via tools/call', async () => {
         const server = new McpServer({ name: 't', version: '1.0.0' });