fix(server): sanitize internal error details in tool error responses

When a tool handler throws an unexpected error, the full error message
was sent to the MCP client, potentially leaking sensitive server
internals (hostnames, connection strings, stack traces).

Adds a ToolError class that tool authors can throw when they want a
specific message shown to the client. All other unhandled errors are
now sanitized to "Internal error". ProtocolErrors from SDK validation
are still passed through since they contain safe, structured messages.

Closes #1429

Author: claygeo

packages/server/src/index.ts

@@ -23,7 +23,7 @@ export type {
     ResourceMetadata,
     ToolCallback
 } from './server/mcp.js';
-export { McpServer, ResourceTemplate } from './server/mcp.js';
+export { McpServer, ResourceTemplate, ToolError } from './server/mcp.js';
 export type { HostHeaderValidationResult } from './server/middleware/hostHeaderValidation.js';
 export { hostHeaderValidationResponse, localhostAllowedHostnames, validateHostHeader } from './server/middleware/hostHeaderValidation.js';
 export type { ServerOptions } from './server/server.js';

packages/server/src/server/mcp.ts

@@ -58,6 +58,22 @@ import { Server } from './server.js';
  * });
  * ```
  */
+
+/**
+ * Error class for tool handlers to throw when they want to send a
+ * user-visible error message to the client. Unlike regular errors,
+ * ToolError messages are passed through to the client as-is.
+ *
+ * Regular errors thrown from tool handlers are sanitized to "Internal
+ * error" to prevent leaking sensitive server internals.
+ */
+export class ToolError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'ToolError';
+    }
+}
+
 export class McpServer {
     /**
      * The underlying {@linkcode Server} instance, useful for advanced operations like sending notifications.
@@ -209,7 +225,16 @@ export class McpServer {
                 if (error instanceof ProtocolError && error.code === ProtocolErrorCode.UrlElicitationRequired) {
                     throw error; // Return the error to the caller without wrapping in CallToolResult
                 }
-                return this.createToolError(error instanceof Error ? error.message : String(error));
+                if (error instanceof ProtocolError) {
+                    // SDK-generated validation errors are safe to expose
+                    return this.createToolError(error.message);
+                }
+                if (error instanceof ToolError) {
+                    // Developer intentionally wants this message shown to client
+                    return this.createToolError(error.message);
+                }
+                // All other errors: sanitize to prevent leaking internals
+                return this.createToolError('Internal error');
             }
         });
 

test/integration/test/server/mcp.test.ts

@@ -8,7 +8,7 @@ import {
     UriTemplate,
     UrlElicitationRequiredError
 } from '@modelcontextprotocol/core';
-import { completable, McpServer, ResourceTemplate } from '@modelcontextprotocol/server';
+import { completable, McpServer, ResourceTemplate, ToolError } from '@modelcontextprotocol/server';
 import { afterEach, beforeEach, describe, expect, test } from 'vitest';
 import * as z from 'zod/v4';
 
@@ -1799,7 +1799,112 @@ describe('Zod v4', () => {
             expect(result.content).toEqual([
                 {
                     type: 'text',
-                    text: 'Tool execution failed'
+                    text: 'Internal error'
+                }
+            ]);
+        });
+
+        test('should pass through ToolError message to client', async () => {
+            const mcpServer = new McpServer({
+                name: 'test server',
+                version: '1.0'
+            });
+
+            const client = new Client({
+                name: 'test client',
+                version: '1.0'
+            });
+
+            mcpServer.registerTool('toolerror-test', {}, async () => {
+                throw new ToolError('Invalid input: country not supported');
+            });
+
+            const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+
+            await Promise.all([client.connect(clientTransport), mcpServer.server.connect(serverTransport)]);
+
+            const result = await client.request({
+                method: 'tools/call',
+                params: {
+                    name: 'toolerror-test'
+                }
+            });
+
+            expect(result.isError).toBe(true);
+            expect(result.content).toEqual([
+                {
+                    type: 'text',
+                    text: 'Invalid input: country not supported'
+                }
+            ]);
+        });
+
+        test('should sanitize generic Error to Internal error', async () => {
+            const mcpServer = new McpServer({
+                name: 'test server',
+                version: '1.0'
+            });
+
+            const client = new Client({
+                name: 'test client',
+                version: '1.0'
+            });
+
+            mcpServer.registerTool('internal-error-test', {}, async () => {
+                throw new Error('Connection failed at 10.0.0.5:5432');
+            });
+
+            const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+
+            await Promise.all([client.connect(clientTransport), mcpServer.server.connect(serverTransport)]);
+
+            const result = await client.request({
+                method: 'tools/call',
+                params: {
+                    name: 'internal-error-test'
+                }
+            });
+
+            expect(result.isError).toBe(true);
+            expect(result.content).toEqual([
+                {
+                    type: 'text',
+                    text: 'Internal error'
+                }
+            ]);
+        });
+
+        test('should sanitize non-Error throws to Internal error', async () => {
+            const mcpServer = new McpServer({
+                name: 'test server',
+                version: '1.0'
+            });
+
+            const client = new Client({
+                name: 'test client',
+                version: '1.0'
+            });
+
+            mcpServer.registerTool('string-throw-test', {}, async () => {
+                throw 'some raw string error';
+            });
+
+            const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+
+            await Promise.all([client.connect(clientTransport), mcpServer.server.connect(serverTransport)]);
+
+            const result = await client.request({
+                method: 'tools/call',
+                params: {
+                    name: 'string-throw-test'
+                }
+            });
+
+            expect(result.isError).toBe(true);
+            expect(result.content).toEqual([
+                {
+                    type: 'text',
+                    text: 'Internal error'
                 }
             ]);
         });
@@ -6972,7 +7077,7 @@ describe('Zod v4', () => {
 
             // Should receive an error since cancelled tasks don't have results
             expect(result).toHaveProperty('content');
-            expect(result.content).toEqual([{ type: 'text' as const, text: expect.stringContaining('has no result stored') }]);
+            expect(result.content).toEqual([{ type: 'text' as const, text: 'Internal error' }]);
 
             // Wait for async operations to complete
             await waitForLatch();