feat!: remove WebSocketClientTransport (#1783)

Co-authored-by: Konstantin Konstantinov <KKonstantinov@users.noreply.github.com>

Author: felixweinberger

.changeset/remove-websocket-transport.md

@@ -0,0 +1,5 @@
+---
+'@modelcontextprotocol/client': major
+---
+
+Remove `WebSocketClientTransport`. WebSocket is not a spec-defined transport; use stdio or Streamable HTTP. The `Transport` interface remains exported for custom implementations. See #142.

docs/migration-SKILL.md

@@ -43,7 +43,7 @@ Replace all `@modelcontextprotocol/sdk/...` imports using this table.
 | `@modelcontextprotocol/sdk/client/streamableHttp.js` | `@modelcontextprotocol/client` |
 | `@modelcontextprotocol/sdk/client/sse.js`            | `@modelcontextprotocol/client` |
 | `@modelcontextprotocol/sdk/client/stdio.js`          | `@modelcontextprotocol/client` |
-| `@modelcontextprotocol/sdk/client/websocket.js`      | `@modelcontextprotocol/client` |
+| `@modelcontextprotocol/sdk/client/websocket.js`      | REMOVED (use Streamable HTTP or stdio; implement `Transport` for custom needs) |
 
 ### Server imports
 
@@ -96,6 +96,7 @@ Notes:
 | `ErrorCode.RequestTimeout`               | `SdkErrorCode.RequestTimeout`                            |
 | `ErrorCode.ConnectionClosed`             | `SdkErrorCode.ConnectionClosed`                          |
 | `StreamableHTTPError`                    | REMOVED (use `SdkError` with `SdkErrorCode.ClientHttp*`) |
+| `WebSocketClientTransport`               | REMOVED (use `StreamableHTTPClientTransport` or `StdioClientTransport`) |
 
 All other symbols from `@modelcontextprotocol/sdk/types.js` retain their original names (e.g., `CallToolResultSchema`, `ListToolsResultSchema`, etc.).
 

docs/migration.md

@@ -110,6 +110,26 @@ const transport = new NodeStreamableHTTPServerTransport({ sessionIdGenerator: ()
 
 The SSE transport has been removed from the server. Servers should migrate to Streamable HTTP. The client-side SSE transport remains available for connecting to legacy SSE servers.
 
+### `WebSocketClientTransport` removed
+
+`WebSocketClientTransport` has been removed. WebSocket is not a spec-defined MCP transport, and keeping it in the SDK encouraged transport proliferation without a conformance baseline.
+
+Use `StdioClientTransport` for local servers or `StreamableHTTPClientTransport` for remote servers. If you need WebSocket for a custom deployment, implement the `Transport` interface directly — it remains exported from `@modelcontextprotocol/client`.
+
+**Before (v1):**
+
+```typescript
+import { WebSocketClientTransport } from '@modelcontextprotocol/sdk/client/websocket.js';
+const transport = new WebSocketClientTransport(new URL('ws://localhost:3000'));
+```
+
+**After (v2):**
+
+```typescript
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
+const transport = new StreamableHTTPClientTransport(new URL('http://localhost:3000/mcp'));
+```
+
 ### Server auth removed
 
 Server-side OAuth/auth has been removed entirely from the SDK. This includes `mcpAuthRouter`, `OAuthServerProvider`, `OAuthTokenVerifier`, `requireBearerAuth`, `authenticateClient`, `ProxyOAuthServerProvider`, `allowedMethods`, and all associated types.

package.json

@@ -60,7 +60,6 @@
         "@types/express-serve-static-core": "catalog:devTools",
         "@types/node": "^24.10.1",
         "@types/supertest": "catalog:devTools",
-        "@types/ws": "catalog:devTools",
         "@typescript/native-preview": "catalog:devTools",
         "eslint": "catalog:devTools",
         "eslint-config-prettier": "catalog:devTools",
@@ -75,7 +74,6 @@
         "typescript": "catalog:devTools",
         "typescript-eslint": "catalog:devTools",
         "vitest": "catalog:devTools",
-        "ws": "catalog:devTools",
         "zod": "catalog:runtimeShared"
     },
     "resolutions": {

packages/client/src/client/websocket.ts

@@ -69,7 +69,6 @@ export type {
     StreamableHTTPReconnectionOptions
 } from './client/streamableHttp.js';
 export { StreamableHTTPClientTransport } from './client/streamableHttp.js';
-export { WebSocketClientTransport } from './client/websocket.js';
 
 // experimental exports
 export { ExperimentalClientTasks } from './experimental/tasks/client.js';

packages/client/src/index.ts

@@ -18,7 +18,6 @@ catalogs:
         '@types/express': ^5.0.6
         '@types/express-serve-static-core': ^5.1.0
         '@types/supertest': ^6.0.2
-        '@types/ws': ^8.5.12
         '@typescript/native-preview': ^7.0.0-dev.20251217.1
         eslint: ^9.39.2
         eslint-config-prettier: ^10.1.8
@@ -32,7 +31,6 @@ catalogs:
         typescript-eslint: ^8.48.1
         vite-tsconfig-paths: ^5.1.4
         vitest: ^4.0.15
-        ws: ^8.18.0
     runtimeClientOnly:
         cross-spawn: ^7.0.5
         eventsource: ^3.0.2

pnpm-lock.yaml

@@ -1,13 +1,7 @@
-import WebSocket from 'ws';
-
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-(global as any).WebSocket = WebSocket;
-
 import express from 'express';
 import { Client } from '../src/client/index.js';
 import { SSEClientTransport } from '../src/client/sse.js';
 import { StdioClientTransport } from '../src/client/stdio.js';
-import { WebSocketClientTransport } from '../src/client/websocket.js';
 import { Server } from '../src/server/index.js';
 import { SSEServerTransport } from '../src/server/sse.js';
 import { StdioServerTransport } from '../src/server/stdio.js';
@@ -38,7 +32,7 @@ async function runClient(url_or_command: string, args: string[]) {
     if (url?.protocol === 'http:' || url?.protocol === 'https:') {
         clientTransport = new SSEClientTransport(new URL(url_or_command));
     } else if (url?.protocol === 'ws:' || url?.protocol === 'wss:') {
-        clientTransport = new WebSocketClientTransport(new URL(url_or_command));
+        throw new Error('WebSocket URLs are no longer supported. Use http(s) or stdio instead.');
     } else {
         clientTransport = new StdioClientTransport({
             command: url_or_command,