address review: changeset, move ToolError, migration docs, test nit

1. Add minor changeset for @modelcontextprotocol/server
2. Move ToolError class above McpServer JSDoc so generated docs
   aren't orphaned
3. Add migration.md entry explaining the breaking change for v1
   authors who throw raw Error expecting clients to see the message
4. Add expect(result.isError).toBe(true) to cancellation test

Author: claygeo

.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 { AjvJsonSchemaValidator } from '@modelcontextprotocol/server';
 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/server/mcp.ts

@@ -45,20 +45,6 @@ import { getCompleter, isCompletable } from './completable.js';
 import type { ServerOptions } from './server.js';
 import { Server } from './server.js';
 
-/**
- * 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
- * {@linkcode Server} instance available via the {@linkcode McpServer.server | server} property.
- *
- * @example
- * ```ts source="./mcp.examples.ts#McpServer_basicUsage"
- * const server = new McpServer({
- *     name: 'my-server',
- *     version: '1.0.0'
- * });
- * ```
- */
-
 /**
  * Error class for tool handlers to throw when they want to send a
  * user-visible error message to the client. Unlike regular errors,
@@ -74,6 +60,19 @@ export class ToolError extends Error {
     }
 }
 
+/**
+ * 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
+ * {@linkcode Server} instance available via the {@linkcode McpServer.server | server} property.
+ *
+ * @example
+ * ```ts source="./mcp.examples.ts#McpServer_basicUsage"
+ * const server = new McpServer({
+ *     name: 'my-server',
+ *     version: '1.0.0'
+ * });
+ * ```
+ */
 export class McpServer {
     /**
      * The underlying {@linkcode Server} instance, useful for advanced operations like sending notifications.

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

@@ -7076,6 +7076,7 @@ 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: 'Internal error' }]);