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

.changeset/tool-error-sanitization.md

@@ -0,0 +1,5 @@
+---
+'@modelcontextprotocol/server': minor
+---
+
+Add ToolError class for secure-by-default tool error handling. Unhandled errors from tool handlers are now sanitized to "Internal error" instead of exposing raw messages. Use `throw new ToolError('message')` when you want clients to see a specific error message.

docs/migration.md

@@ -870,6 +870,26 @@
 import { CfWorkerJsonSchemaValidator } from '@modelcontextprotocol/server/validators/cf-worker';
 ```
 
+## Tool error sanitization
+
+Tool handlers that `throw new Error('message')` will now return `"Internal error"` to clients instead of the raw error message. This prevents accidental leakage of server internals (hostnames, connection strings, stack traces).
+
+To send a user-visible error message, use the new `ToolError` class:
+
+```typescript
+import { ToolError } from '@modelcontextprotocol/server';
+
+server.registerTool('my-tool', {}, async () => {
+    // Client sees: "Internal error"
+    throw new Error('DB connection failed at 10.0.0.5:5432');
+
+    // Client sees: "Invalid country"
+    throw new ToolError('Invalid country');
+});
+```
+
+`ProtocolError` messages (SDK validation errors) are still passed through unchanged.
+
 ## Unchanged APIs
 
 The following APIs are unchanged between v1 and v2 (only the import paths changed):

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

@@ -45,6 +45,21 @@ import { getCompleter, isCompletable } from './completable.js';
 import type { ServerOptions } from './server.js';
 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';
+    }
+}
+
 /**
  * High-level MCP server that provides a simpler API for working with resources, tools, and prompts.
  * For advanced usage (like sending notifications or setting custom request handlers), use the underlying
@@ -209,7 +224,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'
                 }
             ]);
         });
@@ -6971,8 +7076,9 @@ describe('Zod v4', () => {
             });
 
             // Should receive an error since cancelled tasks don't have results
+            expect(result.isError).toBe(true);
             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();